local-lib5/lib/perl5/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 Setting C<complain_stderr> also sets C<no_errata_section>.
 155
 156
 157 =item C<< $parser->source_filename >>
 158
 159 This returns the filename that this parser object was set to read from.
 160
 161
 162 =item C<< $parser->doc_has_started >>
 163
 164 This returns true if C<$parser> has read from a source, and has seen
 165 Pod content in it.
 166
 167
 168 =item C<< $parser->source_dead >>
 169
 170 This returns true if C<$parser> has read from a source, and come to the
 171 end of that source.
 172
 173 =item C<< $parser->strip_verbatim_indent( I<SOMEVALUE> ) >>
 174
 175 The perlpod spec for a Verbatim paragraph is "It should be reproduced
 176 exactly...", which means that the whitespace you've used to indent your
 177 verbatim blocks will be preserved in the output. This can be annoying for
 178 outputs such as HTML, where that whitespace will remain in front of every
 179 line. It's an unfortunate case where syntax is turned into semantics.
 180
 181 If the POD your parsing adheres to a consistent indentation policy, you can
 182 have such indentation stripped from the beginning of every line of your
 183 verbatim blocks. This method tells Pod::Simple what to strip. For two-space
 184 indents, you'd use:
 185
 186   $parser->strip_verbatim_indent('  ');
 187
 188 For tab indents, you'd use a tab character:
 189
 190   $parser->strip_verbatim_indent("\t");
 191
 192 If the POD is inconsistent about the indentation of verbatim blocks, but you
 193 have figured out a heuristic to determine how much a particular verbatim block
 194 is indented, you can pass a code reference instead. The code reference will be
 195 executed with one argument, an array reference of all the lines in the
 196 verbatim block, and should return the value to be stripped from each line. For
 197 example, if you decide that you're fine to use the first line of the verbatim
 198 block to set the standard for indentation of the rest of the block, you can
 199 look at the first line and return the appropriate value, like so:
 200
 201   $new->strip_verbatim_indent(sub {
 202       my $lines = shift;
 203       (my $indent = $lines->[0]) =~ s/\S.*//;
 204       return $indent;
 205   });
 206
 207 If you'd rather treat each line individually, you can do that, too, by just
 208 transforming them in-place in the code reference and returning C<undef>. Say
 209 that you don't want I<any> lines indented. You can do something like this:
 210
 211   $new->strip_verbatim_indent(sub {
 212       my $lines = shift;
 213       sub { s/^\s+// for @{ $lines },
 214       return undef;
 215   });
 216
 217 =back
 218
 219 =head1 CAVEATS
 220
 221 This is just a beta release -- there are a good number of things still
 222 left to do.  Notably, support for EBCDIC platforms is still half-done,
 223 an untested.
 224
 225
 226 =head1 SEE ALSO
 227
 228 L<Pod::Simple::Subclassing>
 229
 230 L<perlpod|perlpod>
 231
 232 L<perlpodspec|perlpodspec>
 233
 234 L<Pod::Escapes|Pod::Escapes>
 235
 236 L<perldoc>
 237
 238
 239 =head1 COPYRIGHT AND DISCLAIMERS
 240
 241 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
 242
 243 This library is free software; you can redistribute it and/or modify it
 244 under the same terms as Perl itself.
 245
 246 This program is distributed in the hope that it will be useful, but
 247 without any warranty; without even the implied warranty of
 248 merchantability or fitness for a particular purpose.
 249
 250 =head1 AUTHOR
 251
 252 Original author: Sean M. Burke C<sburke@cpan.org>
 253
 254 Maintained by:
 255
 256 =over
 257
 258 =item * Allison Randal C<allison@perl.org>
 259
 260 =item * Hans Dieter Pearcey C<hdp@cpan.org>
 261
 262 =back
 263
 264 =cut
 265
 266