1Pod::Xhtml(3)         User Contributed Perl Documentation        Pod::Xhtml(3)
2
3
4

NAME

6       Pod::Xhtml - Generate well-formed XHTML documents from POD format
7       documentation
8

SYNOPSIS

10       This module inherits from Pod::Parser, hence you can use this familiar
11       interface:
12
13               use Pod::Xhtml;
14               my $parser = new Pod::Xhtml;
15               $parser->parse_from_file( $infile, $outfile );
16
17               # or use filehandles instead
18               $parser->parse_from_filehandle($in_fh, $out_fh);
19
20               # or get the XHTML as a scalar
21               my $parsertoo = new Pod::Xhtml( StringMode => 1 );
22               $parsertoo->parse_from_file( $infile, $outfile );
23               my $xhtml = $parsertoo->asString;
24
25               # or get a reference to the XHTML string
26               my $xhtmlref = $parsertoo->asStringRef;
27
28               # to parse some other pod file to another output file all you need to do is...
29               $parser->parse_from_file( $anotherinfile, $anotheroutfile );
30
31       There are options specific to Pod::Xhtml that you can pass in at
32       construction time, e.g.:
33
34               my $parser = new Pod::Xhtml(StringMode => 1, MakeIndex => 0);
35
36       See "OPTIONS". For more information also see Pod::Parser which this
37       module inherits from.
38

DESCRIPTION

40       new Pod::Xhtml( [ OPTIONS ] )
41           Create a new object. Optionally pass in some options in the form
42           'new Pod::Xhtml( StringMode => 1);'
43
44       $parser->parse_from_file( INPUTFILE, [OUTPUTFILE] )
45           Read POD from the input file, output to the output file (or STDOUT
46           if no file is given). See Pod::Parser docs for more.  Note that you
47           can parse multiple files with the same object. All your options
48           will be preserved, as will any text you added with the add*Text
49           methods.
50
51       $parser->parse_from_filehandle( [INPUTFILEHANDLE, [OUTPUTFILEHANDLE]] )
52           Read POD from the input filehandle, output to the output filehandle
53           (STDIN/STDOUT if no filehandle(s) given). See Pod::Parser docs for
54           more.  Note that you can parse multiple files with the same object.
55           All your options will be preserved, as will any text you added with
56           the add*Text methods.
57
58       $parser->asString
59           Get the XHTML as a scalar. You'll probably want to use this with
60           the StringMode option.
61
62       $parser->asStringRef
63           As above, but you get a reference to the string, not the string
64           itself.
65
66       $parser->addHeadText( $text )
67           Inserts some text just before the closing head tag. For example you
68           can add a link to a stylesheet. May be called many times to add
69           lots of text. Note: you need to call this some time before any
70           output is done, e.g. straight after new(). Make sure that you only
71           insert valid XHTML fragments.
72
73       $parser->addBodyOpenText( $text ) / $parser->addBodyCloseText( $text )
74           Inserts some text right at the beginning (or ending) of the body
75           element. For example you can add a navigation header and footer.
76           May be called many times to add lots of text. Note: you need to
77           call this some time before any output is done, e.g. straight after
78           new(). Make sure that you only insert valid XHTML fragments.
79

OPTIONS

81       StringMode
82           Default: 0. If set to 1 this does no output at all, even if
83           filenames/handles are supplied. Use asString or asStringRef to
84           access the text if you set this option.
85
86       MakeIndex
87           Default: 1. If set to 1 then an index of sections is created at the
88           top of the body. If set to 2 then the index includes non-bulleted
89           list items
90
91       MakeMeta
92           Default: 1. If set to 1 then some meta tags are created, recording
93           things like input file, description, etc.
94
95       FragmentOnly
96           Default: 0. If 1, we only produce an XHTML fragment (suitable for
97           use as a server-side include etc). There is no HEAD element nor any
98           BODY or HTML tags. Any text added with the add*Text methods will
99           not be output.
100
101       TopHeading
102           Allows you to set the starting heading level when in fragment mode.
103           For example, if your document already has h1 tags and you want the
104           generated POD to nest inside the outline, you can specify
105
106                   TopHeading => 2
107
108           and "=head1" will be tagged with h2 tags, "=head3" with h3, and so
109           on.
110
111           Note that XHTML doesn't allow for heading tags past h6, so h7 and
112           up will be translated to h6 as necessary.
113
114       TopLinks
115           At each section head this text is added to provide a link back to
116           the top.  Set to 0 or '' to inhibit links, or define your own.
117
118                   Default: <p><a href="#TOP" class="toplink">Top</a></p>
119
120       LinkParser
121           An object that parses links in the POD document. By default, this
122           is a regular Pod::Hyperlink object. Any user-supplied link parser
123           must conform the the Pod::Hyperlink API.
124
125           This module works with a Pod::Hyperlink::BounceURL link parser and
126           generates hyperlinks as 'a' elements with a class of
127           'pod_xhtml_bounce_url'. The optional text giving the "node" is
128           enclosed in a 'strong' element with a class of
129           'pod_xhtml_bounce_url_text'
130

RATIONALE

132       There's Pod::PXML and Pod::XML, so why do we need Pod::Xhtml? You need
133       an XSLT to transform XML into XHTML and many people don't have the time
134       or inclination to do this. But they want to make sure that the pages
135       they put on their web site are well-formed, they want those pages to
136       use stylesheets easily, and possibly they want to squirt the XHTML
137       through some kind of filter for more processing.
138
139       By generating well-formed XHTML straight away we allow anyone to just
140       use the output files as-is. For those who want to use XML tools or
141       transformations they can use the XHTML as a source, because it's a
142       well-formed XML document.
143

CAVEATS

145       This module outputs well-formed XHTML if the POD is well-formed. To
146       check this you can use something like:
147
148               use Pod::Checker;
149               my $syn = podchecker($defaultIn);
150
151       If $syn is 0 there are no syntax errors. If it's -1 then no POD was
152       found. Any positive number indicates that that number of errors were
153       found. If the input POD has errors then the output XHTML should be
154       well-formed but will probably omit information, and in addition
155       Pod::Xhtml will emit warnings. Note that Pod::Parser seems to be
156       sensitive to the current setting of $/ so ensure it's the end-of-line
157       character when the parsing is done.
158

AUTHOR

160       P Kent & Simon Flack  <cpan _at_ bbc _dot_ co _dot_ uk>
161
163       (c) BBC 2004, 2005. This program is free software; you can redistribute
164       it and/or modify it under the GNU GPL.
165
166       See the file COPYING in this distribution, or
167       http://www.gnu.org/licenses/gpl.txt
168
169
170
171perl v5.34.0                      2022-01-21                     Pod::Xhtml(3)
Impressum