summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Pod/Simple.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Pod/Simple.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Pod/Simple.pod395
1 files changed, 0 insertions, 395 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