lib/Pod/Simple.pod

   1
   2 =head1 NAME
   3
   4 Pod::Simple - framework for parsing Pod
   5
   6 =head1 SYNOPSIS
   7
   8  TODO
   9
  10 =head1 DESCRIPTION
  11
  12 Pod::Simple is a Perl library for parsing text in the Pod ("plain old
  13 documentation") markup language that is typically used for writing
  14 documentation for Perl and for Perl modules. The Pod format is explained
  15 in the L<perlpod|perlpod> man page; the most common formatter is called
  16 "perldoc".
  17
  18 Pod formatters can use Pod::Simple to parse Pod documents into produce
  19 renderings of them in plain ASCII, in HTML, or in any number of other
  20 formats. Typically, such formatters will be subclasses of Pod::Simple,
  21 and so they will inherit its methods, like C<parse_file>.
  22
  23 If you're reading this document just because you have a Pod-processing
  24 subclass that you want to use, this document (plus the documentation for
  25 the subclass) is probably all you'll need to read.
  26
  27 If you're reading this document because you want to write a formatter
  28 subclass, continue reading this document, and then read
  29 L<Pod::Simple::Subclassing>, and then possibly even read L<perlpodspec>
  30 (some of which is for parser-writers, but much of which is notes to
  31 formatter-writers).
  32
  33
  34 =head1 MAIN METHODS
  35
  36
  37
  38 =over
  39
  40 =item C<< $parser = I<SomeClass>->new(); >>
  41
  42 This returns a new parser object, where I<C<SomeClass>> is a subclass
  43 of Pod::Simple.
  44
  45 =item C<< $parser->output_fh( *OUT ); >>
  46
  47 This sets the filehandle that C<$parser>'s output will be written to.
  48 You can pass C<*STDOUT>, otherwise you should probably do something
  49 like this:
  50
  51     my $outfile = "output.txt";
  52     open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!";
  53     $parser->output_fh(*TXTOUT);
  54
  55 ...before you call one of the C<< $parser->parse_I<whatever> >> methods.
  56
  57 =item C<< $parser->output_string( \$somestring ); >>
  58
  59 This sets the string that C<$parser>'s output will be sent to,
  60 instead of any filehandle.
  61
  62
  63 =item C<< $parser->parse_file( I<$some_filename> ); >>
  64
  65 =item C<< $parser->parse_file( *INPUT_FH ); >>
  66
  67 This reads the Pod content of the file (or filehandle) that you specify,
  68 and processes it with that C<$parser> object, according to however
  69 C<$parser>'s class works, and according to whatever parser options you
  70 have set up for this C<$parser> object.
  71
  72 =item C<< $parser->parse_string_document( I<$all_content> ); >>
  73
  74 This works just like C<parse_file> except that it reads the Pod
  75 content not from a file, but from a string that you have already
  76 in memory.
  77
  78 =item C<< $parser->parse_lines( I<...@lines...>, undef ); >>
  79
  80 This processes the lines in C<@lines> (where each list item must be a
  81 defined value, and must contain exactly one line of content -- so no
  82 items like C<"foo\nbar"> are allowed).  The final C<undef> is used to
  83 indicate the end of document being parsed.
  84
  85 The other C<parser_I<whatever>> methods are meant to be called only once
  86 per C<$parser> object; but C<parse_lines> can be called as many times per
  87 C<$parser> object as you want, as long as the last call (and only
  88 the last call) ends with an C<undef> value.
  89
  90
  91 =item C<< $parser->content_seen >>
  92
  93 This returns true only if there has been any real content seen
  94 for this document.
  95
  96
  97 =item C<< I<SomeClass>->filter( I<$filename> ); >>
  98
  99 =item C<< I<SomeClass>->filter( I<*INPUT_FH> ); >>
 100
 101 =item C<< I<SomeClass>->filter( I<\$document_content> ); >>
 102
 103 This is a shortcut method for creating a new parser object, setting the
 104 output handle to STDOUT, and then processing the specified file (or
 105 filehandle, or in-memory document). This is handy for one-liners like
 106 this:
 107
 108   perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')"
 109
 110 =back
 111
 112
 113
 114 =head1 SECONDARY METHODS
 115
 116 Some of these methods might be of interest to general users, as
 117 well as of interest to formatter-writers.
 118
 119 Note that the general pattern here is that the accessor-methods
 120 read the attribute's value with C<< $value = $parser->I<attribute> >>
 121 and set the attribute's value with
 122 C<< $parser->I<attribute>(I<newvalue>) >>.  For each accessor, I typically
 123 only mention one syntax or another, based on which I think you are actually
 124 most likely to use.
 125
 126
 127 =over
 128
 129 =item C<< $parser->no_whining( I<SOMEVALUE> ) >>
 130
 131 If you set this attribute to a true value, you will suppress the
 132 parser's complaints about irregularities in the Pod coding. By default,
 133 this attribute's value is false, meaning that irregularities will
 134 be reported.
 135
 136 Note that turning this attribute to true won't suppress one or two kinds
 137 of complaints about rarely occurring unrecoverable errors.
 138
 139
 140 =item C<< $parser->no_errata_section( I<SOMEVALUE> ) >>
 141
 142 If you set this attribute to a true value, you will stop the parser from
 143 generating a "POD ERRORS" section at the end of the document. By
 144 default, this attribute's value is false, meaning that an errata section
 145 will be generated, as necessary.
 146
 147
 148 =item C<< $parser->complain_stderr( I<SOMEVALUE> ) >>
 149
 150 If you set this attribute to a true value, it will send reports of
 151 parsing errors to STDERR. By default, this attribute's value is false,
 152 meaning that no output is sent to STDERR.
 153
 154 Note that errors can be noted in an errata section, or sent to STDERR,
 155 or both, or neither. So don't think that turning on C<complain_stderr>
 156 will turn off C<no_errata_section> or vice versa -- these are
 157 independent attributes.
 158
 159
 160 =item C<< $parser->source_filename >>
 161
 162 This returns the filename that this parser object was set to read from.
 163
 164
 165 =item C<< $parser->doc_has_started >>
 166
 167 This returns true if C<$parser> has read from a source, and has seen
 168 Pod content in it.
 169
 170
 171 =item C<< $parser->source_dead >>
 172
 173 This returns true if C<$parser> has read from a source, and come to the
 174 end of that source.
 175
 176 =back
 177
 178
 179 =head1 CAVEATS
 180
 181 This is just a beta release -- there are a good number of things still
 182 left to do.  Notably, support for EBCDIC platforms is still half-done,
 183 an untested.
 184
 185
 186 =head1 SEE ALSO
 187
 188 L<Pod::Simple::Subclassing>
 189
 190 L<perlpod|perlpod>
 191
 192 L<perlpodspec|perlpodspec>
 193
 194 L<Pod::Escapes|Pod::Escapes>
 195
 196 L<perldoc>
 197
 198
 199 =head1 COPYRIGHT AND DISCLAIMERS
 200
 201 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
 202
 203 This library is free software; you can redistribute it and/or modify it
 204 under the same terms as Perl itself.
 205
 206 This program is distributed in the hope that it will be useful, but
 207 without any warranty; without even the implied warranty of
 208 merchantability or fitness for a particular purpose.
 209
 210 =head1 AUTHOR
 211
 212 Original author: Sean M. Burke C<sburke@cpan.org>
 213
 214 Maintained by:
 215
 216 =over
 217
 218 =item * Allison Randal C<allison@perl.org>
 219
 220 =item * Hans Dieter Pearcey C<hdp@cpan.org>
 221
 222 =back
 223
 224 =cut
 225
 226