Debian Codegraph @

upstream/debian-unstable/man3/Pod::Simple::HTML.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Pod::Simple::HTML 3perl"
58 .TH Pod::Simple::HTML 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Pod::Simple::HTML \- convert Pod to HTML
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& perl \-MPod::Simple::HTML \-e Pod::Simple::HTML::go thingy.pod
69 .Ve
70 .SH DESCRIPTION
71 .IX Header "DESCRIPTION"
72 This class is for making an HTML rendering of a Pod document.
73 .PP
74 This is a subclass of Pod::Simple::PullParser and inherits all its
75 methods (and options).
76 .PP
77 Note that if you want to do a batch conversion of a lot of Pod
78 documents to HTML, you should see the module Pod::Simple::HTMLBatch.
79 .SH "CALLING FROM THE COMMAND LINE"
80 .IX Header "CALLING FROM THE COMMAND LINE"
81 TODO
82 .PP
83 .Vb 1
84 \& perl \-MPod::Simple::HTML \-e Pod::Simple::HTML::go Thing.pod Thing.html
85 .Ve
86 .SH "CALLING FROM PERL"
87 .IX Header "CALLING FROM PERL"
88 .SS "Minimal code"
89 .IX Subsection "Minimal code"
90 .Vb 6
91 \& use Pod::Simple::HTML;
92 \& my $p = Pod::Simple::HTML\->new;
93 \& $p\->output_string(\emy $html);
94 \& $p\->parse_file(\*(Aqpath/to/Module/Name.pm\*(Aq);
95 \& open my $out, \*(Aq>\*(Aq, \*(Aqout.html\*(Aq or die "Cannot open \*(Aqout.html\*(Aq: $!\en";
96 \& print $out $html;
97 .Ve
98 .SS "More detailed example"
99 .IX Subsection "More detailed example"
100 .Vb 1
101 \& use Pod::Simple::HTML;
102 .Ve
103 .PP
104 Set the content type:
105 .PP
106 .Vb 1
107 \& $Pod::Simple::HTML::Content_decl = q{<meta http\-equiv="Content\-Type" content="text/html; charset=UTF\-8" >};
108 \&
109 \& my $p = Pod::Simple::HTML\->new;
110 .Ve
111 .PP
112 Include a single javascript source:
113 .PP
114 .Vb 1
115 \& $p\->html_javascript(\*(Aqhttp://abc.com/a.js\*(Aq);
116 .Ve
117 .PP
118 Or insert multiple javascript source in the header
119 (or for that matter include anything, thought this is not recommended)
120 .PP
121 .Vb 3
122 \& $p\->html_javascript(\*(Aq
123 \& <script type="text/javascript" src="http://abc.com/b.js"></script>
124 \& <script type="text/javascript" src="http://abc.com/c.js"></script>\*(Aq);
125 .Ve
126 .PP
127 Include a single css source in the header:
128 .PP
129 .Vb 1
130 \& $p\->html_css(\*(Aq/style.css\*(Aq);
131 .Ve
132 .PP
133 or insert multiple css sources:
134 .PP
135 .Vb 3
136 \& $p\->html_css(\*(Aq
137 \& <link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://remote.server.com/jquery.css">
138 \& <link rel="stylesheet" type="text/css" title="pod_stylesheet" href="/style.css">\*(Aq);
139 .Ve
140 .PP
141 Tell the parser where should the output go. In this case it will be placed in the \f(CW$html\fR variable:
142 .PP
143 .Vb 2
144 \& my $html;
145 \& $p\->output_string(\e$html);
146 .Ve
147 .PP
148 Parse and process a file with pod in it:
149 .PP
150 .Vb 1
151 \& $p\->parse_file(\*(Aqpath/to/Module/Name.pm\*(Aq);
152 .Ve
153 .SH METHODS
154 .IX Header "METHODS"
155 TODO
156 all (most?) accessorized methods
157 .PP
158 The following variables need to be set \fBbefore\fR the call to the \->new constructor.
159 .PP
160 Set the string that is included before the opening <html> tag:
161 .PP
162 .Vb 2
163 \& $Pod::Simple::HTML::Doctype_decl = qq{<!DOCTYPE HTML PUBLIC "\-//W3C//DTD HTML 4.01 Transitional//EN"
164 \& "http://www.w3.org/TR/html4/loose.dtd">\en};
165 .Ve
166 .PP
167 Set the content-type in the HTML head: (defaults to ISO\-8859\-1)
168 .PP
169 .Vb 1
170 \& $Pod::Simple::HTML::Content_decl = q{<meta http\-equiv="Content\-Type" content="text/html; charset=UTF\-8" >};
171 .Ve
172 .PP
173 Set the value that will be embedded in the opening tags of F, C tags and verbatim text.
174 F maps to <em>, C maps to <code>, Verbatim text maps to <pre> (Computerese defaults to "")
175 .PP
176 .Vb 1
177 \& $Pod::Simple::HTML::Computerese = \*(Aq class="some_class_name\*(Aq;
178 .Ve
179 .SS html_css
180 .IX Subsection "html_css"
181 .SS html_javascript
182 .IX Subsection "html_javascript"
183 .SS title_prefix
184 .IX Subsection "title_prefix"
185 .SS title_postfix
186 .IX Subsection "title_postfix"
187 .SS html_header_before_title
188 .IX Subsection "html_header_before_title"
189 This includes everything before the <title> opening tag including the Document type
190 and including the opening <title> tag. The following call will set it to be a simple HTML
191 file:
192 .PP
193 .Vb 1
194 \& $p\->html_header_before_title(\*(Aq<html><head><title>\*(Aq);
195 .Ve
196 .SS top_anchor
197 .IX Subsection "top_anchor"
198 By default Pod::Simple::HTML adds a dummy anchor at the top of the HTML.
199 You can change it by calling
200 .PP
201 .Vb 1
202 \& $p\->top_anchor(\*(Aq<a name="zz" >\*(Aq);
203 .Ve
204 .SS html_h_level
205 .IX Subsection "html_h_level"
206 Normally =head1 will become <h1>, =head2 will become <h2> etc.
207 Using the html_h_level method will change these levels setting the h level
208 of =head1 tags:
209 .PP
210 .Vb 1
211 \& $p\->html_h_level(3);
212 .Ve
213 .PP
214 Will make sure that =head1 will become <h3> and =head2 will become <h4> etc...
215 .SS index
216 .IX Subsection "index"
217 Set it to some true value if you want to have an index (in reality a table of contents)
218 to be added at the top of the generated HTML.
219 .PP
220 .Vb 1
221 \& $p\->index(1);
222 .Ve
223 .SS html_header_after_title
224 .IX Subsection "html_header_after_title"
225 Includes the closing tag of </title> and through the rest of the head
226 till the opening of the body
227 .PP
228 .Vb 1
229 \& $p\->html_header_after_title(\*(Aq</title>...</head><body id="my_id">\*(Aq);
230 .Ve
231 .SS html_footer
232 .IX Subsection "html_footer"
233 The very end of the document:
234 .PP
235 .Vb 1
236 \& $p\->html_footer( qq[\en<!\-\- end doc \-\->\en\en</body></html>\en] );
237 .Ve
238 .SH SUBCLASSING
239 .IX Header "SUBCLASSING"
240 Can use any of the methods described above but for further customization
241 one needs to override some of the methods:
242 .PP
243 .Vb 3
244 \& package My::Pod;
245 \& use strict;
246 \& use warnings;
247 \&
248 \& use base \*(AqPod::Simple::HTML\*(Aq;
249 \&
250 \& # needs to return a URL string such
251 \& # http://some.other.com/page.html
252 \& # #anchor_in_the_same_file
253 \& # /internal/ref.html
254 \& sub do_pod_link {
255 \& # My::Pod object and Pod::Simple::PullParserStartToken object
256 \& my ($self, $link) = @_;
257 \&
258 \& say $link\->tagname; # will be L for links
259 \& say $link\->attr(\*(Aqto\*(Aq); #
260 \& say $link\->attr(\*(Aqtype\*(Aq); # will be \*(Aqpod\*(Aq always
261 \& say $link\->attr(\*(Aqsection\*(Aq);
262 \&
263 \& # Links local to our web site
264 \& if ($link\->tagname eq \*(AqL\*(Aq and $link\->attr(\*(Aqtype\*(Aq) eq \*(Aqpod\*(Aq) {
265 \& my $to = $link\->attr(\*(Aqto\*(Aq);
266 \& if ($to =~ /^Padre::/) {
267 \& $to =~ s{::}{/}g;
268 \& return "/docs/Padre/$to.html";
269 \& }
270 \& }
271 \&
272 \& # all other links are generated by the parent class
273 \& my $ret = $self\->SUPER::do_pod_link($link);
274 \& return $ret;
275 \& }
276 \&
277 \& 1;
278 .Ve
279 .PP
280 Meanwhile in script.pl:
281 .PP
282 .Vb 1
283 \& use My::Pod;
284 \&
285 \& my $p = My::Pod\->new;
286 \&
287 \& my $html;
288 \& $p\->output_string(\e$html);
289 \& $p\->parse_file(\*(Aqpath/to/Module/Name.pm\*(Aq);
290 \& open my $out, \*(Aq>\*(Aq, \*(Aqout.html\*(Aq or die;
291 \& print $out $html;
292 .Ve
293 .PP
294 TODO
295 .PP
296 maybe override do_beginning do_end
297 .SH "SEE ALSO"
298 .IX Header "SEE ALSO"
299 Pod::Simple, Pod::Simple::HTMLBatch
300 .PP
301 TODO: a corpus of sample Pod input and HTML output? Or common
302 idioms?
303 .SH SUPPORT
304 .IX Header "SUPPORT"
305 Questions or discussion about POD and Pod::Simple should be sent to the
306 pod\[email protected] mail list. Send an empty email to
307 pod\-people\[email protected] to subscribe.
308 .PP
309 This module is managed in an open GitHub repository,
310 <https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or
311 to clone <https://github.com/perl\-pod/pod\-simple.git> and send patches!
312 .PP
313 Patches against Pod::Simple are welcome. Please send bug reports to
314 <bug\-pod\[email protected]>.
315 .SH "COPYRIGHT AND DISCLAIMERS"
316 .IX Header "COPYRIGHT AND DISCLAIMERS"
317 Copyright (c) 2002\-2004 Sean M. Burke.
318 .PP
319 This library is free software; you can redistribute it and/or modify it
320 under the same terms as Perl itself.
321 .PP
322 This program is distributed in the hope that it will be useful, but
323 without any warranty; without even the implied warranty of
324 merchantability or fitness for a particular purpose.
325 .SH ACKNOWLEDGEMENTS
326 .IX Header "ACKNOWLEDGEMENTS"
327 Thanks to Hurricane Electric <http://he.net/> for permission to use its
328 Linux man pages online <http://man.he.net/> site for man page links.
329 .PP
330 Thanks to search.cpan.org <http://search.cpan.org/> for permission to use the
331 site for Perl module links.
332 .SH AUTHOR
333 .IX Header "AUTHOR"
334 Pod::Simple was created by Sean M. Burke <[email protected]>.
335 But don't bother him, he's retired.
336 .PP
337 Pod::Simple is maintained by:
338 .IP \(bu 4
339 Allison Randal \f(CW\*(C`[email protected]\*(C'\fR
340 .IP \(bu 4
341 Hans Dieter Pearcey \f(CW\*(C`[email protected]\*(C'\fR
342 .IP \(bu 4
343 David E. Wheeler \f(CW\*(C`[email protected]\*(C'\fR