--- /dev/null
+
+=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">
+ "Member Data"
+ </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>!
+ </item-bullet>
+ </over-bullet>
+
+=item events with an element_name of over-number
+
+When an "=over ... Z<>=back" block is parsed where the items are
+a numbered list, it will produce this event structure:
+
+ <over-number indent="4" start_line="543">
+ <item-number number="1" start_line="545">
+ ...Stuff...
+ </item-number>
+ ...more item-number...
+ </over-bullet>
+
+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.
+
+Note that the values for the I<number> attributes of "item-number"
+elements in a given "over-number" area I<will> start at 1 and go up by
+one each time. If the Pod source doesn't follow that order (even though
+it really should should!), whatever numbers it has will be ignored (with
+the correct values being put in the I<number> attributes), and an error
+message might be issued to the user.
+
+=item events with an element_name of over-text
+
+These events are are somewhat unlike the other over-*
+structures, as far as what their contents are. When
+an "=over ... Z<>=back" block is parsed where the items are
+a list of text "subheadings", it will produce this event structure:
+
+ <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>
+
+The I<indent> attribute is as with the other over-* events.
+
+For example, this Pod source:
+
+ =over
+
+ =item Foo
+
+ Stuff
+
+ =item Bar I<baz>!
+
+ Quux
+
+ =back
+
+produces this event structure:
+
+ <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>
+
+
+
+=item events with an element_name of over-block
+
+These events are are somewhat unlike the other over-*
+structures, as far as what their contents are. When
+an "=over ... Z<>=back" block is parsed where there are no items,
+it will produce this event structure:
+
+ <over-block indent="4" start_line="543">
+ ...stuff (generally Para or Verbatim elements)...
+ </over-block>
+
+The I<indent> attribute is as with the other over-* events.
+
+For example, this Pod source:
+
+ =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.
+
+ =cut
+
+will produce this event structure:
+
+ <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>
+
+=item events with an element_name of item-bullet
+
+See L</"events with an element_name of over-bullet">, above.
+
+=item events with an element_name of item-number
+
+See L</"events with an element_name of over-number">, above.
+
+=item events with an element_name of item-text
+
+See L</"events with an element_name of over-text">, above.
+
+=item events with an element_name of for
+
+TODO...
+
+=item events with an element_name of Data
+
+TODO...
+
+=back
+
+
+
+=head1 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
+capabilites of your parser, notably what C<=for I<targetname>> sections
+it's interested in, what extra NE<lt>...E<gt> codes it accepts beyond
+the ones described in the I<perlpod>.
+
+=over
+
+=item C<< $parser->accept_targets( I<SOMEVALUE> ) >>
+
+As the parser sees sections like:
+
+ =for html <img src="fig1.jpg">
+
+or
+
+ =begin html
+
+ <img src="fig1.jpg">
+
+ =end html
+
+...the parser will ignore these sections unless your subclass has
+specified that it wants to see sections targetted to "html" (or whatever
+the formatter name is).
+
+If you want to process all sections, even if they're not targetted for you,
+call this before you start parsing:
+
+ $parser->accept_targets('*');
+
+=item C<< $parser->accept_targets_as_text( I<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 I<targetname>" doesn't start with a ":".
+
+At time of writing, I don't think you'll need to use this.
+
+
+=item C<< $parser->accept_codes( I<Codename>, I<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":
+
+ $parser->accept_codes( qw( N R W ) );
+
+B<TODO: document how this interacts with =extend, and long element names>
+
+
+=item C<< $parser->accept_directive_as_data( I<directive_name> ) >>
+
+=item C<< $parser->accept_directive_as_verbatim( I<directive_name> ) >>
+
+=item C<< $parser->accept_directive_as_processed( I<directive_name> ) >>
+
+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
+parset 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 BE<lt>...E<gt>).
+
+For example, to accept a new directive "=method", you'd presumably
+use:
+
+ $parser->accept_directive_as_processed("method");
+
+so that you could have Pod lines like:
+
+ =method I<$whatever> thing B<um>
+
+Making up your own directives breaks compatibility with other Pod
+formatters, in a way that using "=for I<target> ..." 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.
+
+
+=item C<< $parser->nbsp_for_S( I<BOOLEAN> ); >>
+
+Setting this attribute to a true value (and by default it is false) will
+turn "SE<lt>...E<gt>" sequences into sequences of words separated by
+C<\xA0> (non-breaking space) characters. For example, it will take this:
+
+ I like S<Dutch apple pie>, don't you?
+
+and treat it as if it were:
+
+ I like DutchE<nbsp>appleE<nbsp>pie, don't you?
+
+This is handy for output formats that don't have anything quite like an
+"SE<lt>...E<gt>" code, but which do have a code for non-breaking space.
+
+There is currently no method for going the other way; but I can
+probably provide one upon request.
+
+
+=item C<< $parser->version_report() >>
+
+This returns a string reporting the $VERSION value from your module (and
+its classname) as well as the $VERSION value of Pod::Simple. Note that
+L<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:
+
+ print OUT "<!-- \n", $parser->version_report, "\n -->";
+
+
+=item C<< $parser->pod_para_count() >>
+
+This returns the count of Pod paragraphs seen so far.
+
+
+=item C<< $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.
+
+
+=item C<< $parser->nix_X_codes( I<SOMEVALUE> ) >>
+
+This attribute, when set to a true value (and it is false by default)
+ignores any "XE<lt>...E<gt>" sequences in the document being parsed.
+Many formats don't actually use the content of these codes, so have
+no reason to process them.
+
+
+=item C<< $parser->merge_text( I<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:
+
+ I just LOVE Z<>hotE<32>apple pie!
+
+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!".
+
+
+=item C<< $parser->code_handler( I<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:
+
+ sub get_code_line { # or whatever you'll call it
+ my($line, $line_number, $parser) = @_;
+ ...
+ }
+
+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.
+
+
+=item C<< $parser->cut_handler( I<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.
+
+
+=item C<< $parser->whine( I<linenumber>, I<complaint string> ) >>
+
+This notes a problem in the Pod, which will be reported to in the "Pod
+Errors" section of the document and/or send to STDERR, depending on the
+values of the attributes C<no_whining>, C<no_errata_section>, and
+C<complain_stderr>.
+
+=item C<< $parser->scream( I<linenumber>, I<complaint string> ) >>
+
+This notes an error like C<whine> does, except that it is not
+suppressable with C<no_whining>. This should be used only for very
+serious errors.
+
+
+=item C<< $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
+C<die>!
+
+=item C<< $parser->hide_line_numbers( I<SOMEVALUE> ) >>
+
+Some subclasses that indescriminately dump event attributes (well,
+except for ones beginning with "~") can use this object attribute for
+refraining to dump the "start_line" attribute.
+
+=item C<< $parser->no_whining( I<SOMEVALUE> ) >>
+
+This attribute, if set to true, will suppress reports of non-fatal
+error messages. The default value is false, meaning that complaints
+I<are> reported. How they get reported depends on the values of
+the attributes C<no_errata_section> and C<complain_stderr>.
+
+=item C<< $parser->no_errata_section( I<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.
+
+=item C<< $parser->complain_stderr( I<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.
+
+=item C<< $parser->bare_output( I<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.
+
+If you want to set this to true, you should probably also set
+C<no_whining> or at least C<no_errata_section> to true.
+
+=item C<< $parser->preserve_whitespace( I<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).
+
+=back
+
+
+=head1 SEE ALSO
+
+L<Pod::Simple> -- event-based Pod-parsing framework
+
+L<Pod::Simple::Methody> -- like Pod::Simple, but each sort of event
+calls its own method (like C<start_head3>)
+
+L<Pod::Simple::PullParser> -- a Pod-parsing framework like Pod::Simple,
+but with a token-stream interface
+
+L<Pod::Simple::SimpleTree> -- a Pod-parsing framework like Pod::Simple,
+but with a tree interface
+
+L<Pod::Simple::Checker> -- a simple Pod::Simple subclass that reads
+documents, and then makes a plaintext report of any errors found in the
+document
+
+L<Pod::Simple::DumpAsXML> -- for dumping Pod documents as tidily
+indented XML, showing each event on its own line
+
+L<Pod::Simple::XMLOutStream> -- dumps a Pod document as XML (without
+introducing extra whitespace as Pod::Simple::DumpAsXML does).
+
+L<Pod::Simple::DumpAsText> -- for dumping Pod documents as tidily
+indented text, showing each event on its own line
+
+L<Pod::Simple::LinkSection> -- class for objects representing the values
+of the TODO and TODO attributes of LE<lt>...E<gt> elements
+
+L<Pod::Escapes> -- the module the Pod::Simple uses for evaluating
+EE<lt>...E<gt> content
+
+L<Pod::Simple::Text> -- a simple plaintext formatter for Pod
+
+L<Pod::Simple::TextContent> -- like Pod::Simple::Text, but
+makes no effort for indent or wrap the text being formatted
+
+L<perlpod|perlpod>
+
+L<perlpodspec|perlpodspec>
+
+L<perldoc>
+
+
+=head1 COPYRIGHT AND DISCLAIMERS
+
+Copyright (c) 2002 Sean M. Burke. All rights reserved.
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+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.
+
+=head1 AUTHOR
+
+Sean M. Burke C<sburke@cpan.org>
+
+
+=for notes
+Hm, my old podchecker version (1.2) says:
+ *** WARNING: node 'http://search.cpan.org/' contains non-escaped | or / at line 38 in file Subclassing.pod
+ *** WARNING: node 'http://lists.perl.org/showlist.cgi?name=pod-people' contains non-escaped | or / at line 41 in file Subclassing.pod
+Yes, L<...> is hard.
+
+
+=cut
+
+
projects / dh-make-perl / blobdiff