subclassing.pod

source of perl for linux application,

=head1 NAME

Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass

=head1 SYNOPSIS

  package Pod::SomeFormatter;
  use Pod::Simple;
  @ISA = qw(Pod::Simple);
  $VERSION = '1.01';
  use strict;

  sub _handle_element_start {
    my($parser, $element_name, $attr_hash_r) = @_;
    ...
  }

  sub _handle_element_end {
    my($parser, $element_name) = @_;
    ...
  }

  sub _handle_text {
    my($parser, $text) = @_;
    ...
  }
  1;

=head1 DESCRIPTION

This document is about using Pod::Simple to write a Pod processor,
generally a Pod formatter. If you just want to know about using an
existing Pod formatter, instead see its documentation and see also the
docs in L<Pod::Simple>.

The zeroeth step in writing a Pod formatter is to make sure that there
isn't already a decent one in CPAN. See L<http://search.cpan.org/>, and
run a search on the name of the format you want to render to. Also
consider joining the Pod People list
L<http://lists.perl.org/showlist.cgi?name=pod-people> and asking whether
anyone has a formatter for that format -- maybe someone cobbled one
together but just hasn't released it.

The first step in writing a Pod processor is to read L<perlpodspec>,
which contains notes information on writing a Pod parser (which has been
largely taken care of by Pod::Simple), but also a lot of requirements
and recommendations for writing a formatter.

The second step is to actually learn the format you're planning to
format to -- or at least as much as you need to know to represent Pod,
which probably isn't much.

The third step is to pick which of Pod::Simple's interfaces you want to
use -- the basic interface via Pod::Simple or L<Pod::Simple::Methody> is
event-based, sort of like L<HTML::Parser>'s interface, or sort of like
L<XML::Parser>'s "Handlers" interface), but L<Pod::Simple::PullParser>
provides a token-stream interface, sort of like L<HTML::TokeParser>'s
interface; L<Pod::Simple::SimpleTree> provides a simple tree interface,
rather like XML::Parser's "Tree" interface. Users familiar with
XML-handling will find one of these styles relatively familiar; but if
you would be even more at home with XML, there are classes that produce
an XML representation of the Pod stream, notably
L<Pod::Simple::XMLOutStream>; you can feed the output of such a class to
whatever XML parsing system you are most at home with.

The last step is to write your code based on how the events (or tokens,
or tree-nodes, or the XML, or however you're parsing) will map to
constructs in the output format. Also sure to consider how to escape
text nodes containing arbitrary text, and also what to do with text
nodes that represent preformatted text (from verbatim sections).



=head1 Events

TODO intro... mention that events are supplied for implicits, like for
missing >'s


In the following section, we use XML to represent the event structure
associated with a particular construct.  That is, TODO

=over

=item C<< $parser->_handle_element_start( I<element_name>, I<attr_hashref> ) >>

=item C<< $parser->_handle_element_end( I<element_name>  ) >>

=item C<< $parser->_handle_text(  I<text_string>  ) >>

=back

TODO describe


=over

=item events with an element_name of Document

Parsing a document produces this event structure:

  <Document start_line="543">
    ...all events...
  </Document>

The value of the I<start_line> attribute will be the line number of the first
Pod directive in the document.

If there is no Pod in the given document, then the 
event structure will be this:

  <Document contentless="1" start_line="543">
  </Document>

In that case, the value of the I<start_line> attribute will not be meaningful;
under current implementations, it will probably be the line number of the
last line in the file.

=item events with an element_name of Para

Parsing a plain (non-verbatim, non-directive, non-data) paragraph in
a Pod document produces this event structure:

    <Para start_line="543">
      ...all events in this paragraph...
    </Para>

The value of the I<start_line> attribute will be the line number of the start
of the paragraph.

For example, parsing this paragraph of Pod:

  The value of the I<start_line> attribute will be the
  line number of the start of the paragraph.

produces this event structure:

    <Para start_line="129">
      The value of the 
      <I>
        start_line
      </I>
       attribute will be the line number of the first Pod directive
      in the document.
    </Para>

=item events with an element_name of B, C, F, or I.

Parsing a BE<lt>...E<gt> formatting code (or of course any of its
semantically identical syntactic variants
S<BE<lt>E<lt> ... E<gt>E<gt>>,
or S<BE<lt>E<lt>E<lt>E<lt> ... E<gt>E<gt>E<gt>E<gt>>, etc.)
produces this event structure:

      <B>
        ...stuff...
      </B>

Currently, there are no attributes conveyed.

Parsing C, F, or I codes produce the same structure, with only a
different element name.

If your parser object has been set to accept other formatting codes,
then they will be presented like these B/C/F/I codes -- i.e., without
any attributes.

=item events with an element_name of S

Normally, parsing an SE<lt>...E<gt> sequence produces this event
structure, just as if it were a B/C/F/I code:

      <S>
        ...stuff...
      </S>

However, Pod::Simple (and presumably all derived parsers) offers the
C<nbsp_for_S> option which, if enabled, will suppress all S events, and
instead change all spaces in the content to non-breaking spaces. This is
intended for formatters that output to a format that has no code that
means the same as SE<lt>...E<gt>, but which has a code/character that
means non-breaking space.

=item events with an element_name of X

Normally, parsing an XE<lt>...E<gt> sequence produces this event
structure, just as if it were a B/C/F/I code:

      <X>
        ...stuff...
      </X>

However, Pod::Simple (and presumably all derived parsers) offers the
C<nix_X_codes> option which, if enabled, will suppress all X events
and ignore their content.  For formatters/processors that don't use
X events, this is presumably quite useful.


=item events with an element_name of L

Because the LE<lt>...E<gt> is the most complex construct in the
language, it should not surprise you that the events it generates are
the most complex in the language. Most of complexity is hidden away in
the attribute values, so for those of you writing a Pod formatter that
produces a non-hypertextual format, you can just ignore the attributes
and treat an L event structure like a formatting element that
(presumably) doesn't actually produce a change in formatting.  That is,
the content of the L event structure (as opposed to its
attributes) is always what text should be displayed.

There are, at first glance, three kinds of L links: URL, man, and pod.

When a LE<lt>I<some_url>E<gt> code is parsed, it produces this event
structure:

  <L content-implicit="yes" to="that_url" type="url">
    that_url
  </L>

The C<type="url"> attribute is always specified for this type of
L code.

For example, this Pod source:

  L<http://www.perl.com/CPAN/authors/>

produces this event structure:

  <L content-implicit="yes" to="http://www.perl.com/CPAN/authors/" type="url">
    http://www.perl.com/CPAN/authors/
  </L>

When a LE<lt>I<manpage(section)>E<gt> code is parsed (and these are
fairly rare and not terribly useful), it produces this event structure:

  <L content-implicit="yes" to="manpage(section)" type="man">
    manpage(section)
  </L>

The C<type="man"> attribute is always specified for this type of
L code.

For example, this Pod source:

  L<crontab(5)>

produces this event structure:

  <L content-implicit="yes" to="crontab(5)" type="man">
    crontab(5)
  </L>

In the rare cases where a man page link has a specified, that text appears
in a I<section> attribute. For example, this Pod source:

  L<crontab(5)/"ENVIRONMENT">

will produce this event structure:

  <L content-implicit="yes" section="ENVIRONMENT" to="crontab(5)" type="man">
    "ENVIRONMENT" in crontab(5)
  </L>

In the rare case where the Pod document has code like
LE<lt>I<sometext>|I<manpage(section)>E<gt>, then the I<sometext> will appear
as the content of the element, the I<manpage(section)> text will appear
only as the value of the I<to> attribute, and there will be no
C<content-implicit="yes"> attribute (whose presence means that the Pod parser
had to infer what text should appear as the link text -- as opposed to
cases where that attribute is absent, which means that the Pod parser did
I<not> have to infer the link text, because that L code explicitly specified
some link text.)

For example, this Pod source:

  L<hell itself!|crontab(5)>
  
will produce this event structure:

  <L to="crontab(5)" type="man">
    hell itself!
  </L>

The last type of L structure is for links to/within Pod documents. It is
the most complex because it can have a I<to> attribute, I<or> a
I<section> attribute, or both. The C<type="pod"> attribute is always
specified for this type of L code.

In the most common case, the simple case of a LE<lt>podpageE<gt> code
produces this event structure:

  <L content-implicit="yes" to="Net::Ping" type="pod">
    podpage
  </L>

For example, this Pod source:

  L<Net::Ping>

produces this event structure:

  <L content-implicit="yes" to="Net::Ping" type="pod">
    Net::Ping
  </L>

In cases where there is link-text explicitly specified, it
is to be found in the content of the element (and not the
attributes), just as with the LE<lt>I<sometext>|I<manpage(section)>E<gt>
case discussed above.  For example, this Pod source:

  L<Perl Error Messages|perldiag>

produces this event structure:

  <L to="perldiag" type="pod">
    Perl Error Messages
  </L>

In cases of links to a section in the current Pod document,
there is a I<section> attribute instead of a I<to> attribute.
For example, this Pod source:

  L</"Member Data">

produces this event structure:

  <L content-implicit="yes" section="Member Data" type="pod">
    "Member Data"
  </L>

As another example, this Pod source:

  L<the various attributes|/"Member Data">

produces this event structure:

  <L section="Member Data" type="pod">
    the various attributes
  </L>

In cases of links to a section in a different Pod document,
there are both a I<section> attribute and a L<to> attribute.
For example, this Pod source:

  L<perlsyn/"Basic BLOCKs and Switch Statements">

produces this event structure:

  <L content-implicit="yes" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
    "Basic BLOCKs and Switch Statements" in perlsyn
  </L>

As another example, this Pod source:

  L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">

produces this event structure:

  <L section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
    SWITCH statements
  </L>

Incidentally, note that we do not distinguish between these syntaxes:

  L</"Member Data">
  L<"Member Data">
  L</Member Data>
  L<Member Data>    [deprecated syntax]

That is, they all produce the same event structure, namely:

  <L content-implicit="yes" section="Member Data" type="pod">
    &#34;Member Data&#34;
  </L>

=item events with an element_name of E or Z

While there are Pod codes EE<lt>...E<gt> and ZE<lt>E<gt>, these
I<do not> produce any E or Z events -- that is, there are no such
events as E or Z.

=item events with an element_name of Verbatim

When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
produces this event structure:

  <Verbatim start_line="543" xml:space="preserve">
    ...text...
  </Verbatim>

The value of the I<start_line> attribute will be the line number of the
first line of this verbatim block.  The I<xml:space> attribute is always
present, and always has the value "preserve".

The text content will have tabs already expanded.


=item events with an element_name of head1 .. head4

When a "=head1 ..." directive is parsed, it produces this event
structure:

  <head1>
    ...stuff...
  </head1>

For example, a directive consisting of this:

  =head1 Options to C<new> et al.

will produce this event structure:

  <head1 start_line="543">
    Options to 
    <C>
      new
    </C>
     et al.
  </head1>

"=head2" thru "=head4" directives are the same, except for the element
names in the event structure.

=item events with an element_name of over-bullet

When an "=over ... Z<>=back" block is parsed where the items are
a bulletted list, it will produce this event structure:

  <over-bullet indent="4" start_line="543">
    <item-bullet start_line="545">
      ...Stuff...
    </item-bullet>
    ...more item-bullets...
  </over-bullet>

The value of the I<indent> attribute is whatever value is after the
"=over" directive, as in "=over 8".  If no such value is specified
in the directive, then the I<indent> attribute has the value "4".

For example, this Pod source:

  =over

  =item *

  Stuff

  =item *

  Bar I<baz>!

  =back

produces this event structure:

  <over-bullet indent="4" start_line="10">
    <item-bullet start_line="12">
      Stuff
    </item-bullet>
    <item-bullet start_line="14">
      Bar <I>baz</I>!