diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Pod::Simple::Subclassing.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Pod::Simple::Subclassing.3pm | 1212 |
1 files changed, 1212 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Pod::Simple::Subclassing.3pm b/upstream/mageia-cauldron/man3pm/Pod::Simple::Subclassing.3pm new file mode 100644 index 00000000..2e6180c9 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Pod::Simple::Subclassing.3pm @@ -0,0 +1,1212 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" 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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. 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::Simple::Subclassing 3pm" +.TH Pod::Simple::Subclassing 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" 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::Simple::Subclassing \-\- write a formatter as a Pod::Simple subclass +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 5 +\& package Pod::SomeFormatter; +\& use Pod::Simple; +\& @ISA = qw(Pod::Simple); +\& $VERSION = \*(Aq1.01\*(Aq; +\& use strict; +\& +\& sub _handle_element_start { +\& my($parser, $element_name, $attr_hash_r) = @_; +\& ... +\& } +\& +\& sub _handle_element_end { +\& my($parser, $element_name, $attr_hash_r) = @_; +\& # NOTE: $attr_hash_r is only present when $element_name is "over" or "begin" +\& # The remaining code excerpts will mostly ignore this $attr_hash_r, as it is +\& # mostly useless. It is documented where "over\-*" and "begin" events are +\& # documented. +\& ... +\& } +\& +\& sub _handle_text { +\& my($parser, $text) = @_; +\& ... +\& } +\& 1; +.Ve +.SH DESCRIPTION +.IX Header "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 Pod::Simple. +.PP +\&\fBThe zeroeth step\fR in writing a Pod formatter is to make sure that there +isn't already a decent one in CPAN. See <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 +<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. +.PP +\&\fBThe first step\fR in writing a Pod processor is to read perlpodspec, +which contains 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. +.PP +\&\fBThe second step\fR 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. +.PP +\&\fBThe third step\fR is to pick which of Pod::Simple's interfaces you want to +use: +.IP Pod::Simple 4 +.IX Item "Pod::Simple" +The basic Pod::Simple interface that uses \f(CW_handle_element_start()\fR, +\&\f(CW_handle_element_end()\fR and \f(CW_handle_text()\fR. +.IP Pod::Simple::Methody 4 +.IX Item "Pod::Simple::Methody" +The Pod::Simple::Methody interface is event-based, similar to that of +HTML::Parser or XML::Parser's "Handlers". +.IP Pod::Simple::PullParser 4 +.IX Item "Pod::Simple::PullParser" +Pod::Simple::PullParser provides a token-stream interface, sort of +like HTML::TokeParser's interface. +.IP Pod::Simple::SimpleTree 4 +.IX Item "Pod::Simple::SimpleTree" +Pod::Simple::SimpleTree provides a simple tree interface, rather like +XML::Parser's "Tree" interface. Users familiar with XML handling will +be comfortable with this interface. Users interested in outputting XML, +should look into the modules that produce an XML representation of the +Pod stream, notably Pod::Simple::XMLOutStream; you can feed the output +of such a class to whatever XML parsing system you are most at home with. +.PP +\&\fBThe last step\fR 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 be sure to consider how to escape +text nodes containing arbitrary text, and what to do with text +nodes that represent preformatted text (from verbatim sections). +.SH Events +.IX Header "Events" +TODO intro... mention that events are supplied for implicits, like for +missing >'s +.PP +In the following section, we use XML to represent the event structure +associated with a particular construct. That is, an opening tag +represents the element start, the attributes of that opening tag are +the attributes given to the callback, and the closing tag represents +the end element. +.PP +Three callback methods must be supplied by a class extending +Pod::Simple to receive the corresponding event: +.ie n .IP """$parser\->_handle_element_start( \fIelement_name\fR, \fIattr_hashref\fR )""" 4 +.el .IP "\f(CW$parser\->_handle_element_start( \fR\f(CIelement_name\fR\f(CW, \fR\f(CIattr_hashref\fR\f(CW )\fR" 4 +.IX Item "$parser->_handle_element_start( element_name, attr_hashref )" +.PD 0 +.ie n .IP """$parser\->_handle_element_end( \fIelement_name\fR )""" 4 +.el .IP "\f(CW$parser\->_handle_element_end( \fR\f(CIelement_name\fR\f(CW )\fR" 4 +.IX Item "$parser->_handle_element_end( element_name )" +.ie n .IP """$parser\->_handle_text( \fItext_string\fR )""" 4 +.el .IP "\f(CW$parser\->_handle_text( \fR\f(CItext_string\fR\f(CW )\fR" 4 +.IX Item "$parser->_handle_text( text_string )" +.PD +.PP +Here's the comprehensive list of values you can expect as +\&\fIelement_name\fR in your implementation of \f(CW\*(C`_handle_element_start\*(C'\fR +and \f(CW\*(C`_handle_element_end\*(C'\fR:: +.IP "events with an element_name of Document" 4 +.IX Item "events with an element_name of Document" +Parsing a document produces this event structure: +.Sp +.Vb 3 +\& <Document start_line="543"> +\& ...all events... +\& </Document> +.Ve +.Sp +The value of the \fIstart_line\fR attribute will be the line number of the first +Pod directive in the document. +.Sp +If there is no Pod in the given document, then the +event structure will be this: +.Sp +.Vb 2 +\& <Document contentless="1" start_line="543"> +\& </Document> +.Ve +.Sp +In that case, the value of the \fIstart_line\fR attribute will not be meaningful; +under current implementations, it will probably be the line number of the +last line in the file. +.IP "events with an element_name of Para" 4 +.IX 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: +.Sp +.Vb 3 +\& <Para start_line="543"> +\& ...all events in this paragraph... +\& </Para> +.Ve +.Sp +The value of the \fIstart_line\fR attribute will be the line number of the start +of the paragraph. +.Sp +For example, parsing this paragraph of Pod: +.Sp +.Vb 2 +\& The value of the I<start_line> attribute will be the +\& line number of the start of the paragraph. +.Ve +.Sp +produces this event structure: +.Sp +.Vb 8 +\& <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> +.Ve +.IP "events with an element_name of B, C, F, or I." 4 +.IX Item "events with an element_name of B, C, F, or I." +Parsing a B<...> formatting code (or of course any of its +semantically identical syntactic variants +B<<\ ...\ >>, +or B<<<<\ ...\ >>>>, etc.) +produces this event structure: +.Sp +.Vb 3 +\& <B> +\& ...stuff... +\& </B> +.Ve +.Sp +Currently, there are no attributes conveyed. +.Sp +Parsing C, F, or I codes produce the same structure, with only a +different element name. +.Sp +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. +.IP "events with an element_name of S" 4 +.IX Item "events with an element_name of S" +Normally, parsing an S<...> sequence produces this event +structure, just as if it were a B/C/F/I code: +.Sp +.Vb 3 +\& <S> +\& ...stuff... +\& </S> +.Ve +.Sp +However, Pod::Simple (and presumably all derived parsers) offers the +\&\f(CW\*(C`nbsp_for_S\*(C'\fR 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 S<...>, but which has a code/character that +means non-breaking space. +.IP "events with an element_name of X" 4 +.IX Item "events with an element_name of X" +Normally, parsing an X<...> sequence produces this event +structure, just as if it were a B/C/F/I code: +.Sp +.Vb 3 +\& <X> +\& ...stuff... +\& </X> +.Ve +.Sp +However, Pod::Simple (and presumably all derived parsers) offers the +\&\f(CW\*(C`nix_X_codes\*(C'\fR 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. +.IP "events with an element_name of L" 4 +.IX Item "events with an element_name of L" +Because the L<...> 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. +.Sp +There are, at first glance, three kinds of L links: URL, man, and pod. +.Sp +When a L<\fIsome_url\fR> code is parsed, it produces this event +structure: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="that_url" to="that_url" type="url"> +\& that_url +\& </L> +.Ve +.Sp +The \f(CW\*(C`type="url"\*(C'\fR attribute is always specified for this type of +L code. +.Sp +For example, this Pod source: +.Sp +.Vb 1 +\& L<http://www.perl.com/CPAN/authors/> +.Ve +.Sp +produces this event structure: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url"> +\& http://www.perl.com/CPAN/authors/ +\& </L> +.Ve +.Sp +When a L<\fImanpage(section)\fR> code is parsed (and these are +fairly rare and not terribly useful), it produces this event structure: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man"> +\& manpage(section) +\& </L> +.Ve +.Sp +The \f(CW\*(C`type="man"\*(C'\fR attribute is always specified for this type of +L code. +.Sp +For example, this Pod source: +.Sp +.Vb 1 +\& L<crontab(5)> +.Ve +.Sp +produces this event structure: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man"> +\& crontab(5) +\& </L> +.Ve +.Sp +In the rare cases where a man page link has a section specified, that text appears +in a \fIsection\fR attribute. For example, this Pod source: +.Sp +.Vb 1 +\& L<crontab(5)/"ENVIRONMENT"> +.Ve +.Sp +will produce this event structure: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="crontab(5)/"ENVIRONMENT"" section="ENVIRONMENT" to="crontab(5)" type="man"> +\& "ENVIRONMENT" in crontab(5) +\& </L> +.Ve +.Sp +In the rare case where the Pod document has code like +L<\fIsometext\fR|\fImanpage(section)\fR>, then the \fIsometext\fR will appear +as the content of the element, the \fImanpage(section)\fR text will appear +only as the value of the \fIto\fR attribute, and there will be no +\&\f(CW\*(C`content\-implicit="yes"\*(C'\fR 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 +\&\fInot\fR have to infer the link text, because that L code explicitly specified +some link text.) +.Sp +For example, this Pod source: +.Sp +.Vb 1 +\& L<hell itself!|crontab(5)> +.Ve +.Sp +will produce this event structure: +.Sp +.Vb 3 +\& <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man"> +\& hell itself! +\& </L> +.Ve +.Sp +The last type of L structure is for links to/within Pod documents. It is +the most complex because it can have a \fIto\fR attribute, \fIor\fR a +\&\fIsection\fR attribute, or both. The \f(CW\*(C`type="pod"\*(C'\fR attribute is always +specified for this type of L code. +.Sp +In the most common case, the simple case of a L<podpage> code +produces this event structure: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="podpage" to="podpage" type="pod"> +\& podpage +\& </L> +.Ve +.Sp +For example, this Pod source: +.Sp +.Vb 1 +\& L<Net::Ping> +.Ve +.Sp +produces this event structure: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod"> +\& Net::Ping +\& </L> +.Ve +.Sp +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 L<\fIsometext\fR|\fImanpage(section)\fR> +case discussed above. For example, this Pod source: +.Sp +.Vb 1 +\& L<Perl Error Messages|perldiag> +.Ve +.Sp +produces this event structure: +.Sp +.Vb 3 +\& <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod"> +\& Perl Error Messages +\& </L> +.Ve +.Sp +In cases of links to a section in the current Pod document, +there is a \fIsection\fR attribute instead of a \fIto\fR attribute. +For example, this Pod source: +.Sp +.Vb 1 +\& L</"Member Data"> +.Ve +.Sp +produces this event structure: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="/"Member Data"" section="Member Data" type="pod"> +\& "Member Data" +\& </L> +.Ve +.Sp +As another example, this Pod source: +.Sp +.Vb 1 +\& L<the various attributes|/"Member Data"> +.Ve +.Sp +produces this event structure: +.Sp +.Vb 3 +\& <L raw="the various attributes|/"Member Data"" section="Member Data" type="pod"> +\& the various attributes +\& </L> +.Ve +.Sp +In cases of links to a section in a different Pod document, +there are both a \fIsection\fR attribute and a to attribute. +For example, this Pod source: +.Sp +.Vb 1 +\& L<perlsyn/"Basic BLOCKs and Switch Statements"> +.Ve +.Sp +produces this event structure: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod"> +\& "Basic BLOCKs and Switch Statements" in perlsyn +\& </L> +.Ve +.Sp +As another example, this Pod source: +.Sp +.Vb 1 +\& L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"> +.Ve +.Sp +produces this event structure: +.Sp +.Vb 3 +\& <L raw="SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod"> +\& SWITCH statements +\& </L> +.Ve +.Sp +Incidentally, note that we do not distinguish between these syntaxes: +.Sp +.Vb 4 +\& L</"Member Data"> +\& L<"Member Data"> +\& L</Member Data> +\& L<Member Data> [deprecated syntax] +.Ve +.Sp +That is, they all produce the same event structure (for the most part), namely: +.Sp +.Vb 3 +\& <L content\-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod"> +\& "Member Data" +\& </L> +.Ve +.Sp +The \fIraw\fR attribute depends on what the raw content of the \f(CW\*(C`L<>\*(C'\fR is, +so that is why the event structure is the same "for the most part". +.Sp +If you have not guessed it yet, the \fIraw\fR attribute contains the raw, +original, unescaped content of the \f(CW\*(C`L<>\*(C'\fR formatting code. In addition +to the examples above, take notice of the following event structure produced +by the following \f(CW\*(C`L<>\*(C'\fR formatting code. +.Sp +.Vb 1 +\& L<click B<here>|page/About the C<\-M> switch> +\& +\& <L raw="click B<here>|page/About the C<\-M> switch" section="About the \-M switch" to="page" type="pod"> +\& click B<here> +\& </L> +.Ve +.Sp +Specifically, notice that the formatting codes are present and unescaped +in \fIraw\fR. +.Sp +There is a known bug in the \fIraw\fR attribute where any surrounding whitespace +is condensed into a single ' '. For example, given L< link>, \fIraw\fR +will be " link". +.IP "events with an element_name of E or Z" 4 +.IX Item "events with an element_name of E or Z" +While there are Pod codes E<...> and Z<>, these +\&\fIdo not\fR produce any E or Z events \-\- that is, there are no such +events as E or Z. +.IP "events with an element_name of Verbatim" 4 +.IX Item "events with an element_name of Verbatim" +When a Pod verbatim paragraph (AKA "codeblock") is parsed, it +produces this event structure: +.Sp +.Vb 3 +\& <Verbatim start_line="543" xml:space="preserve"> +\& ...text... +\& </Verbatim> +.Ve +.Sp +The value of the \fIstart_line\fR attribute will be the line number of the +first line of this verbatim block. The \fIxml:space\fR attribute is always +present, and always has the value "preserve". +.Sp +The text content will have tabs already expanded. +.IP "events with an element_name of head1 .. head4" 4 +.IX Item "events with an element_name of head1 .. head4" +When a "=head1 ..." directive is parsed, it produces this event +structure: +.Sp +.Vb 3 +\& <head1> +\& ...stuff... +\& </head1> +.Ve +.Sp +For example, a directive consisting of this: +.Sp +.Vb 1 +\& =head1 Options to C<new> et al. +.Ve +.Sp +will produce this event structure: +.Sp +.Vb 7 +\& <head1 start_line="543"> +\& Options to +\& <C> +\& new +\& </C> +\& et al. +\& </head1> +.Ve +.Sp +"=head2" through "=head4" directives are the same, except for the element +names in the event structure. +.IP "events with an element_name of encoding" 4 +.IX Item "events with an element_name of encoding" +In the default case, the events corresponding to \f(CW\*(C`=encoding\*(C'\fR directives +are not emitted. They are emitted if \f(CW\*(C`keep_encoding_directive\*(C'\fR is true. +In that case they produce event structures like +"events with an element_name of head1 .. head4" above. +.IP "events with an element_name of over-bullet" 4 +.IX Item "events with an element_name of over-bullet" +When an "=over ... =back" block is parsed where the items are +a bulleted list, it will produce this event structure: +.Sp +.Vb 6 +\& <over\-bullet indent="4" start_line="543"> +\& <item\-bullet start_line="545"> +\& ...Stuff... +\& </item\-bullet> +\& ...more item\-bullets... +\& </over\-bullet fake\-closer="1"> +.Ve +.Sp +The attribute \fIfake-closer\fR is only present if it is a true value; it is not +present if it is a false value. It is shown in the above example to illustrate +where the attribute is (in the \fBclosing\fR tag). It signifies that the \f(CW\*(C`=over\*(C'\fR +did not have a matching \f(CW\*(C`=back\*(C'\fR, and thus Pod::Simple had to create a fake +closer. +.Sp +For example, this Pod source: +.Sp +.Vb 1 +\& =over +\& +\& =item * +\& +\& Something +\& +\& =back +.Ve +.Sp +Would produce an event structure that does \fBnot\fR have the \fIfake-closer\fR +attribute, whereas this Pod source: +.Sp +.Vb 1 +\& =over +\& +\& =item * +\& +\& Gasp! An unclosed =over block! +.Ve +.Sp +would. The rest of the over\-* examples will not demonstrate this attribute, +but they all can have it. See Pod::Checker's source for an example of this +attribute being used. +.Sp +The value of the \fIindent\fR attribute is whatever value is after the +"=over" directive, as in "=over 8". If no such value is specified +in the directive, then the \fIindent\fR attribute has the value "4". +.Sp +For example, this Pod source: +.Sp +.Vb 1 +\& =over +\& +\& =item * +\& +\& Stuff +\& +\& =item * +\& +\& Bar I<baz>! +\& +\& =back +.Ve +.Sp +produces this event structure: +.Sp +.Vb 8 +\& <over\-bullet indent="4" start_line="10"> +\& <item\-bullet start_line="12"> +\& Stuff +\& </item\-bullet> +\& <item\-bullet start_line="14"> +\& Bar <I>baz</I>! +\& </item\-bullet> +\& </over\-bullet> +.Ve +.IP "events with an element_name of over-number" 4 +.IX Item "events with an element_name of over-number" +When an "=over ... =back" block is parsed where the items are +a numbered list, it will produce this event structure: +.Sp +.Vb 6 +\& <over\-number indent="4" start_line="543"> +\& <item\-number number="1" start_line="545"> +\& ...Stuff... +\& </item\-number> +\& ...more item\-number... +\& </over\-bullet> +.Ve +.Sp +This is like the "over-bullet" event structure; but note that the contents +are "item-number" instead of "item-bullet", and note that they will have +a "number" attribute, which some formatters/processors may ignore +(since, for example, there's no need for it in HTML when producing +an "<UL><LI>...</LI>...</UL>" structure), but which any processor may use. +.Sp +Note that the values for the \fInumber\fR attributes of "item-number" +elements in a given "over-number" area \fIwill\fR start at 1 and go up by +one each time. If the Pod source doesn't follow that order (even though +it really should!), whatever numbers it has will be ignored (with +the correct values being put in the \fInumber\fR attributes), and an error +message might be issued to the user. +.IP "events with an element_name of over-text" 4 +.IX Item "events with an element_name of over-text" +These events are somewhat unlike the other over\-* +structures, as far as what their contents are. When +an "=over ... =back" block is parsed where the items are +a list of text "subheadings", it will produce this event structure: +.Sp +.Vb 8 +\& <over\-text indent="4" start_line="543"> +\& <item\-text> +\& ...stuff... +\& </item\-text> +\& ...stuff (generally Para or Verbatim elements)... +\& <item\-text> +\& ...more item\-text and/or stuff... +\& </over\-text> +.Ve +.Sp +The \fIindent\fR and \fIfake-closer\fR attributes are as with the other over\-* events. +.Sp +For example, this Pod source: +.Sp +.Vb 1 +\& =over +\& +\& =item Foo +\& +\& Stuff +\& +\& =item Bar I<baz>! +\& +\& Quux +\& +\& =back +.Ve +.Sp +produces this event structure: +.Sp +.Vb 10 +\& <over\-text indent="4" start_line="20"> +\& <item\-text start_line="22"> +\& Foo +\& </item\-text> +\& <Para start_line="24"> +\& Stuff +\& </Para> +\& <item\-text start_line="26"> +\& Bar +\& <I> +\& baz +\& </I> +\& ! +\& </item\-text> +\& <Para start_line="28"> +\& Quux +\& </Para> +\& </over\-text> +.Ve +.IP "events with an element_name of over-block" 4 +.IX Item "events with an element_name of over-block" +These events are somewhat unlike the other over\-* +structures, as far as what their contents are. When +an "=over ... =back" block is parsed where there are no items, +it will produce this event structure: +.Sp +.Vb 3 +\& <over\-block indent="4" start_line="543"> +\& ...stuff (generally Para or Verbatim elements)... +\& </over\-block> +.Ve +.Sp +The \fIindent\fR and \fIfake-closer\fR attributes are as with the other over\-* events. +.Sp +For example, this Pod source: +.Sp +.Vb 1 +\& =over +\& +\& For cutting off our trade with all parts of the world +\& +\& For transporting us beyond seas to be tried for pretended offenses +\& +\& He is at this time transporting large armies of foreign mercenaries to +\& complete the works of death, desolation and tyranny, already begun with +\& circumstances of cruelty and perfidy scarcely paralleled in the most +\& barbarous ages, and totally unworthy the head of a civilized nation. +\& +\& =back +.Ve +.Sp +will produce this event structure: +.Sp +.Vb 11 +\& <over\-block indent="4" start_line="2"> +\& <Para start_line="4"> +\& For cutting off our trade with all parts of the world +\& </Para> +\& <Para start_line="6"> +\& For transporting us beyond seas to be tried for pretended offenses +\& </Para> +\& <Para start_line="8"> +\& He is at this time transporting large armies of [...more text...] +\& </Para> +\& </over\-block> +.Ve +.IP "events with an element_name of over-empty" 4 +.IX Item "events with an element_name of over-empty" +\&\fBNote: These events are only triggered if \fR\f(CBparse_empty_lists()\fR\fB is set to a +true value.\fR +.Sp +These events are somewhat unlike the other over\-* structures, as far as what +their contents are. When an "=over ... =back" block is parsed where there +is no content, it will produce this event structure: +.Sp +.Vb 2 +\& <over\-empty indent="4" start_line="543"> +\& </over\-empty> +.Ve +.Sp +The \fIindent\fR and \fIfake-closer\fR attributes are as with the other over\-* events. +.Sp +For example, this Pod source: +.Sp +.Vb 1 +\& =over +\& +\& =over +\& +\& =back +\& +\& =back +.Ve +.Sp +will produce this event structure: +.Sp +.Vb 4 +\& <over\-block indent="4" start_line="1"> +\& <over\-empty indent="4" start_line="3"> +\& </over\-empty> +\& </over\-block> +.Ve +.Sp +Note that the outer \f(CW\*(C`=over\*(C'\fR is a block because it has no \f(CW\*(C`=item\*(C'\fRs but still +has content: the inner \f(CW\*(C`=over\*(C'\fR. The inner \f(CW\*(C`=over\*(C'\fR, in turn, is completely +empty, and is treated as such. +.IP "events with an element_name of item-bullet" 4 +.IX Item "events with an element_name of item-bullet" +See "events with an element_name of over-bullet", above. +.IP "events with an element_name of item-number" 4 +.IX Item "events with an element_name of item-number" +See "events with an element_name of over-number", above. +.IP "events with an element_name of item-text" 4 +.IX Item "events with an element_name of item-text" +See "events with an element_name of over-text", above. +.IP "events with an element_name of for" 4 +.IX Item "events with an element_name of for" +TODO... +.IP "events with an element_name of Data" 4 +.IX Item "events with an element_name of Data" +TODO... +.SH "More Pod::Simple Methods" +.IX Header "More Pod::Simple Methods" +Pod::Simple provides a lot of methods that aren't generally interesting +to the end user of an existing Pod formatter, but some of which you +might find useful in writing a Pod formatter. They are listed below. The +first several methods (the accept_* methods) are for declaring the +capabilities of your parser, notably what \f(CW\*(C`=for \fR\f(CItargetname\fR\f(CW\*(C'\fR sections +it's interested in, what extra N<...> codes it accepts beyond +the ones described in the \fIperlpod\fR. +.ie n .IP """$parser\->accept_targets( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->accept_targets( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->accept_targets( SOMEVALUE )" +As the parser sees sections like: +.Sp +.Vb 1 +\& =for html <img src="fig1.jpg"> +.Ve +.Sp +or +.Sp +.Vb 1 +\& =begin html +\& +\& <img src="fig1.jpg"> +\& +\& =end html +.Ve +.Sp +\&...the parser will ignore these sections unless your subclass has +specified that it wants to see sections targeted to "html" (or whatever +the formatter name is). +.Sp +If you want to process all sections, even if they're not targeted for you, +call this before you start parsing: +.Sp +.Vb 1 +\& $parser\->accept_targets(\*(Aq*\*(Aq); +.Ve +.ie n .IP """$parser\->accept_targets_as_text( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->accept_targets_as_text( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->accept_targets_as_text( SOMEVALUE )" +This is like accept_targets, except that it specifies also that the +content of sections for this target should be treated as Pod text even +if the target name in "=for \fItargetname\fR" doesn't start with a ":". +.Sp +At time of writing, I don't think you'll need to use this. +.ie n .IP """$parser\->accept_codes( \fICodename\fR, \fICodename\fR... )""" 4 +.el .IP "\f(CW$parser\->accept_codes( \fR\f(CICodename\fR\f(CW, \fR\f(CICodename\fR\f(CW... )\fR" 4 +.IX Item "$parser->accept_codes( Codename, Codename... )" +This tells the parser that you accept additional formatting codes, +beyond just the standard ones (I B C L F S X, plus the two weird ones +you don't actually see in the parse tree, Z and E). For example, to also +accept codes "N", "R", and "W": +.Sp +.Vb 1 +\& $parser\->accept_codes( qw( N R W ) ); +.Ve +.Sp +\&\fBTODO: document how this interacts with =extend, and long element names\fR +.ie n .IP """$parser\->accept_directive_as_data( \fIdirective_name\fR )""" 4 +.el .IP "\f(CW$parser\->accept_directive_as_data( \fR\f(CIdirective_name\fR\f(CW )\fR" 4 +.IX Item "$parser->accept_directive_as_data( directive_name )" +.PD 0 +.ie n .IP """$parser\->accept_directive_as_verbatim( \fIdirective_name\fR )""" 4 +.el .IP "\f(CW$parser\->accept_directive_as_verbatim( \fR\f(CIdirective_name\fR\f(CW )\fR" 4 +.IX Item "$parser->accept_directive_as_verbatim( directive_name )" +.ie n .IP """$parser\->accept_directive_as_processed( \fIdirective_name\fR )""" 4 +.el .IP "\f(CW$parser\->accept_directive_as_processed( \fR\f(CIdirective_name\fR\f(CW )\fR" 4 +.IX Item "$parser->accept_directive_as_processed( directive_name )" +.PD +In the unlikely situation that you need to tell the parser that you will +accept additional directives ("=foo" things), you need to first set the +parser to treat its content as data (i.e., not really processed at +all), or as verbatim (mostly just expanding tabs), or as processed text +(parsing formatting codes like B<...>). +.Sp +For example, to accept a new directive "=method", you'd presumably +use: +.Sp +.Vb 1 +\& $parser\->accept_directive_as_processed("method"); +.Ve +.Sp +so that you could have Pod lines like: +.Sp +.Vb 1 +\& =method I<$whatever> thing B<um> +.Ve +.Sp +Making up your own directives breaks compatibility with other Pod +formatters, in a way that using "=for \fItarget\fR ..." lines doesn't; +however, you may find this useful if you're making a Pod superset +format where you don't need to worry about compatibility. +.ie n .IP """$parser\->nbsp_for_S( \fIBOOLEAN\fR );""" 4 +.el .IP "\f(CW$parser\->nbsp_for_S( \fR\f(CIBOOLEAN\fR\f(CW );\fR" 4 +.IX Item "$parser->nbsp_for_S( BOOLEAN );" +Setting this attribute to a true value (and by default it is false) will +turn "S<...>" sequences into sequences of words separated by +\&\f(CW\*(C`\exA0\*(C'\fR (non-breaking space) characters. For example, it will take this: +.Sp +.Vb 1 +\& I like S<Dutch apple pie>, don\*(Aqt you? +.Ve +.Sp +and treat it as if it were: +.Sp +.Vb 1 +\& I like DutchE<nbsp>appleE<nbsp>pie, don\*(Aqt you? +.Ve +.Sp +This is handy for output formats that don't have anything quite like an +"S<...>" code, but which do have a code for non-breaking space. +.Sp +There is currently no method for going the other way; but I can +probably provide one upon request. +.ie n .IP """$parser\->version_report()""" 4 +.el .IP \f(CW$parser\->version_report()\fR 4 +.IX Item "$parser->version_report()" +This returns a string reporting the \f(CW$VERSION\fR value from your module (and +its classname) as well as the \f(CW$VERSION\fR value of Pod::Simple. Note that +perlpodspec requires output formats (wherever possible) to note +this detail in a comment in the output format. For example, for +some kind of SGML output format: +.Sp +.Vb 1 +\& print OUT "<!\-\- \en", $parser\->version_report, "\en \-\->"; +.Ve +.ie n .IP """$parser\->pod_para_count()""" 4 +.el .IP \f(CW$parser\->pod_para_count()\fR 4 +.IX Item "$parser->pod_para_count()" +This returns the count of Pod paragraphs seen so far. +.ie n .IP """$parser\->line_count()""" 4 +.el .IP \f(CW$parser\->line_count()\fR 4 +.IX Item "$parser->line_count()" +This is the current line number being parsed. But you might find the +"line_number" event attribute more accurate, when it is present. +.ie n .IP """$parser\->nix_X_codes( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->nix_X_codes( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->nix_X_codes( SOMEVALUE )" +This attribute, when set to a true value (and it is false by default) +ignores any "X<...>" sequences in the document being parsed. +Many formats don't actually use the content of these codes, so have +no reason to process them. +.ie n .IP """$parser\->keep_encoding_directive( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->keep_encoding_directive( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->keep_encoding_directive( SOMEVALUE )" +This attribute, when set to a true value (it is false by default) +will keep \f(CW\*(C`=encoding\*(C'\fR and its content in the event structure. Most +formats don't actually need to process the content of an \f(CW\*(C`=encoding\*(C'\fR +directive, even when this directive sets the encoding and the +processor makes use of the encoding information. Indeed, it is +possible to know the encoding without processing the directive +content. +.ie n .IP """$parser\->merge_text( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->merge_text( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->merge_text( SOMEVALUE )" +This attribute, when set to a true value (and it is false by default) +makes sure that only one event (or token, or node) will be created +for any single contiguous sequence of text. For example, consider +this somewhat contrived example: +.Sp +.Vb 1 +\& I just LOVE Z<>hotE<32>apple pie! +.Ve +.Sp +When that is parsed and events are about to be called on it, it may +actually seem to be four different text events, one right after another: +one event for "I just LOVE ", one for "hot", one for " ", and one for +"apple pie!". But if you have merge_text on, then you're guaranteed +that it will be fired as one text event: "I just LOVE hot apple pie!". +.ie n .IP """$parser\->code_handler( \fICODE_REF\fR )""" 4 +.el .IP "\f(CW$parser\->code_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4 +.IX Item "$parser->code_handler( CODE_REF )" +This specifies code that should be called when a code line is seen +(i.e., a line outside of the Pod). Normally this is undef, meaning +that no code should be called. If you provide a routine, it should +start out like this: +.Sp +.Vb 4 +\& sub get_code_line { # or whatever you\*(Aqll call it +\& my($line, $line_number, $parser) = @_; +\& ... +\& } +.Ve +.Sp +Note, however, that sometimes the Pod events aren't processed in exactly +the same order as the code lines are \-\- i.e., if you have a file with +Pod, then code, then more Pod, sometimes the code will be processed (via +whatever you have code_handler call) before the all of the preceding Pod +has been processed. +.ie n .IP """$parser\->cut_handler( \fICODE_REF\fR )""" 4 +.el .IP "\f(CW$parser\->cut_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4 +.IX Item "$parser->cut_handler( CODE_REF )" +This is just like the code_handler attribute, except that it's for +"=cut" lines, not code lines. The same caveats apply. "=cut" lines are +unlikely to be interesting, but this is included for completeness. +.ie n .IP """$parser\->pod_handler( \fICODE_REF\fR )""" 4 +.el .IP "\f(CW$parser\->pod_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4 +.IX Item "$parser->pod_handler( CODE_REF )" +This is just like the code_handler attribute, except that it's for +"=pod" lines, not code lines. The same caveats apply. "=pod" lines are +unlikely to be interesting, but this is included for completeness. +.ie n .IP """$parser\->whiteline_handler( \fICODE_REF\fR )""" 4 +.el .IP "\f(CW$parser\->whiteline_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4 +.IX Item "$parser->whiteline_handler( CODE_REF )" +This is just like the code_handler attribute, except that it's for +lines that are seemingly blank but have whitespace (" " and/or "\et") on them, +not code lines. The same caveats apply. These lines are unlikely to be +interesting, but this is included for completeness. +.ie n .IP """$parser\->whine( \fIlinenumber\fR, \fIcomplaint string\fR )""" 4 +.el .IP "\f(CW$parser\->whine( \fR\f(CIlinenumber\fR\f(CW, \fR\f(CIcomplaint string\fR\f(CW )\fR" 4 +.IX Item "$parser->whine( linenumber, complaint string )" +This notes a problem in the Pod, which will be reported in the "Pod +Errors" section of the document and/or sent to STDERR, depending on the +values of the attributes \f(CW\*(C`no_whining\*(C'\fR, \f(CW\*(C`no_errata_section\*(C'\fR, and +\&\f(CW\*(C`complain_stderr\*(C'\fR. +.ie n .IP """$parser\->scream( \fIlinenumber\fR, \fIcomplaint string\fR )""" 4 +.el .IP "\f(CW$parser\->scream( \fR\f(CIlinenumber\fR\f(CW, \fR\f(CIcomplaint string\fR\f(CW )\fR" 4 +.IX Item "$parser->scream( linenumber, complaint string )" +This notes an error like \f(CW\*(C`whine\*(C'\fR does, except that it is not +suppressible with \f(CW\*(C`no_whining\*(C'\fR. This should be used only for very +serious errors. +.ie n .IP """$parser\->source_dead(1)""" 4 +.el .IP \f(CW$parser\->source_dead(1)\fR 4 +.IX Item "$parser->source_dead(1)" +This aborts parsing of the current document, by switching on the flag +that indicates that EOF has been seen. In particularly drastic cases, +you might want to do this. It's rather nicer than just calling +\&\f(CW\*(C`die\*(C'\fR! +.ie n .IP """$parser\->hide_line_numbers( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->hide_line_numbers( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->hide_line_numbers( SOMEVALUE )" +Some subclasses that indiscriminately dump event attributes (well, +except for ones beginning with "~") can use this object attribute for +refraining to dump the "start_line" attribute. +.ie n .IP """$parser\->no_whining( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->no_whining( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->no_whining( SOMEVALUE )" +This attribute, if set to true, will suppress reports of non-fatal +error messages. The default value is false, meaning that complaints +\&\fIare\fR reported. How they get reported depends on the values of +the attributes \f(CW\*(C`no_errata_section\*(C'\fR and \f(CW\*(C`complain_stderr\*(C'\fR. +.ie n .IP """$parser\->no_errata_section( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->no_errata_section( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->no_errata_section( SOMEVALUE )" +This attribute, if set to true, will suppress generation of an errata +section. The default value is false \-\- i.e., an errata section will be +generated. +.ie n .IP """$parser\->complain_stderr( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->complain_stderr( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->complain_stderr( SOMEVALUE )" +This attribute, if set to true will send complaints to STDERR. The +default value is false \-\- i.e., complaints do not go to STDERR. +.ie n .IP """$parser\->bare_output( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->bare_output( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->bare_output( SOMEVALUE )" +Some formatter subclasses use this as a flag for whether output should +have prologue and epilogue code omitted. For example, setting this to +true for an HTML formatter class should omit the +"<html><head><title>...</title><body>..." prologue and the +"</body></html>" epilogue. +.Sp +If you want to set this to true, you should probably also set +\&\f(CW\*(C`no_whining\*(C'\fR or at least \f(CW\*(C`no_errata_section\*(C'\fR to true. +.ie n .IP """$parser\->preserve_whitespace( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->preserve_whitespace( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->preserve_whitespace( SOMEVALUE )" +If you set this attribute to a true value, the parser will try to +preserve whitespace in the output. This means that such formatting +conventions as two spaces after periods will be preserved by the parser. +This is primarily useful for output formats that treat whitespace as +significant (such as text or *roff, but not HTML). +.ie n .IP """$parser\->parse_empty_lists( \fISOMEVALUE\fR )""" 4 +.el .IP "\f(CW$parser\->parse_empty_lists( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 +.IX Item "$parser->parse_empty_lists( SOMEVALUE )" +If this attribute is set to true, the parser will not ignore empty +\&\f(CW\*(C`=over\*(C'\fR/\f(CW\*(C`=back\*(C'\fR blocks. The type of \f(CW\*(C`=over\*(C'\fR will be \fIempty\fR, documented +above, "events with an element_name of over-empty". +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Pod::Simple \-\- event-based Pod-parsing framework +.PP +Pod::Simple::Methody \-\- like Pod::Simple, but each sort of event +calls its own method (like \f(CW\*(C`start_head3\*(C'\fR) +.PP +Pod::Simple::PullParser \-\- a Pod-parsing framework like Pod::Simple, +but with a token-stream interface +.PP +Pod::Simple::SimpleTree \-\- a Pod-parsing framework like Pod::Simple, +but with a tree interface +.PP +Pod::Simple::Checker \-\- a simple Pod::Simple subclass that reads +documents, and then makes a plaintext report of any errors found in the +document +.PP +Pod::Simple::DumpAsXML \-\- for dumping Pod documents as tidily +indented XML, showing each event on its own line +.PP +Pod::Simple::XMLOutStream \-\- dumps a Pod document as XML (without +introducing extra whitespace as Pod::Simple::DumpAsXML does). +.PP +Pod::Simple::DumpAsText \-\- for dumping Pod documents as tidily +indented text, showing each event on its own line +.PP +Pod::Simple::LinkSection \-\- class for objects representing the values +of the TODO and TODO attributes of L<...> elements +.PP +Pod::Escapes \-\- the module that Pod::Simple uses for evaluating +E<...> content +.PP +Pod::Simple::Text \-\- a simple plaintext formatter for Pod +.PP +Pod::Simple::TextContent \-\- like Pod::Simple::Text, but +makes no effort for indent or wrap the text being formatted +.PP +Pod::Simple::HTML \-\- a simple HTML formatter for Pod +.PP +perlpod +.PP +perlpodspec +.PP +perldoc +.SH SUPPORT +.IX Header "SUPPORT" +Questions or discussion about POD and Pod::Simple should be sent to the +pod\-people@perl.org mail list. Send an empty email to +pod\-people\-subscribe@perl.org to subscribe. +.PP +This module is managed in an open GitHub repository, +<https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or +to clone <git://github.com/perl\-pod/pod\-simple.git> and send patches! +.PP +Patches against Pod::Simple are welcome. Please send bug reports to +<bug\-pod\-simple@rt.cpan.org>. +.SH "COPYRIGHT AND DISCLAIMERS" +.IX Header "COPYRIGHT AND DISCLAIMERS" +Copyright (c) 2002 Sean M. Burke. +.PP +This library is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. +.PP +This program is distributed in the hope that it will be useful, but +without any warranty; without even the implied warranty of +merchantability or fitness for a particular purpose. +.SH AUTHOR +.IX Header "AUTHOR" +Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. +But don't bother him, he's retired. +.PP +Pod::Simple is maintained by: +.IP \(bu 4 +Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR +.IP \(bu 4 +Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR +.IP \(bu 4 +David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR |