diff options
author | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2014-04-23 22:10:41 +0000 |
commit | e5c6e6d9c56fbfc54508fa2c32b03a5a870b7553 (patch) | |
tree | 40fcc93aa383c1e45d31ddc42d03f15cbada7076 /Master/tlpkg/tlperl/lib/Pod | |
parent | 300c1eb6d37d46078d448d6d58938d5a80cd68ff (diff) |
oops, remove 5.16 tlperl files
git-svn-id: svn://tug.org/texlive/trunk@33649 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Pod/Simple.pod | 395 | ||||
-rw-r--r-- | Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod | 1057 |
2 files changed, 0 insertions, 1452 deletions
diff --git a/Master/tlpkg/tlperl/lib/Pod/Simple.pod b/Master/tlpkg/tlperl/lib/Pod/Simple.pod deleted file mode 100644 index a8ad211d3b6..00000000000 --- a/Master/tlpkg/tlperl/lib/Pod/Simple.pod +++ /dev/null @@ -1,395 +0,0 @@ - -=head1 NAME - -Pod::Simple - framework for parsing Pod - -=head1 SYNOPSIS - - TODO - -=head1 DESCRIPTION - -Pod::Simple is a Perl library for parsing text in the Pod ("plain old -documentation") markup language that is typically used for writing -documentation for Perl and for Perl modules. The Pod format is explained -L<perlpod>; the most common formatter is called C<perldoc>. - -Pod formatters can use Pod::Simple to parse Pod documents and render them into -plain text, HTML, or any number of other formats. Typically, such formatters -will be subclasses of Pod::Simple, and so they will inherit its methods, like -C<parse_file>. - -If you're reading this document just because you have a Pod-processing -subclass that you want to use, this document (plus the documentation for the -subclass) is probably all you need to read. - -If you're reading this document because you want to write a formatter -subclass, continue reading it and then read L<Pod::Simple::Subclassing>, and -then possibly even read L<perlpodspec> (some of which is for parser-writers, -but much of which is notes to formatter-writers). - -=head1 MAIN METHODS - -=over - -=item C<< $parser = I<SomeClass>->new(); >> - -This returns a new parser object, where I<C<SomeClass>> is a subclass -of Pod::Simple. - -=item C<< $parser->output_fh( *OUT ); >> - -This sets the filehandle that C<$parser>'s output will be written to. -You can pass C<*STDOUT>, otherwise you should probably do something -like this: - - my $outfile = "output.txt"; - open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!"; - $parser->output_fh(*TXTOUT); - -...before you call one of the C<< $parser->parse_I<whatever> >> methods. - -=item C<< $parser->output_string( \$somestring ); >> - -This sets the string that C<$parser>'s output will be sent to, -instead of any filehandle. - - -=item C<< $parser->parse_file( I<$some_filename> ); >> - -=item C<< $parser->parse_file( *INPUT_FH ); >> - -This reads the Pod content of the file (or filehandle) that you specify, -and processes it with that C<$parser> object, according to however -C<$parser>'s class works, and according to whatever parser options you -have set up for this C<$parser> object. - -=item C<< $parser->parse_string_document( I<$all_content> ); >> - -This works just like C<parse_file> except that it reads the Pod -content not from a file, but from a string that you have already -in memory. - -=item C<< $parser->parse_lines( I<...@lines...>, undef ); >> - -This processes the lines in C<@lines> (where each list item must be a -defined value, and must contain exactly one line of content -- so no -items like C<"foo\nbar"> are allowed). The final C<undef> is used to -indicate the end of document being parsed. - -The other C<parser_I<whatever>> methods are meant to be called only once -per C<$parser> object; but C<parse_lines> can be called as many times per -C<$parser> object as you want, as long as the last call (and only -the last call) ends with an C<undef> value. - - -=item C<< $parser->content_seen >> - -This returns true only if there has been any real content seen for this -document. Returns false in cases where the document contains content, -but does not make use of any Pod markup. - -=item C<< I<SomeClass>->filter( I<$filename> ); >> - -=item C<< I<SomeClass>->filter( I<*INPUT_FH> ); >> - -=item C<< I<SomeClass>->filter( I<\$document_content> ); >> - -This is a shortcut method for creating a new parser object, setting the -output handle to STDOUT, and then processing the specified file (or -filehandle, or in-memory document). This is handy for one-liners like -this: - - perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')" - -=back - - - -=head1 SECONDARY METHODS - -Some of these methods might be of interest to general users, as -well as of interest to formatter-writers. - -Note that the general pattern here is that the accessor-methods -read the attribute's value with C<< $value = $parser->I<attribute> >> -and set the attribute's value with -C<< $parser->I<attribute>(I<newvalue>) >>. For each accessor, I typically -only mention one syntax or another, based on which I think you are actually -most likely to use. - - -=over - -=item C<< $parser->no_whining( I<SOMEVALUE> ) >> - -If you set this attribute to a true value, you will suppress the -parser's complaints about irregularities in the Pod coding. By default, -this attribute's value is false, meaning that irregularities will -be reported. - -Note that turning this attribute to true won't suppress one or two kinds -of complaints about rarely occurring unrecoverable errors. - - -=item C<< $parser->no_errata_section( I<SOMEVALUE> ) >> - -If you set this attribute to a true value, you will stop the parser from -generating a "POD ERRORS" section at the end of the document. By -default, this attribute's value is false, meaning that an errata section -will be generated, as necessary. - - -=item C<< $parser->complain_stderr( I<SOMEVALUE> ) >> - -If you set this attribute to a true value, it will send reports of -parsing errors to STDERR. By default, this attribute's value is false, -meaning that no output is sent to STDERR. - -Setting C<complain_stderr> also sets C<no_errata_section>. - - -=item C<< $parser->source_filename >> - -This returns the filename that this parser object was set to read from. - - -=item C<< $parser->doc_has_started >> - -This returns true if C<$parser> has read from a source, and has seen -Pod content in it. - - -=item C<< $parser->source_dead >> - -This returns true if C<$parser> has read from a source, and come to the -end of that source. - -=item C<< $parser->strip_verbatim_indent( I<SOMEVALUE> ) >> - -The perlpod spec for a Verbatim paragraph is "It should be reproduced -exactly...", which means that the whitespace you've used to indent your -verbatim blocks will be preserved in the output. This can be annoying for -outputs such as HTML, where that whitespace will remain in front of every -line. It's an unfortunate case where syntax is turned into semantics. - -If the POD your parsing adheres to a consistent indentation policy, you can -have such indentation stripped from the beginning of every line of your -verbatim blocks. This method tells Pod::Simple what to strip. For two-space -indents, you'd use: - - $parser->strip_verbatim_indent(' '); - -For tab indents, you'd use a tab character: - - $parser->strip_verbatim_indent("\t"); - -If the POD is inconsistent about the indentation of verbatim blocks, but you -have figured out a heuristic to determine how much a particular verbatim block -is indented, you can pass a code reference instead. The code reference will be -executed with one argument, an array reference of all the lines in the -verbatim block, and should return the value to be stripped from each line. For -example, if you decide that you're fine to use the first line of the verbatim -block to set the standard for indentation of the rest of the block, you can -look at the first line and return the appropriate value, like so: - - $new->strip_verbatim_indent(sub { - my $lines = shift; - (my $indent = $lines->[0]) =~ s/\S.*//; - return $indent; - }); - -If you'd rather treat each line individually, you can do that, too, by just -transforming them in-place in the code reference and returning C<undef>. Say -that you don't want I<any> lines indented. You can do something like this: - - $new->strip_verbatim_indent(sub { - my $lines = shift; - sub { s/^\s+// for @{ $lines }, - return undef; - }); - -=back - -=head1 TERTIARY METHODS - -=over - -=item C<< $parser->abandon_output_fh() >>X<abandon_output_fh> - -Cancel output to the file handle. Any POD read by the C<$parser> is not -effected. - -=item C<< $parser->abandon_output_string() >>X<abandon_output_string> - -Cancel output to the output string. Any POD read by the C<$parser> is not -effected. - -=item C<< $parser->accept_code( @codes ) >>X<accept_code> - -Alias for L<< accept_codes >>. - -=item C<< $parser->accept_codes( @codes ) >>X<accept_codes> - -Allows C<$parser> to accept a list of L<perlpod/Formatting Codes>. This can be -used to implement user-defined codes. - -=item C<< $parser->accept_directive_as_data( @directives ) >>X<accept_directive_as_data> - -Allows C<$parser> to accept a list of directives for data paragraphs. A -directive is the label of a L<perlpod/Command Paragraph>. A data paragraph is -one delimited by C<< =begin/=for/=end >> directives. This can be used to -implement user-defined directives. - -=item C<< $parser->accept_directive_as_processed( @directives ) >>X<accept_directive_as_processed> - -Allows C<$parser> to accept a list of directives for processed paragraphs. A -directive is the label of a L<perlpod/Command Paragraph>. A processed -paragraph is also known as L<perlpod/Ordinary Paragraph>. This can be used to -implement user-defined directives. - -=item C<< $parser->accept_directive_as_verbatim( @directives ) >>X<accept_directive_as_verbatim> - -Allows C<$parser> to accept a list of directives for L<perlpod/Verbatim -Paragraph>. A directive is the label of a L<perlpod/Command Paragraph>. This -can be used to implement user-defined directives. - -=item C<< $parser->accept_target( @targets ) >>X<accept_target> - -Alias for L<< accept_targets >>. - -=item C<< $parser->accept_target_as_text( @targets ) >>X<accept_target_as_text> - -Alias for L<< accept_targets_as_text >>. - -=item C<< $parser->accept_targets( @targets ) >>X<accept_targets> - -Accepts targets for C<< =begin/=for/=end >> sections of the POD. - -=item C<< $parser->accept_targets_as_text( @targets ) >>X<accept_targets_as_text> - -Accepts targets for C<< =begin/=for/=end >> sections that should be parsed as -POD. For details, see L<< perlpodspec/About Data Paragraphs >>. - -=item C<< $parser->any_errata_seen() >>X<any_errata_seen> - -Used to check if any errata was seen. - -I<Example:> - - die "too many errors\n" if $parser->any_errata_seen(); - -=item C<< $parser->parse_from_file( $source, $to ) >>X<parse_from_file> - -Parses from C<$source> file to C<$to> file. Similar to L<< -Pod::Parser/parse_from_file >>. - -=item C<< $parser->scream( @error_messages ) >>X<scream> - -Log an error that can't be ignored. - -=item C<< $parser->unaccept_code( @codes ) >>X<unaccept_code> - -Alias for L<< unaccept_codes >>. - -=item C<< $parser->unaccept_codes( @codes ) >>X<unaccept_codes> - -Removes C<< @codes >> as valid codes for the parse. - -=item C<< $parser->unaccept_directive( @directives ) >>X<unaccept_directive> - -Alias for L<< unaccept_directives >>. - -=item C<< $parser->unaccept_directives( @directives ) >>X<unaccept_directives> - -Removes C<< @directives >> as valid directives for the parse. - -=item C<< $parser->unaccept_target( @targets ) >>X<unaccept_target> - -Alias for L<< unaccept_targets >>. - -=item C<< $parser->unaccept_targets( @targets ) >>X<unaccept_targets> - -Removes C<< @targets >> as valid targets for the parse. - -=item C<< $parser->version_report() >>X<version_report> - -Returns a string describing the version. - -=item C<< $parser->whine( @error_messages ) >>X<whine> - -Log an error unless C<< $parser->no_whining( TRUE ); >>. - -=back - -=head1 CAVEATS - -This is just a beta release -- there are a good number of things still -left to do. Notably, support for EBCDIC platforms is still half-done, -an untested. - - -=head1 SEE ALSO - -L<Pod::Simple::Subclassing> - -L<perlpod|perlpod> - -L<perlpodspec|perlpodspec> - -L<Pod::Escapes|Pod::Escapes> - -L<perldoc> - -=head1 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. - -This module is managed in an open GitHub repository, -L<http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or -to clone L<git://github.com/theory/pod-simple.git> and send patches! - -Patches against Pod::Simple are welcome. Please send bug reports to -<bug-pod-simple@rt.cpan.org>. - -=head1 COPYRIGHT AND DISCLAIMERS - -Copyright (c) 2002 Sean M. Burke. - -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 - -Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. -But don't bother him, he's retired. - -Pod::Simple is maintained by: - -=over - -=item * Allison Randal C<allison@perl.org> - -=item * Hans Dieter Pearcey C<hdp@cpan.org> - -=item * David E. Wheeler C<dwheeler@cpan.org> - -=back - -Documentation has been contributed by: - -=over - -=item * Gabor Szabo C<szabgab@gmail.com> - -=item * Shawn H Corey C<SHCOREY at cpan.org> - -=back - -=cut diff --git a/Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod b/Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod deleted file mode 100644 index 792d1be5a24..00000000000 --- a/Master/tlpkg/tlperl/lib/Pod/Simple/Subclassing.pod +++ /dev/null @@ -1,1057 +0,0 @@ - -=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, $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; - -=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" raw="that_url" 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" raw="http://www.perl.com/CPAN/authors/" 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" raw="manpage(section)" 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" raw="crontab(5)" 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" raw="crontab(5)/"ENVIRONMENT"" 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 raw="hell itself!|crontab(5)" 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" raw="podpage" to="podpage" type="pod"> - podpage - </L> - -For example, this Pod source: - - L<Net::Ping> - -produces this event structure: - - <L content-implicit="yes" raw="Net::Ping" 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 raw="Perl Error Messages|perldiag" 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" raw="/"Member Data"" 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 raw="the various attributes|/"Member Data"" 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" 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> - -As another example, this Pod source: - - L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"> - -produces this event structure: - - <L raw="SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"" 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 (for the most part), namely: - - <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod"> - "Member Data" - </L> - -The I<raw> attribute depends on what the raw content of the L<> is, so that is -why the event structure is the same "for the most part". - -If you have not guessed it yet, the I<raw> attribute contains the raw, -original, unescaped content of the L<> formatting code. In addition to the -examples above, take notice of the following event structure produced by -the following L<> formatting code. - - 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> - -Specifically, notice that the formatting codes are present and unescaped -in I<raw>. - -There is a known bug in the I<raw> attribute where any surrounding whitespace -is condensed into a single ' '. For example, given LE<60> linkE<62>, I<raw> -will be " link". - -=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 bulleted 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 fake-closer="1"> - -The attribute I<fake-closer> 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 B<closing> tag). It signifies that the C<=over> -did not have a matching C<=back>, and thus Pod::Simple had to create a fake -closer. - -For example, this Pod source: - - =over - - =item * - - Something - - =back - -Would produce an event structure that does B<not> have the I<fake-closer> -attribute, whereas this Pod source: - - =over - - =item * - - Gasp! An unclosed =over block! - -would. The rest of the over-* examples will not demonstrate this attribute, -but they all can have it. See L<Pod::Checker>'s source for an example of this -attribute being used. - -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 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> and I<fake-closer> attributes are 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 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> and I<fake-closer> attributes are 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. - - =back - -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 over-empty - -B<Note: These events are only triggered if C<parse_empty_lists()> is set to a -true value.> - -These events are somewhat unlike the other over-* structures, as far as what -their contents are. When an "=over ... Z<>=back" block is parsed where there -is no content, it will produce this event structure: - - <over-empty indent="4" start_line="543"> - </over-empty> - -The I<indent> and I<fake-closer> attributes are as with the other over-* events. - -For example, this Pod source: - - =over - - =over - - =back - - =back - -will produce this event structure: - - <over-block indent="4" start_line="1"> - <over-empty indent="4" start_line="3"> - </over-empty> - </over-block> - -Note that the outer C<=over> is a block because it has no C<=item>s but still -has content: the inner C<=over>. The inner C<=over>, in turn, is completely -empty, and is treated as such. - -=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 -capabilities 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 -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 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->pod_handler( I<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. - - -=item C<< $parser->whiteline_handler( I<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 "\t") on them, -not code lines. The same caveats apply. These 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 -suppressible 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 indiscriminately 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). - -=item C<< $parser->parse_empty_lists( I<SOMEVALUE> ) >> - -If this attribute is set to true, the parser will not ignore empty -C<=over>/C<=back> blocks. The type of C<=over> will be I<empty>, documented -above, L<events with an element_name of over-empty>. - -=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<Pod::Simple::HTML> -- a simple HTML formatter for Pod - -L<perlpod|perlpod> - -L<perlpodspec|perlpodspec> - -L<perldoc> - -=head1 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. - -This module is managed in an open GitHub repository, -L<http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or -to clone L<git://github.com/theory/pod-simple.git> and send patches! - -Patches against Pod::Simple are welcome. Please send bug reports to -<bug-pod-simple@rt.cpan.org>. - -=head1 COPYRIGHT AND DISCLAIMERS - -Copyright (c) 2002 Sean M. Burke. - -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 - -Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. -But don't bother him, he's retired. - -Pod::Simple is maintained by: - -=over - -=item * Allison Randal C<allison@perl.org> - -=item * Hans Dieter Pearcey C<hdp@cpan.org> - -=item * David E. Wheeler C<dwheeler@cpan.org> - -=back - -=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 - - |