1Pod::Simple::XHTML(3pm)Perl Programmers Reference GuidePod::Simple::XHTML(3pm)
2
6 Pod::Simple::XHTML -- format Pod as validating XHTML
7
9 use Pod::Simple::XHTML;
10 my $parser = Pod::Simple::XHTML->new();
12 ...
14 $parser->parse_file('path/to/file.pod');
16
18 This class is a formatter that takes Pod and renders it as XHTML
19 validating HTML.
20 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
26 Pod::Simple::XHTML offers a number of methods that modify the format of
27 the HTML output. Call these after creating the parser object, but
28 before the call to "parse_file":
29 my $parser = Pod::PseudoPod::HTML->new();
31 $parser->set_optional_param("value");
32 $parser->parse_file($file);
33 perldoc_url_prefix
35 In turning Foo::Bar into http://whatever/Foo%3a%3aBar, what to put
36 before the "Foo%3a%3aBar". The default value is
37 "http://search.cpan.org/perldoc?".
38 perldoc_url_postfix
40 What to put after "Foo%3a%3aBar" in the URL. This option is not set by
41 default.
42 man_url_prefix
44 In turning crontab(5) into http://whatever/man/1/crontab, what to put
45 before the "1/crontab". The default value is "http://man.he.net/man".
46 man_url_postfix
48 What to put after "1/crontab" in the URL. This option is not set by
49 default.
50 title_prefix, title_postfix
52 What to put before and after the title in the head. The values should
53 already be &-escaped.
54 html_css
56 $parser->html_css('path/to/style.css');
57 The URL or relative path of a CSS file to include. This option is not
59 set by default.
60 html_javascript
62 The URL or relative path of a JavaScript file to pull in. This option
63 is not set by default.
64 html_doctype
66 A document type tag for the file. This option is not set by default.
67 html_header_tags
69 Additional arbitrary HTML tags for the header of the document. The
70 default value is just a content type header tag:
71 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
73 Add additional meta tags here, or blocks of inline CSS or JavaScript
75 (wrapped in the appropriate tags).
76 html_h_level
78 This is the level of HTML "Hn" element to which a Pod "head1"
79 corresponds. For example, if "html_h_level" is set to 2, a head1 will
80 produce an H2, a head2 will produce an H3, and so on.
81 default_title
83 Set a default title for the page if no title can be determined from the
84 content. The value of this string should already be &-escaped.
85 force_title
87 Force a title for the page (don't try to determine it from the
88 content). The value of this string should already be &-escaped.
89 html_header, html_footer
91 Set the HTML output at the beginning and end of each file. The default
92 header includes a title, a doctype tag (if "html_doctype" is set), a
93 content tag (customized by "html_header_tags"), a tag for a CSS file
94 (if "html_css" is set), and a tag for a Javascript file (if
95 "html_javascript" is set). The default footer simply closes the "html"
96 and "body" tags.
97 The options listed above customize parts of the default header, but
99 setting "html_header" or "html_footer" completely overrides the built-
100 in header or footer. These may be useful if you want to use template
101 tags instead of literal HTML headers and footers or are integrating
102 converted POD pages in a larger website.
103 If you want no headers or footers output in the HTML, set these options
105 to the empty string.
106 index
108 Whether to add a table-of-contents at the top of each page (called an
109 index for the sake of tradition).
110
112 If the standard options aren't enough, you may want to subclass
113 Pod::Simple::XHMTL. These are the most likely candidates for methods
114 you'll want to override when subclassing.
115 handle_text
117 This method handles the body of text within any element: it's the body
118 of a paragraph, or everything between a "=begin" tag and the
119 corresponding "=end" tag, or the text within an L entity, etc. You
120 would want to override this if you are adding a custom element type
121 that does more than just display formatted text. Perhaps adding a way
122 to generate HTML tables from an extended version of POD.
123 So, let's say you want add a custom element called 'foo'. In your
125 subclass's "new" method, after calling "SUPER::new" you'd call:
126 $new->accept_targets_as_text( 'foo' );
128 Then override the "start_for" method in the subclass to check for when
130 "$flags->{'target'}" is equal to 'foo' and set a flag that marks that
131 you're in a foo block (maybe "$self->{'in_foo'} = 1"). Then override
132 the "handle_text" method to check for the flag, and pass $text to your
133 custom subroutine to construct the HTML output for 'foo' elements,
134 something like:
135 sub handle_text {
137 my ($self, $text) = @_;
138 if ($self->{'in_foo'}) {
139 $self->{'scratch'} .= build_foo_html($text);
140 } else {
141 $self->{'scratch'} .= $text;
142 }
143 }
144 accept_targets_as_html
146 This method behaves like "accept_targets_as_text", but also marks the
147 region as one whose content should be emitted literally, without HTML
148 entity escaping or wrapping in a "div" element.
149 resolve_pod_page_link
151 my $url = $pod->resolve_pod_page_link('Net::Ping', 'INSTALL');
152 my $url = $pod->resolve_pod_page_link('perlpodspec');
153 my $url = $pod->resolve_pod_page_link(undef, 'SYNOPSIS');
154 Resolves a POD link target (typically a module or POD file name) and
156 section name to a URL. The resulting link will be returned for the
157 above examples as:
158 http://search.cpan.org/perldoc?Net::Ping#INSTALL
160 http://search.cpan.org/perldoc?perlpodspec
161 #SYNOPSIS
162 Note that when there is only a section argument the URL will simply be
164 a link to a section in the current document.
165 resolve_man_page_link
167 my $url = $pod->resolve_man_page_link('crontab(5)', 'EXAMPLE CRON FILE');
168 my $url = $pod->resolve_man_page_link('crontab');
169 Resolves a man page link target and numeric section to a URL. The
171 resulting link will be returned for the above examples as:
172 http://man.he.net/man5/crontab
174 http://man.he.net/man1/crontab
175 Note that the first argument is required. The section number will be
177 parsed from it, and if it's missing will default to 1. The second
178 argument is currently ignored, as man.he.net <http://man.he.net> does
179 not currently include linkable IDs or anchor names in its pages.
180 Subclass to link to a different man page HTTP server.
181 idify
183 my $id = $pod->idify($text);
184 my $hash = $pod->idify($text, 1);
185 This method turns an arbitrary string into a valid XHTML ID attribute
187 value. The rules enforced, following
188 <http://webdesign.about.com/od/htmltags/a/aa031707.htm>, are:
189 · The id must start with a letter (a-z or A-Z)
191 · All subsequent characters can be letters, numbers (0-9), hyphens
193 (-), underscores (_), colons (:), and periods (.).
194 · Each id must be unique within the document.
196 In addition, the returned value will be unique within the context of
198 the Pod::Simple::XHTML object unless a second argument is passed a true
199 value. ID attributes should always be unique within a single XHTML
200 document, but pass the true value if you are creating not an ID but a
201 URL hash to point to an ID (i.e., if you need to put the "#foo" in "<a
202 href="#foo">foo</a>".
203 batch_mode_page_object_init
205 $pod->batch_mode_page_object_init($batchconvobj, $module, $infile, $outfile, $depth);
206 Called by Pod::Simple::HTMLBatch so that the class has a chance to
208 initialize the converter. Internally it sets the "batch_mode" property
209 to true and sets "batch_mode_current_level()", but Pod::Simple::XHTML
210 does not currently use those features. Subclasses might, though.
211
213 Pod::Simple, Pod::Simple::Text, Pod::Spell
214
216 Questions or discussion about POD and Pod::Simple should be sent to the
217 pod-people@perl.org mail list. Send an empty email to
218 pod-people-subscribe@perl.org to subscribe.
219 This module is managed in an open GitHub repository,
221 http://github.com/theory/pod-simple/ <http://github.com/theory/pod-
222 simple/>. Feel free to fork and contribute, or to clone
223 git://github.com/theory/pod-simple.git <git://github.com/theory/pod-
224 simple.git> and send patches!
225 Patches against Pod::Simple are welcome. Please send bug reports to
227 <bug-pod-simple@rt.cpan.org>.
228
230 Copyright (c) 2003-2005 Allison Randal.
231 This library is free software; you can redistribute it and/or modify it
233 under the same terms as Perl itself.
234 This program is distributed in the hope that it will be useful, but
236 without any warranty; without even the implied warranty of
237 merchantability or fitness for a particular purpose.
238
240 Thanks to Hurricane Electrict <http://he.net/> for permission to use
241 its Linux man pages online <http://man.he.net/> site for man page
242 links.
243 Thanks to search.cpan.org <http://search.cpan.org/> for permission to
245 use the site for Perl module links.
246
248 Pod::Simpele::XHTML was created by Allison Randal <allison@perl.org>.
249 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't
251 bother him, he's retired.
252 Pod::Simple is maintained by:
254 · Allison Randal "allison@perl.org"
256 · Hans Dieter Pearcey "hdp@cpan.org"
258 · David E. Wheeler "dwheeler@cpan.org"
260perl v5.12.4 2011-06-07 Pod::Simple::XHTML(3pm)