| 1 | package Apache::Pod::HTML; | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | Apache::Pod::HTML - base class for converting Pod files to prettier forms | ||
| 6 | |||
| 7 | =cut | ||
| 8 | |||
| 9 | 3 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | 3 | ▶ | use vars qw( $VERSION ); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 11 | |||
| 12 | $VERSION = '0.22'; | ||
| 13 | |||
| 14 | =head1 VERSION | ||
| 15 | |||
| 16 | Version 0.22 | ||
| 17 | |||
| 18 | =cut | ||
| 19 | |||
| 20 | 3 | ▶ | use Apache::Pod; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 21 | 0 | ▶ | use Apache::Constants; |
|
Subroutine
BEGIN: called CC=1 SCAR=2.6
| |||
| 22 | use URI::Escape; | ||
| 23 | |||
| 24 | =head1 SYNOPSIS | ||
| 25 | |||
| 26 | A simple mod_perl handler to easily convert Pod to HTML or other forms. | ||
| 27 | You can also emulate F<perldoc>. | ||
| 28 | |||
| 29 | =head1 CONFIGURATION | ||
| 30 | |||
| 31 | =head2 Pod-to-HTML conversion | ||
| 32 | |||
| 33 | Add the following lines to your F<httpd.conf>. | ||
| 34 | |||
| 35 | <Files *.pod> | ||
| 36 | SetHandler perl-script | ||
| 37 | PerlHandler Apache::Pod::HTML | ||
| 38 | </Files> | ||
| 39 | |||
| 40 | All F<*.pod> files will magically be converted to HTML. | ||
| 41 | |||
| 42 | =head2 F<perldoc> emulation | ||
| 43 | |||
| 44 | The following configuration should go in your httpd.conf | ||
| 45 | |||
| 46 | <Location /perldoc> | ||
| 47 | SetHandler perl-script | ||
| 48 | PerlHandler Apache::Pod::HTML | ||
| 49 | PerlSetVar STYLESHEET auto | ||
| 50 | PerlSetVar LINKBASE http://www.example.com/docs/ | ||
| 51 | </Location> | ||
| 52 | |||
| 53 | You can then get documentation for a module C<Foo::Bar> at the URL | ||
| 54 | C<http://your.server.com/perldoc/Foo::Bar> | ||
| 55 | |||
| 56 | Note that you can also get the standard Perl documentation with URLs | ||
| 57 | like C<http://your.server.com/perldoc/perlfunc> or just | ||
| 58 | C<http://your.server.com/perldoc> for the main Perl docs. | ||
| 59 | |||
| 60 | Finally, you can search for a particular Perl keyword with | ||
| 61 | C<http://your.server.com/perldoc/f/keyword> The 'f' is used by analogy | ||
| 62 | with the C<-f> flag to C<perldoc>. | ||
| 63 | |||
| 64 | =head1 CONFIGURATION VARIABLES | ||
| 65 | |||
| 66 | =head2 STYLESHEET | ||
| 67 | |||
| 68 | Specifies the stylesheet to use with the output HTML file. | ||
| 69 | |||
| 70 | <Location /perldoc> | ||
| 71 | SetHandler perl-script | ||
| 72 | PerlHandler Apache::Pod::HTML | ||
| 73 | PerlSetVar STYLESHEET auto | ||
| 74 | </Location> | ||
| 75 | |||
| 76 | Specifying 'auto' for the stylesheet will cause the built-in CSS | ||
| 77 | stylesheet to be used. If you prefer, you can replace the word 'auto' | ||
| 78 | with the URL of your own custom stylesheet file. | ||
| 79 | |||
| 80 | =head2 INDEX | ||
| 81 | |||
| 82 | When INDEX is true, a table of contents is added at the top of the | ||
| 83 | HTML document. | ||
| 84 | |||
| 85 | <Files *.pod> | ||
| 86 | SetHandler perl-script | ||
| 87 | PerlHandler Apache::Pod::HTML | ||
| 88 | PerlSetVar INDEX 1 | ||
| 89 | </Files> | ||
| 90 | |||
| 91 | By default, this is off. | ||
| 92 | |||
| 93 | =head2 GZIP | ||
| 94 | |||
| 95 | When GZIP is true, the whole HTTP body is compressed. The user's browser must | ||
| 96 | accept gzip, and L<Compress::Zlib> must be available. Otherwise, GZIP is ignored. | ||
| 97 | |||
| 98 | <Files *.pod> | ||
| 99 | SetHandler perl-script | ||
| 100 | PerlHandler Apache::Pod::HTML | ||
| 101 | PerlSetVar GZIP 1 | ||
| 102 | </Files> | ||
| 103 | |||
| 104 | By default, this is off. | ||
| 105 | |||
| 106 | =head2 LINKBASE | ||
| 107 | |||
| 108 | Specifying an optional C<LINKBASE> variable changes the external | ||
| 109 | HTTP links to use a URL prefix of your specification instead of using | ||
| 110 | L<Pod::Simple::HTML>'s default. Using the magic word C<LOCAL> will make | ||
| 111 | links local instead of external. | ||
| 112 | |||
| 113 | =cut | ||
| 114 | |||
| 115 | sub handler { | ||
| 116 | my $r = shift; | ||
| 117 | |||
| 118 | if ( $r->path_info eq '/auto.css' ) { | ||
| 119 | $r->content_type( 'text/css' ); | ||
| 120 | $r->send_http_header; | ||
| 121 | $r->print( _css() ); | ||
| 122 | return OK; | ||
| 123 | } | ||
| 124 | |||
| 125 | my $body; | ||
| 126 | my $file = Apache::Pod::getpodfile( $r ); | ||
| 127 | |||
| 128 | if ( $file ) { | ||
| 129 | my $parser = Pod::Simple::HTML->new; | ||
| 130 | $parser->no_errata_section(1); | ||
| 131 | $parser->complain_stderr(1); | ||
| 132 | $parser->output_string( \$body ); | ||
| 133 | $parser->index( $r->dir_config('INDEX') ); | ||
| 134 | if ( my $prefix = $r->dir_config('LINKBASE') ) { | ||
| 135 | if ( $prefix eq 'LOCAL' ) { | ||
| 136 | $prefix = $r->location . '/'; | ||
| 137 | } | ||
| 138 | $parser->perldoc_url_prefix( $prefix ); | ||
| 139 | } | ||
| 140 | $parser->parse_file( $file ); | ||
| 141 | # TODO: Send the timestamp of the file in the header | ||
| 142 | |||
| 143 | my $stylesheet = $r->dir_config('STYLESHEET') || ''; | ||
| 144 | $stylesheet = $r->location . '/auto.css' if $stylesheet =~ /^auto/i; | ||
| 145 | if ( $stylesheet ) { | ||
| 146 | # Stick in a link to our stylesheet | ||
| 147 | $stylesheet = qq(<LINK REL="stylesheet" HREF="$stylesheet" TYPE="text/css">); | ||
| 148 | $body =~ s{(?=</head)}{$stylesheet\n}i; | ||
| 149 | } | ||
| 150 | if ( $r->dir_config('GZIP') && ($r->header_in('Accept-Encoding') =~ /gzip/) ) { | ||
| 151 | local $@; | ||
| 152 | eval { | ||
| 153 | require Compress::Zlib; | ||
| 154 | $body = Compress::Zlib::memGzip( $body ); | ||
| 155 | $r->header_out('Content-Encoding','gzip'); | ||
| 156 | }; | ||
| 157 | } | ||
| 158 | } else { | ||
| 159 | $body = "<HTML><HEAD><TITLE>Not found</TITLE></HEAD><BODY>That module doesn't exist</BODY></HTML>"; | ||
| 160 | } | ||
| 161 | |||
| 162 | $r->content_type('text/html'); | ||
| 163 | $r->send_http_header; | ||
| 164 | $r->print( $body ); | ||
| 165 | |||
| 166 | return OK; | ||
| 167 | } | ||
| 168 | |||
| 169 | sub _css { | ||
| 170 | return <<'EOF'; | ||
| 171 | BODY { | ||
| 172 | background: white; | ||
| 173 | color: black; | ||
| 174 | font-family: times,serif; | ||
| 175 | margin: 0; | ||
| 176 | padding: 1ex; | ||
| 177 | } | ||
| 178 | |||
| 179 | TABLE { | ||
| 180 | border-collapse: collapse; | ||
| 181 | border-spacing: 0; | ||
| 182 | border-width: 0; | ||
| 183 | color: inherit; | ||
| 184 | } | ||
| 185 | |||
| 186 | A:link, A:visited { | ||
| 187 | background: transparent; | ||
| 188 | color: #006699; | ||
| 189 | } | ||
| 190 | |||
| 191 | PRE { | ||
| 192 | background: #eeeeee; | ||
| 193 | border: 1px solid #888888; | ||
| 194 | color: black; | ||
| 195 | padding-top: 1em; | ||
| 196 | padding-bottom: 1em; | ||
| 197 | white-space: pre; | ||
| 198 | } | ||
| 199 | |||
| 200 | H1 { | ||
| 201 | background: transparent; | ||
| 202 | color: #006699; | ||
| 203 | font-size: x-large; | ||
| 204 | font-family: tahoma,sans-serif; | ||
| 205 | } | ||
| 206 | |||
| 207 | H2 { | ||
| 208 | background: transparent; | ||
| 209 | color: #006699; | ||
| 210 | font-size: large; | ||
| 211 | font-family: tahoma,sans-serif; | ||
| 212 | } | ||
| 213 | |||
| 214 | .block { | ||
| 215 | background: transparent; | ||
| 216 | } | ||
| 217 | |||
| 218 | TD .block { | ||
| 219 | color: #006699; | ||
| 220 | background: #dddddd; | ||
| 221 | padding: 0.2em; | ||
| 222 | font-size: large; | ||
| 223 | } | ||
| 224 | |||
| 225 | HR { | ||
| 226 | display: none; | ||
| 227 | } | ||
| 228 | EOF | ||
| 229 | } | ||
| 230 | |||
| 231 | package My::Pod::Simple::HTML; | ||
| 232 | |||
| 233 | use Pod::Simple::HTML; | ||
| 234 | |||
| 235 | our @ISA = qw( Pod::Simple::HTML ); | ||
| 236 | |||
| 237 | *VERSION = *Pod::Simple::HTML::VERSION; | ||
| 238 | |||
| 239 | sub resolve_pod_page_link { | ||
| 240 | my $self = shift; | ||
| 241 | my $to = shift; | ||
| 242 | my $section = shift; | ||
| 243 | |||
| 244 | my $link = $to; | ||
| 245 | |||
| 246 | return uri_escape( $link ); | ||
| 247 | } | ||
| 248 | |||
| 249 | =head1 AUTHOR | ||
| 250 | |||
| 251 | Andy Lester C<< <andy@petdance.com> >>, adapted from Apache::Perldoc by | ||
| 252 | Rich Bowen C<< <rbowen@ApacheAdmin.com> >> | ||
| 253 | |||
| 254 | =head1 LICENSE | ||
| 255 | |||
| 256 | This package is licensed under the same terms as Perl itself. | ||
| 257 | |||
| 258 | =cut | ||
| 259 | |||
| 260 | 1; | ||