X-Git-Url: https://vcs.maemo.org/git/?a=blobdiff_plain;f=dev%2Fi386%2Flibpod-simple-perl%2Flibpod-simple-perl-3.07%2Flib%2FPod%2FSimple.pod;fp=dev%2Fi386%2Flibpod-simple-perl%2Flibpod-simple-perl-3.07%2Flib%2FPod%2FSimple.pod;h=a58217336a1e3aa846a3d48bf52bb0c9d5fdb060;hb=8977e561d8a9eae6959218b0306c9df2056a38a9;hp=0000000000000000000000000000000000000000;hpb=df794b845212301ea0d267c919232538bfef356a;p=dh-make-perl diff --git a/dev/i386/libpod-simple-perl/libpod-simple-perl-3.07/lib/Pod/Simple.pod b/dev/i386/libpod-simple-perl/libpod-simple-perl-3.07/lib/Pod/Simple.pod new file mode 100644 index 0000000..a582173 --- /dev/null +++ b/dev/i386/libpod-simple-perl/libpod-simple-perl-3.07/lib/Pod/Simple.pod @@ -0,0 +1,226 @@ + +=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 +in the L man page; the most common formatter is called +"perldoc". + +Pod formatters can use Pod::Simple to parse Pod documents into produce +renderings of them in plain ASCII, in HTML, or in any number of other +formats. Typically, such formatters will be subclasses of Pod::Simple, +and so they will inherit its methods, like C. + +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'll need to read. + +If you're reading this document because you want to write a formatter +subclass, continue reading this document, and then read +L, and then possibly even read L +(some of which is for parser-writers, but much of which is notes to +formatter-writers). + + +=head1 MAIN METHODS + + + +=over + +=item C<< $parser = I->new(); >> + +This returns a new parser object, where I> 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 >> 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 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 is used to +indicate the end of document being parsed. + +The other C> methods are meant to be called only once +per C<$parser> object; but C 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 value. + + +=item C<< $parser->content_seen >> + +This returns true only if there has been any real content seen +for this document. + + +=item C<< I->filter( I<$filename> ); >> + +=item C<< I->filter( I<*INPUT_FH> ); >> + +=item C<< I->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 >> +and set the attribute's value with +C<< $parser->I(I) >>. 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 ) >> + +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 ) >> + +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 ) >> + +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. + +Note that errors can be noted in an errata section, or sent to STDERR, +or both, or neither. So don't think that turning on C +will turn off C or vice versa -- these are +independent attributes. + + +=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. + +=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 + +L + +L + +L + +L + + +=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 + +Original author: Sean M. Burke C + +Maintained by: + +=over + +=item * Allison Randal C + +=item * Hans Dieter Pearcey C + +=back + +=cut + +