.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pod::SAX 3pm"
.TH Pod::SAX 3pm "2020-05-17" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pod::SAX \- a SAX parser for Pod
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& my $h = XML::SAX::Writer\->new();
\& my $p = Pod::SAX\->new( Handler => $h );
\& $p\->parse_uri(\*(Aqperlpodspec.pod\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Very simply, this module parses \s-1POD\s0 (or perl) files and turns the
Plain Old Documentation into \s-1SAX\s0 events (which often you'll use
to turn into \s-1XML,\s0 but there are other uses as well).
.PP
The aim of this module is not round-tripping, so some things may
be lost in the conversion. The aim is to be as standards compliant
as possible, while giving you very simple access to the data.
.PP
The main motivation for this module though was simple standards
compliance \- all the Pod parsers out there seem to have their own
unique way of doing things, and so my aim was to unify that and
allow the flexibility that \s-1SAX\s0 gives me at the same time.
.PP
For an introduction to \s-1SAX,\s0 please read XML::SAX::Intro.
.PP
One very important point to note is that just because this is a
\&\s-1SAX\s0 module it doesn't mandate that the results are \s-1XML.\s0 You could
just as easily use this module to extract all filenames from
a \s-1POD\s0 file, or extract custom =for/=begin sections. And because
it uses standardised interfaces this is a lot simpler than working
with any other \s-1POD\s0 parser out there, and the knowledge is
transferrable.
.SH "API"
.IX Header "API"
.SS "\fBnew()\fP"
.IX Subsection "new()"
To construct a parser simply call \fBnew()\fR. It is customary to pass
in the handler object that will receive the \s-1SAX\s0 events at this time,
though you do not have to:
.PP
.Vb 1
\& my $parser = Pod::SAX\->new(Handler => $h);
.Ve
.PP
You can re-use this parser object multiple times. It's possible to change
the handler at a later date using \f(CW\*(C`$parser\-\*(C'\fR\fBset_handler()\fR>. This and many
other \s-1API\s0 calls are documented in XML::SAX::Base, which this module
inherits from.
.SS "\fBparse()\fP"
.IX Subsection "parse()"
This method is an auto-detecting parser \- it will try and figure out
what you passed to it (a string, a file handle or a filename) and
parse the data using the appropriate technique.
.SS "\fBparse_file()\fP, \fBparse_string()\fP, \fBparse_uri()\fP, \fBparse_fh()\fP"
.IX Subsection "parse_file(), parse_string(), parse_uri(), parse_fh()"
These are simply the non-detecting methods that \fBparse()\fR uses internally.
Use these if you are paranoid about what you're parsing, and don't want
the overhead of \s-1SAX\s0 trying to guess.
.SH "XML Format"
.IX Header "XML Format"
The \s-1XML\s0 format is intended to be simple and map fairly closely to the
source \s-1POD.\s0 The documentation here shows the \s-1POD\s0 marker and the
tag that it maps to.
.SS "=pod (or any other way to begin the document)"
.IX Subsection "=pod (or any other way to begin the document)"
.Vb 2
\&
\&
.Ve
.PP
The comment is automatically generated so that you can see what version
of Pod::SAX was used in parsing this document. The closing \f(CW\*(C`\*(C'\fR
tag is generated when the end of the \s-1POD\s0 is reached.
.SS "=head1 and =headN"
.IX Subsection "=head1 and =headN"
.Vb 1
\& Text here
.Ve
.PP
All head levels are supported.
.SS "Paragraphs"
.IX Subsection "Paragraphs"
Plain paragraphs are represented with:
.PP
.Vb 1
\& text
.Ve
.SS "Verbatim"
.IX Subsection "Verbatim"
Verbatim sections (i.e. when you indent the text) are represented with:
.PP
.Vb 1
\& text
.Ve
.SS "=over/=back"
.IX Subsection "=over/=back"
Pod::SAX automatically detects whether a list is itemized or ordered (i.e.
whether it should have bullet points or numbers), and so =over/=back are
represented by:
.PP
.Vb 1
\&
.Ve
.PP
and
.PP
.Vb 1
\&
.Ve
.PP
respectively. The indent value (as in \*(L"=over 4\*(R") is saved in the
\&\f(CW\*(C`indent_width\*(C'\fR attribute, although for most purposes this can be ignored.
.SS "=item"
.IX Subsection "=item"
For both bulleted and numbered lists, the =item tag always maps to:
.PP
.Vb 1
\& text
.Ve
.PP
If a paragraph follows an =item tag (and occurs before any =back) then
the paragraph is included immediately after the tag, so for example:
.PP
.Vb 1
\& =item foo
\&
\& Some text about foo
.Ve
.PP
Maps to:
.PP
.Vb 3
\& foo
\& Some text about foo
\&
.Ve
.SS "=begin foo"
.IX Subsection "=begin foo"
And \*(L"=for foo\*(R" (the two are semantically equivalent in Pod)
.PP
.Vb 1
\& text here
.Ve
.PP
If the markup section is meant for ordinary processing (see
the perlpodspec section on \*(L"About Data Paragraphs and \*(R"=begin/=end\*(L"
Regions\*(R"), which means the type name begins with a colon as in:
.PP
.Vb 1
\& =begin :biblio
.Ve
.PP
Then the markup produced indicates that using:
.PP
.Vb 1
\&
.Ve
.PP
And the parser will expand all interior Pod commands as it should.
.PP
\&\fBNote\fR: There is \fIno\fR special treatment of =begin html or
=begin \s-1XML\s0 or any variant thereof. The contents of those markers
will simply be treated as text, and it is up to the user of this
module to parse that data as \s-1XML\s0 if they wish to do so.
.SS "Sequences or Formatting Codes"
.IX Subsection "Sequences or Formatting Codes"
Sequences in \s-1POD\s0 consist of the following:
.PP
.Vb 9
\& L<> \- Links
\& E<> \- Entities
\& I<> \- Italics
\& B<> \- Bold
\& C<> \- Code
\& F<> \- Filename
\& S<> \- Non breaking space
\& X<> \- Index marker
\& Z<> \- Null
.Ve
.PP
Most sequences are simply converted to tags of the same name, case
preserved:
.PP
.Vb 1
\& This is bold text and also some in italics.
.Ve
.PP
Special treatment is given to the L<> E<> and S<> tags
only.
.PP
\fILinks\fR
.IX Subsection "Links"
.PP
Links in Pod are... funky.
.PP
Parsing links is really hard, so don't expect that I've got this right.
Basically though you've got this mapping:
.PP
.Vb 2
\& L
\& => foo
\&
\& L
\& => Some Foo
\&
\& L