Pod::SAX - a SAX parser for Pod

new()
       To construct a parser simply call new(). It is customary to pass in the handler object that will receive
       the SAX events at this time, though you do not have to:

         my $parser = Pod::SAX->new(Handler => $h);

       You can re-use this parser object multiple times. It's possible to change the handler at a later date
       using "$parser-"set_handler()>. This and many other API calls are documented in XML::SAX::Base, which
       this module inherits from.

   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.

   parse_file(),parse_string(),parse_uri(),parse_fh()
       These are simply the non-detecting methods that parse() uses internally.  Use these if you are paranoid
       about what you're parsing, and don't want the overhead of SAX trying to guess.

       Matt Sergeant, matt@sergeant.org. Copyright AxKit.com Ltd 2002

       There may be bugs in the unicode handling on perl 5.8, because it's just really hard to get things right
       on 5.8 when dealing with unicode. :-)

       Very simply, this module parses POD (or perl) files and turns the Plain Old Documentation into SAX events
       (which often you'll use to turn into XML, but there are other uses as well).

       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.

       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 SAX gives me at the same time.

       For an introduction to SAX, please read XML::SAX::Intro.

       One very important point to note is that just because this is a SAX module it doesn't mandate that the
       results are XML. You could just as easily use this module to extract all filenames from a POD file, or
       extract custom =for/=begin sections. And because it uses standardised interfaces this is a lot simpler
       than working with any other POD parser out there, and the knowledge is transferrable.

       This is free software. You may use it and redistribute it under the same terms as Perl itself.

perl v5.30.0                                       2020-05-17                                      Pod::SAX(3pm)

       Pod::SAX - a SAX parser for Pod

         my $h = XML::SAX::Writer->new();
         my $p = Pod::SAX->new( Handler => $h );
         $p->parse_uri('perlpodspec.pod');

       The XML format is intended to be simple and map fairly closely to the source POD. The documentation here
       shows the POD marker and the tag that it maps to.

   =pod(oranyotherwaytobeginthedocument)
         <pod>
         <!-- Pod::SAX v0.14, using POD::Parser v1.13 -->

       The comment is automatically generated so that you can see what version of Pod::SAX was used in parsing
       this document. The closing "</pod>" tag is generated when the end of the POD is reached.

   =head1and=headN
         <head1>Text here</head1>

       All head levels are supported.

   Paragraphs
       Plain paragraphs are represented with:

         <para>text</para>

   Verbatim
       Verbatim sections (i.e. when you indent the text) are represented with:

         <verbatim>text</verbatim>

   =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:

         <itemizedlist>  </itemizedlist>

       and

         <orderedlist>   </orderedlist>

       respectively. The indent value (as in "=over 4") is saved in the "indent_width" attribute, although for
       most purposes this can be ignored.

   =item
       For both bulleted and numbered lists, the =item tag always maps to:

         <listitem>text</listitem>

       If a paragraph follows an =item tag (and occurs before any =back) then the paragraph is included
       immediately after the tag, so for example:

         =item foo

         Some text about foo

       Maps to:

         <listitem>foo
           <para>Some text about foo</para>
         </listitem>

   =beginfoo
       And "=for foo" (the two are semantically equivalent in Pod)

         <markup type="foo" ordinary_paragraph="0">text here</markup>

       If the markup section is meant for ordinary processing (see the perlpodspec section on "About Data
       Paragraphs and "=begin/=end" Regions"), which means the type name begins with a colon as in:

         =begin :biblio

       Then the markup produced indicates that using:

         <markup type="biblio" ordinary_paragraph="1"/>

       And the parser will expand all interior Pod commands as it should.

       Note: There is no special treatment of =begin html or =begin XML 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 XML if they wish to do so.

   SequencesorFormattingCodes
       Sequences in POD consist of the following:

         L<> - Links
         E<> - Entities
         I<> - Italics
         B<> - Bold
         C<> - Code
         F<> - Filename
         S<> - Non breaking space
         X<> - Index marker
         Z<> - Null

       Most sequences are simply converted to tags of the same name, case preserved:

         <B>This is bold text</B> and also <I>some in italics</I>.

       Special treatment is given to the L<> E<> and S<> tags only.

       Links

       Links in Pod are... funky.

       Parsing links is really hard, so don't expect that I've got this right.  Basically though you've got this
       mapping:

         L<foo/bar>
          => <link type="pod" page="foo" section="bar">foo</link>

         L<Some Foo|foo>
          => <link type="pod" page="foo" section="">Some Foo</link>

         L<select(3)>
          => <link type="man" page="select(3)" section="">select(3)</link>

         L<http://foo.com>
          => <xlink href="http://foo.com">http://foo.com</xlink>

       And many variations thereof! Basically it should do the right thing

       Entities

       In POD an E<> marker defines an entity. In pod these are single characters only, and take either a text
       form, in which case they map to the standard HTML entities (e.g. ouml, Agrave etc), or a decimal number
       in which case they map to the unicode character at that code point.

       In Pod::SAX entities are always converted to unicode and never generate any tags or markers in the data
       stream so it will be as though the entity was never there.

       Non-BreakingSpace

       Non breaking space is simply achieved by changing all space within the S<> section into the unicode
       codepoint 160 - the non-breaking space character. Normally this is enough to do the right thing, but if
       you need to you can detect this with a regexp.