Pod/HTML.pm

filter: Statementstmt 83.3% 10 / 12 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 4 / 4 Podpod n/a totaltotal 87.5% 14 / 16 CC 1 SCAR 0.7
CC
1
Cov
83%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
« Pod.pm ↑ Summary Pod/Text.pm »
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;
« Pod.pm ↑ Summary Pod/Text.pm »