1Pod::Simple::XHTML(3) User Contributed Perl DocumentationPod::Simple::XHTML(3)
2
3
4

NAME

6       Pod::Simple::XHTML -- format Pod as validating XHTML
7

SYNOPSIS

9         use Pod::Simple::XHTML;
10
11         my $parser = Pod::Simple::XHTML->new();
12
13         ...
14
15         $parser->parse_file('path/to/file.pod');
16

DESCRIPTION

18       This class is a formatter that takes Pod and renders it as XHTML
19       validating HTML.
20
21       This is a subclass of Pod::Simple::Methody and inherits all its
22       methods. The implementation is entirely different than
23       Pod::Simple::HTML, but it largely preserves the same interface.
24
25   Minimal code
26         use Pod::Simple::XHTML;
27         my $psx = Pod::Simple::XHTML->new;
28         $psx->output_string(\my $html);
29         $psx->parse_file('path/to/Module/Name.pm');
30         open my $out, '>', 'out.html' or die "Cannot open 'out.html': $!\n";
31         print $out $html;
32
33       You can also control the character encoding and entities. For example,
34       if you're sure that the POD is properly encoded (using the "=encoding"
35       command), you can prevent high-bit characters from being encoded as
36       HTML entities and declare the output character set as UTF-8 before
37       parsing, like so:
38
39         $psx->html_charset('UTF-8');
40         $psx->html_encode_chars(q{&<>'"});
41

METHODS

43       Pod::Simple::XHTML offers a number of methods that modify the format of
44       the HTML output. Call these after creating the parser object, but
45       before the call to "parse_file":
46
47         my $parser = Pod::PseudoPod::HTML->new();
48         $parser->set_optional_param("value");
49         $parser->parse_file($file);
50
51   perldoc_url_prefix
52       In turning Foo::Bar into http://whatever/Foo%3a%3aBar, what to put
53       before the "Foo%3a%3aBar". The default value is
54       "https://metacpan.org/pod/".
55
56   perldoc_url_postfix
57       What to put after "Foo%3a%3aBar" in the URL. This option is not set by
58       default.
59
60   man_url_prefix
61       In turning crontab(5) into http://whatever/man/1/crontab, what to put
62       before the "1/crontab". The default value is "http://man.he.net/man".
63
64   man_url_postfix
65       What to put after "1/crontab" in the URL. This option is not set by
66       default.
67
68   title_prefix, title_postfix
69       What to put before and after the title in the head. The values should
70       already be &-escaped.
71
72   html_css
73         $parser->html_css('path/to/style.css');
74
75       The URL or relative path of a CSS file to include. This option is not
76       set by default.
77
78   html_javascript
79       The URL or relative path of a JavaScript file to pull in. This option
80       is not set by default.
81
82   html_doctype
83       A document type tag for the file. This option is not set by default.
84
85   html_charset
86       The character set to declare in the Content-Type meta tag created by
87       default for "html_header_tags". Note that this option will be ignored
88       if the value of "html_header_tags" is changed. Defaults to
89       "ISO-8859-1".
90
91   html_header_tags
92       Additional arbitrary HTML tags for the header of the document. The
93       default value is just a content type header tag:
94
95         <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
96
97       Add additional meta tags here, or blocks of inline CSS or JavaScript
98       (wrapped in the appropriate tags).
99
100       html_encode_chars
101
102       A string containing all characters that should be encoded as HTML
103       entities, specified using the regular expression character class syntax
104       (what you find within brackets in regular expressions). This value will
105       be passed as the second argument to the "encode_entities" function of
106       HTML::Entities. If HTML::Entities is not installed, then any characters
107       other than "&<""'> will be encoded numerically.
108
109   html_h_level
110       This is the level of HTML "Hn" element to which a Pod "head1"
111       corresponds.  For example, if "html_h_level" is set to 2, a head1 will
112       produce an H2, a head2 will produce an H3, and so on.
113
114   default_title
115       Set a default title for the page if no title can be determined from the
116       content. The value of this string should already be &-escaped.
117
118   force_title
119       Force a title for the page (don't try to determine it from the
120       content).  The value of this string should already be &-escaped.
121
122   html_header, html_footer
123       Set the HTML output at the beginning and end of each file. The default
124       header includes a title, a doctype tag (if "html_doctype" is set), a
125       content tag (customized by "html_header_tags"), a tag for a CSS file
126       (if "html_css" is set), and a tag for a Javascript file (if
127       "html_javascript" is set). The default footer simply closes the "html"
128       and "body" tags.
129
130       The options listed above customize parts of the default header, but
131       setting "html_header" or "html_footer" completely overrides the built-
132       in header or footer. These may be useful if you want to use template
133       tags instead of literal HTML headers and footers or are integrating
134       converted POD pages in a larger website.
135
136       If you want no headers or footers output in the HTML, set these options
137       to the empty string.
138
139   index
140       Whether to add a table-of-contents at the top of each page (called an
141       index for the sake of tradition).
142
143   anchor_items
144       Whether to anchor every definition "=item" directive. This needs to be
145       enabled if you want to be able to link to specific "=item" directives,
146       which are output as "<dt>" elements. Disabled by default.
147
148   backlink
149       Whether to turn every =head1 directive into a link pointing to the top
150       of the page (specifically, the opening body tag).
151

SUBCLASSING

153       If the standard options aren't enough, you may want to subclass
154       Pod::Simple::XHMTL. These are the most likely candidates for methods
155       you'll want to override when subclassing.
156
157   handle_text
158       This method handles the body of text within any element: it's the body
159       of a paragraph, or everything between a "=begin" tag and the
160       corresponding "=end" tag, or the text within an L entity, etc. You
161       would want to override this if you are adding a custom element type
162       that does more than just display formatted text. Perhaps adding a way
163       to generate HTML tables from an extended version of POD.
164
165       So, let's say you want to add a custom element called 'foo'. In your
166       subclass's "new" method, after calling "SUPER::new" you'd call:
167
168         $new->accept_targets_as_text( 'foo' );
169
170       Then override the "start_for" method in the subclass to check for when
171       "$flags->{'target'}" is equal to 'foo' and set a flag that marks that
172       you're in a foo block (maybe "$self->{'in_foo'} = 1"). Then override
173       the "handle_text" method to check for the flag, and pass $text to your
174       custom subroutine to construct the HTML output for 'foo' elements,
175       something like:
176
177         sub handle_text {
178             my ($self, $text) = @_;
179             if ($self->{'in_foo'}) {
180                 $self->{'scratch'} .= build_foo_html($text);
181                 return;
182             }
183             $self->SUPER::handle_text($text);
184         }
185
186   handle_code
187       This method handles the body of text that is marked up to be code.  You
188       might for instance override this to plug in a syntax highlighter.  The
189       base implementation just escapes the text.
190
191       The callback methods "start_code" and "end_code" emits the "code" tags
192       before and after "handle_code" is invoked, so you might want to
193       override these together with "handle_code" if this wrapping isn't
194       suitable.
195
196       Note that the code might be broken into multiple segments if there are
197       nested formatting codes inside a "C<...>" sequence.  In between the
198       calls to "handle_code" other markup tags might have been emitted in
199       that case.  The same is true for verbatim sections if the
200       "codes_in_verbatim" option is turned on.
201
202   accept_targets_as_html
203       This method behaves like "accept_targets_as_text", but also marks the
204       region as one whose content should be emitted literally, without HTML
205       entity escaping or wrapping in a "div" element.
206
207   resolve_pod_page_link
208         my $url = $pod->resolve_pod_page_link('Net::Ping', 'INSTALL');
209         my $url = $pod->resolve_pod_page_link('perlpodspec');
210         my $url = $pod->resolve_pod_page_link(undef, 'SYNOPSIS');
211
212       Resolves a POD link target (typically a module or POD file name) and
213       section name to a URL. The resulting link will be returned for the
214       above examples as:
215
216         https://metacpan.org/pod/Net::Ping#INSTALL
217         https://metacpan.org/pod/perlpodspec
218         #SYNOPSIS
219
220       Note that when there is only a section argument the URL will simply be
221       a link to a section in the current document.
222
223   resolve_man_page_link
224         my $url = $pod->resolve_man_page_link('crontab(5)', 'EXAMPLE CRON FILE');
225         my $url = $pod->resolve_man_page_link('crontab');
226
227       Resolves a man page link target and numeric section to a URL. The
228       resulting link will be returned for the above examples as:
229
230           http://man.he.net/man5/crontab
231           http://man.he.net/man1/crontab
232
233       Note that the first argument is required. The section number will be
234       parsed from it, and if it's missing will default to 1. The second
235       argument is currently ignored, as man.he.net <http://man.he.net> does
236       not currently include linkable IDs or anchor names in its pages.
237       Subclass to link to a different man page HTTP server.
238
239   idify
240         my $id   = $pod->idify($text);
241         my $hash = $pod->idify($text, 1);
242
243       This method turns an arbitrary string into a valid XHTML ID attribute
244       value.  The rules enforced, following
245       <http://webdesign.about.com/od/htmltags/a/aa031707.htm>, are:
246
247       •   The id must start with a letter (a-z or A-Z)
248
249       •   All subsequent characters can be letters, numbers (0-9), hyphens
250           (-), underscores (_), colons (:), and periods (.).
251
252       •   The final character can't be a hyphen, colon, or period. URLs
253           ending with these characters, while allowed by XHTML, can be
254           awkward to extract from plain text.
255
256       •   Each id must be unique within the document.
257
258       In addition, the returned value will be unique within the context of
259       the Pod::Simple::XHTML object unless a second argument is passed a true
260       value. ID attributes should always be unique within a single XHTML
261       document, but pass the true value if you are creating not an ID but a
262       URL hash to point to an ID (i.e., if you need to put the "#foo" in "<a
263       href="#foo">foo</a>".
264
265   batch_mode_page_object_init
266         $pod->batch_mode_page_object_init($batchconvobj, $module, $infile, $outfile, $depth);
267
268       Called by Pod::Simple::HTMLBatch so that the class has a chance to
269       initialize the converter. Internally it sets the "batch_mode" property
270       to true and sets "batch_mode_current_level()", but Pod::Simple::XHTML
271       does not currently use those features. Subclasses might, though.
272

SEE ALSO

274       Pod::Simple, Pod::Simple::Text, Pod::Spell
275

SUPPORT

277       Questions or discussion about POD and Pod::Simple should be sent to the
278       pod-people@perl.org mail list. Send an empty email to
279       pod-people-subscribe@perl.org to subscribe.
280
281       This module is managed in an open GitHub repository,
282       <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
283       contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
284       send patches!
285
286       Patches against Pod::Simple are welcome. Please send bug reports to
287       <bug-pod-simple@rt.cpan.org>.
288
290       Copyright (c) 2003-2005 Allison Randal.
291
292       This library is free software; you can redistribute it and/or modify it
293       under the same terms as Perl itself.
294
295       This program is distributed in the hope that it will be useful, but
296       without any warranty; without even the implied warranty of
297       merchantability or fitness for a particular purpose.
298

ACKNOWLEDGEMENTS

300       Thanks to Hurricane Electric <http://he.net/> for permission to use its
301       Linux man pages online <http://man.he.net/> site for man page links.
302
303       Thanks to search.cpan.org <http://search.cpan.org/> for permission to
304       use the site for Perl module links.
305

AUTHOR

307       Pod::Simpele::XHTML was created by Allison Randal <allison@perl.org>.
308
309       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
310       bother him, he's retired.
311
312       Pod::Simple is maintained by:
313
314       •   Allison Randal "allison@perl.org"
315
316       •   Hans Dieter Pearcey "hdp@cpan.org"
317
318       •   David E. Wheeler "dwheeler@cpan.org"
319
320
321
322perl v5.34.0                      2022-01-21             Pod::Simple::XHTML(3)
Impressum