local-lib5/man/man3/Pod::Simple.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Pod::Simple 3"
 132 .TH Pod::Simple 3 "2009-10-26" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Pod::Simple \- framework for parsing Pod
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \& TODO
 139 .Ve
 140 .SH "DESCRIPTION"
 141 .IX Header "DESCRIPTION"
 142 Pod::Simple is a Perl library for parsing text in the Pod (\*(L"plain old
 143 documentation\*(R") markup language that is typically used for writing
 144 documentation for Perl and for Perl modules. The Pod format is explained
 145 in the perlpod man page; the most common formatter is called
 146 \&\*(L"perldoc\*(R".
 147 .PP
 148 Pod formatters can use Pod::Simple to parse Pod documents into produce
 149 renderings of them in plain \s-1ASCII\s0, in \s-1HTML\s0, or in any number of other
 150 formats. Typically, such formatters will be subclasses of Pod::Simple,
 151 and so they will inherit its methods, like \f(CW\*(C`parse_file\*(C'\fR.
 152 .PP
 153 If you're reading this document just because you have a Pod-processing
 154 subclass that you want to use, this document (plus the documentation for
 155 the subclass) is probably all you'll need to read.
 156 .PP
 157 If you're reading this document because you want to write a formatter
 158 subclass, continue reading this document, and then read
 159 Pod::Simple::Subclassing, and then possibly even read perlpodspec
 160 (some of which is for parser\-writers, but much of which is notes to
 161 formatter\-writers).
 162 .SH "MAIN METHODS"
 163 .IX Header "MAIN METHODS"
 164 .ie n .IP """$parser = \f(CISomeClass\f(CW\->new();""" 4
 165 .el .IP "\f(CW$parser = \f(CISomeClass\f(CW\->new();\fR" 4
 166 .IX Item "$parser = SomeClass->new();"
 167 This returns a new parser object, where \fI\f(CI\*(C`SomeClass\*(C'\fI\fR is a subclass
 168 of Pod::Simple.
 169 .ie n .IP """$parser\->output_fh( *OUT );""" 4
 170 .el .IP "\f(CW$parser\->output_fh( *OUT );\fR" 4
 171 .IX Item "$parser->output_fh( *OUT );"
 172 This sets the filehandle that \f(CW$parser\fR's output will be written to.
 173 You can pass \f(CW*STDOUT\fR, otherwise you should probably do something
 174 like this:
 175 .Sp
 176 .Vb 3
 177 \&    my $outfile = "output.txt";
 178 \&    open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!";
 179 \&    $parser\->output_fh(*TXTOUT);
 180 .Ve
 181 .Sp
 182 \&...before you call one of the \f(CW\*(C`$parser\->parse_\f(CIwhatever\f(CW\*(C'\fR methods.
 183 .ie n .IP """$parser\->output_string( \e$somestring );""" 4
 184 .el .IP "\f(CW$parser\->output_string( \e$somestring );\fR" 4
 185 .IX Item "$parser->output_string( $somestring );"
 186 This sets the string that \f(CW$parser\fR's output will be sent to,
 187 instead of any filehandle.
 188 .ie n .IP """$parser\->parse_file( \f(CI$some_filename\f(CW );""" 4
 189 .el .IP "\f(CW$parser\->parse_file( \f(CI$some_filename\f(CW );\fR" 4
 190 .IX Item "$parser->parse_file( $some_filename );"
 191 .PD 0
 192 .ie n .IP """$parser\->parse_file( *INPUT_FH );""" 4
 193 .el .IP "\f(CW$parser\->parse_file( *INPUT_FH );\fR" 4
 194 .IX Item "$parser->parse_file( *INPUT_FH );"
 195 .PD
 196 This reads the Pod content of the file (or filehandle) that you specify,
 197 and processes it with that \f(CW$parser\fR object, according to however
 198 \&\f(CW$parser\fR's class works, and according to whatever parser options you
 199 have set up for this \f(CW$parser\fR object.
 200 .ie n .IP """$parser\->parse_string_document( \f(CI$all_content\f(CW );""" 4
 201 .el .IP "\f(CW$parser\->parse_string_document( \f(CI$all_content\f(CW );\fR" 4
 202 .IX Item "$parser->parse_string_document( $all_content );"
 203 This works just like \f(CW\*(C`parse_file\*(C'\fR except that it reads the Pod
 204 content not from a file, but from a string that you have already
 205 in memory.
 206 .ie n .IP """$parser\->parse_lines( \f(CI...@lines...\f(CW, undef );""" 4
 207 .el .IP "\f(CW$parser\->parse_lines( \f(CI...@lines...\f(CW, undef );\fR" 4
 208 .IX Item "$parser->parse_lines( ...@lines..., undef );"
 209 This processes the lines in \f(CW@lines\fR (where each list item must be a
 210 defined value, and must contain exactly one line of content \*(-- so no
 211 items like \f(CW"foo\enbar"\fR are allowed).  The final \f(CW\*(C`undef\*(C'\fR is used to
 212 indicate the end of document being parsed.
 213 .Sp
 214 The other \f(CW\*(C`parser_\f(CIwhatever\f(CW\*(C'\fR methods are meant to be called only once
 215 per \f(CW$parser\fR object; but \f(CW\*(C`parse_lines\*(C'\fR can be called as many times per
 216 \&\f(CW$parser\fR object as you want, as long as the last call (and only
 217 the last call) ends with an \f(CW\*(C`undef\*(C'\fR value.
 218 .ie n .IP """$parser\->content_seen""" 4
 219 .el .IP "\f(CW$parser\->content_seen\fR" 4
 220 .IX Item "$parser->content_seen"
 221 This returns true only if there has been any real content seen
 222 for this document.
 223 .ie n .IP """\f(CISomeClass\f(CW\->filter( \f(CI$filename\f(CW );""" 4
 224 .el .IP "\f(CW\f(CISomeClass\f(CW\->filter( \f(CI$filename\f(CW );\fR" 4
 225 .IX Item "SomeClass->filter( $filename );"
 226 .PD 0
 227 .ie n .IP """\f(CISomeClass\f(CW\->filter( \f(CI*INPUT_FH\f(CW );""" 4
 228 .el .IP "\f(CW\f(CISomeClass\f(CW\->filter( \f(CI*INPUT_FH\f(CW );\fR" 4
 229 .IX Item "SomeClass->filter( *INPUT_FH );"
 230 .ie n .IP """\f(CISomeClass\f(CW\->filter( \f(CI\e$document_content\f(CW );""" 4
 231 .el .IP "\f(CW\f(CISomeClass\f(CW\->filter( \f(CI\e$document_content\f(CW );\fR" 4
 232 .IX Item "SomeClass->filter( $document_content );"
 233 .PD
 234 This is a shortcut method for creating a new parser object, setting the
 235 output handle to \s-1STDOUT\s0, and then processing the specified file (or
 236 filehandle, or in-memory document). This is handy for one-liners like
 237 this:
 238 .Sp
 239 .Vb 1
 240 \&  perl \-MPod::Simple::Text \-e "Pod::Simple::Text\->filter('thingy.pod')"
 241 .Ve
 242 .SH "SECONDARY METHODS"
 243 .IX Header "SECONDARY METHODS"
 244 Some of these methods might be of interest to general users, as
 245 well as of interest to formatter\-writers.
 246 .PP
 247 Note that the general pattern here is that the accessor-methods
 248 read the attribute's value with \f(CW\*(C`$value = $parser\->\f(CIattribute\f(CW\*(C'\fR
 249 and set the attribute's value with
 250 \&\f(CW\*(C`$parser\->\f(CIattribute\f(CW(\f(CInewvalue\f(CW)\*(C'\fR.  For each accessor, I typically
 251 only mention one syntax or another, based on which I think you are actually
 252 most likely to use.
 253 .ie n .IP """$parser\->no_whining( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
 254 .el .IP "\f(CW$parser\->no_whining( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
 255 .IX Item "$parser->no_whining( SOMEVALUE )"
 256 If you set this attribute to a true value, you will suppress the
 257 parser's complaints about irregularities in the Pod coding. By default,
 258 this attribute's value is false, meaning that irregularities will
 259 be reported.
 260 .Sp
 261 Note that turning this attribute to true won't suppress one or two kinds
 262 of complaints about rarely occurring unrecoverable errors.
 263 .ie n .IP """$parser\->no_errata_section( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
 264 .el .IP "\f(CW$parser\->no_errata_section( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
 265 .IX Item "$parser->no_errata_section( SOMEVALUE )"
 266 If you set this attribute to a true value, you will stop the parser from
 267 generating a \*(L"\s-1POD\s0 \s-1ERRORS\s0\*(R" section at the end of the document. By
 268 default, this attribute's value is false, meaning that an errata section
 269 will be generated, as necessary.
 270 .ie n .IP """$parser\->complain_stderr( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
 271 .el .IP "\f(CW$parser\->complain_stderr( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
 272 .IX Item "$parser->complain_stderr( SOMEVALUE )"
 273 If you set this attribute to a true value, it will send reports of
 274 parsing errors to \s-1STDERR\s0. By default, this attribute's value is false,
 275 meaning that no output is sent to \s-1STDERR\s0.
 276 .Sp
 277 Setting \f(CW\*(C`complain_stderr\*(C'\fR also sets \f(CW\*(C`no_errata_section\*(C'\fR.
 278 .ie n .IP """$parser\->source_filename""" 4
 279 .el .IP "\f(CW$parser\->source_filename\fR" 4
 280 .IX Item "$parser->source_filename"
 281 This returns the filename that this parser object was set to read from.
 282 .ie n .IP """$parser\->doc_has_started""" 4
 283 .el .IP "\f(CW$parser\->doc_has_started\fR" 4
 284 .IX Item "$parser->doc_has_started"
 285 This returns true if \f(CW$parser\fR has read from a source, and has seen
 286 Pod content in it.
 287 .ie n .IP """$parser\->source_dead""" 4
 288 .el .IP "\f(CW$parser\->source_dead\fR" 4
 289 .IX Item "$parser->source_dead"
 290 This returns true if \f(CW$parser\fR has read from a source, and come to the
 291 end of that source.
 292 .ie n .IP """$parser\->strip_verbatim_indent( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
 293 .el .IP "\f(CW$parser\->strip_verbatim_indent( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
 294 .IX Item "$parser->strip_verbatim_indent( SOMEVALUE )"
 295 The perlpod spec for a Verbatim paragraph is \*(L"It should be reproduced
 296 exactly...\*(R", which means that the whitespace you've used to indent your
 297 verbatim blocks will be preserved in the output. This can be annoying for
 298 outputs such as \s-1HTML\s0, where that whitespace will remain in front of every
 299 line. It's an unfortunate case where syntax is turned into semantics.
 300 .Sp
 301 If the \s-1POD\s0 your parsing adheres to a consistent indentation policy, you can
 302 have such indentation stripped from the beginning of every line of your
 303 verbatim blocks. This method tells Pod::Simple what to strip. For two-space
 304 indents, you'd use:
 305 .Sp
 306 .Vb 1
 307 \&  $parser\->strip_verbatim_indent('  ');
 308 .Ve
 309 .Sp
 310 For tab indents, you'd use a tab character:
 311 .Sp
 312 .Vb 1
 313 \&  $parser\->strip_verbatim_indent("\et");
 314 .Ve
 315 .Sp
 316 If the \s-1POD\s0 is inconsistent about the indentation of verbatim blocks, but you
 317 have figured out a heuristic to determine how much a particular verbatim block
 318 is indented, you can pass a code reference instead. The code reference will be
 319 executed with one argument, an array reference of all the lines in the
 320 verbatim block, and should return the value to be stripped from each line. For
 321 example, if you decide that you're fine to use the first line of the verbatim
 322 block to set the standard for indentation of the rest of the block, you can
 323 look at the first line and return the appropriate value, like so:
 324 .Sp
 325 .Vb 5
 326 \&  $new\->strip_verbatim_indent(sub {
 327 \&      my $lines = shift;
 328 \&      (my $indent = $lines\->[0]) =~ s/\eS.*//;
 329 \&      return $indent;
 330 \&  });
 331 .Ve
 332 .Sp
 333 If you'd rather treat each line individually, you can do that, too, by just
 334 transforming them in-place in the code reference and returning \f(CW\*(C`undef\*(C'\fR. Say
 335 that you don't want \fIany\fR lines indented. You can do something like this:
 336 .Sp
 337 .Vb 5
 338 \&  $new\->strip_verbatim_indent(sub {
 339 \&      my $lines = shift;
 340 \&      sub { s/^\es+// for @{ $lines },
 341 \&      return undef;
 342 \&  });
 343 .Ve
 344 .SH "CAVEATS"
 345 .IX Header "CAVEATS"
 346 This is just a beta release \*(-- there are a good number of things still
 347 left to do.  Notably, support for \s-1EBCDIC\s0 platforms is still half\-done,
 348 an untested.
 349 .SH "SEE ALSO"
 350 .IX Header "SEE ALSO"
 351 Pod::Simple::Subclassing
 352 .PP
 353 perlpod
 354 .PP
 355 perlpodspec
 356 .PP
 357 Pod::Escapes
 358 .PP
 359 perldoc
 360 .SH "COPYRIGHT AND DISCLAIMERS"
 361 .IX Header "COPYRIGHT AND DISCLAIMERS"
 362 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
 363 .PP
 364 This library is free software; you can redistribute it and/or modify it
 365 under the same terms as Perl itself.
 366 .PP
 367 This program is distributed in the hope that it will be useful, but
 368 without any warranty; without even the implied warranty of
 369 merchantability or fitness for a particular purpose.
 370 .SH "AUTHOR"
 371 .IX Header "AUTHOR"
 372 Original author: Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR
 373 .PP
 374 Maintained by:
 375 .ie n .IP "* Allison Randal ""allison@perl.org""" 4
 376 .el .IP "* Allison Randal \f(CWallison@perl.org\fR" 4
 377 .IX Item "Allison Randal allison@perl.org"
 378 .PD 0
 379 .ie n .IP "* Hans Dieter Pearcey ""hdp@cpan.org""" 4
 380 .el .IP "* Hans Dieter Pearcey \f(CWhdp@cpan.org\fR" 4
 381 .IX Item "Hans Dieter Pearcey hdp@cpan.org"