Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Pod::Simple::HTML.3pm

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