local-lib5/man/man3/Pod::Text.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::Text 3"
 132 .TH Pod::Text 3 "2009-01-18" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Pod::Text \- Convert POD data to formatted ASCII text
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&    use Pod::Text;
 139 \&    my $parser = Pod::Text\->new (sentence => 0, width => 78);
 140 .Ve
 141 .PP
 142 .Vb 2
 143 \&    # Read POD from STDIN and write to STDOUT.
 144 \&    $parser\->parse_from_filehandle;
 145 .Ve
 146 .PP
 147 .Vb 2
 148 \&    # Read POD from file.pod and write to file.txt.
 149 \&    $parser\->parse_from_file ('file.pod', 'file.txt');
 150 .Ve
 151 .SH "DESCRIPTION"
 152 .IX Header "DESCRIPTION"
 153 Pod::Text is a module that can convert documentation in the \s-1POD\s0 format (the
 154 preferred language for documenting Perl) into formatted \s-1ASCII\s0.  It uses no
 155 special formatting controls or codes whatsoever, and its output is therefore
 156 suitable for nearly any device.
 157 .PP
 158 As a derived class from Pod::Simple, Pod::Text supports the same methods and
 159 interfaces.  See Pod::Simple for all the details; briefly, one creates a
 160 new parser with \f(CW\*(C`Pod::Text\->new()\*(C'\fR and then normally calls \fIparse_file()\fR.
 161 .PP
 162 \&\fInew()\fR can take options, in the form of key/value pairs, that control the
 163 behavior of the parser.  The currently recognized options are:
 164 .IP "alt" 4
 165 .IX Item "alt"
 166 If set to a true value, selects an alternate output format that, among other
 167 things, uses a different heading style and marks \f(CW\*(C`=item\*(C'\fR entries with a
 168 colon in the left margin.  Defaults to false.
 169 .IP "code" 4
 170 .IX Item "code"
 171 If set to a true value, the non-POD parts of the input file will be included
 172 in the output.  Useful for viewing code documented with \s-1POD\s0 blocks with the
 173 \&\s-1POD\s0 rendered and the code left intact.
 174 .IP "indent" 4
 175 .IX Item "indent"
 176 The number of spaces to indent regular text, and the default indentation for
 177 \&\f(CW\*(C`=over\*(C'\fR blocks.  Defaults to 4.
 178 .IP "loose" 4
 179 .IX Item "loose"
 180 If set to a true value, a blank line is printed after a \f(CW\*(C`=head1\*(C'\fR heading.
 181 If set to false (the default), no blank line is printed after \f(CW\*(C`=head1\*(C'\fR,
 182 although one is still printed after \f(CW\*(C`=head2\*(C'\fR.  This is the default because
 183 it's the expected formatting for manual pages; if you're formatting
 184 arbitrary text documents, setting this to true may result in more pleasing
 185 output.
 186 .IP "margin" 4
 187 .IX Item "margin"
 188 The width of the left margin in spaces.  Defaults to 0.  This is the margin
 189 for all text, including headings, not the amount by which regular text is
 190 indented; for the latter, see the \fIindent\fR option.  To set the right
 191 margin, see the \fIwidth\fR option.
 192 .IP "quotes" 4
 193 .IX Item "quotes"
 194 Sets the quote marks used to surround C<> text.  If the value is a
 195 single character, it is used as both the left and right quote; if it is two
 196 characters, the first character is used as the left quote and the second as
 197 the right quoted; and if it is four characters, the first two are used as
 198 the left quote and the second two as the right quote.
 199 .Sp
 200 This may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote
 201 marks are added around C<> text.
 202 .IP "sentence" 4
 203 .IX Item "sentence"
 204 If set to a true value, Pod::Text will assume that each sentence ends in two
 205 spaces, and will try to preserve that spacing.  If set to false, all
 206 consecutive whitespace in non-verbatim paragraphs is compressed into a
 207 single space.  Defaults to true.
 208 .IP "stderr" 4
 209 .IX Item "stderr"
 210 Send error messages about invalid \s-1POD\s0 to standard error instead of
 211 appending a \s-1POD\s0 \s-1ERRORS\s0 section to the generated output.
 212 .IP "utf8" 4
 213 .IX Item "utf8"
 214 By default, Pod::Text uses the same output encoding as the input encoding
 215 of the \s-1POD\s0 source (provided that Perl was built with PerlIO; otherwise, it
 216 doesn't encode its output).  If this option is given, the output encoding
 217 is forced to \s-1UTF\-8\s0.
 218 .Sp
 219 Be aware that, when using this option, the input encoding of your \s-1POD\s0
 220 source must be properly declared unless it is US-ASCII or Latin\-1.  \s-1POD\s0
 221 input without an \f(CW\*(C`=encoding\*(C'\fR command will be assumed to be in Latin\-1,
 222 and if it's actually in \s-1UTF\-8\s0, the output will be double\-encoded.  See
 223 \&\fIperlpod\fR\|(1) for more information on the \f(CW\*(C`=encoding\*(C'\fR command.
 224 .IP "width" 4
 225 .IX Item "width"
 226 The column at which to wrap text on the right-hand side.  Defaults to 76.
 227 .PP
 228 The standard Pod::Simple method \fIparse_file()\fR takes one argument, the file or
 229 file handle to read from, and writes output to standard output unless that
 230 has been changed with the \fIoutput_fh()\fR method.  See Pod::Simple for the
 231 specific details and for other alternative interfaces.
 232 .SH "DIAGNOSTICS"
 233 .IX Header "DIAGNOSTICS"
 234 .IP "Bizarre space in item" 4
 235 .IX Item "Bizarre space in item"
 236 .PD 0
 237 .IP "Item called without tag" 4
 238 .IX Item "Item called without tag"
 239 .PD
 240 (W) Something has gone wrong in internal \f(CW\*(C`=item\*(C'\fR processing.  These
 241 messages indicate a bug in Pod::Text; you should never see them.
 242 .ie n .IP "Can't open %s\fR for reading: \f(CW%s" 4
 243 .el .IP "Can't open \f(CW%s\fR for reading: \f(CW%s\fR" 4
 244 .IX Item "Can't open %s for reading: %s"
 245 (F) Pod::Text was invoked via the compatibility mode \fIpod2text()\fR interface
 246 and the input file it was given could not be opened.
 247 .ie n .IP "Invalid quote specification ""%s""" 4
 248 .el .IP "Invalid quote specification ``%s''" 4
 249 .IX Item "Invalid quote specification %s"
 250 (F) The quote specification given (the quotes option to the constructor) was
 251 invalid.  A quote specification must be one, two, or four characters long.
 252 .SH "BUGS"
 253 .IX Header "BUGS"
 254 Encoding handling assumes that PerlIO is available and does not work
 255 properly if it isn't.  The \f(CW\*(C`utf8\*(C'\fR option is therefore not supported
 256 unless Perl is built with PerlIO support.
 257 .SH "CAVEATS"
 258 .IX Header "CAVEATS"
 259 If Pod::Text is given the \f(CW\*(C`utf8\*(C'\fR option, the encoding of its output file
 260 handle will be forced to \s-1UTF\-8\s0 if possible, overriding any existing
 261 encoding.  This will be done even if the file handle is not created by
 262 Pod::Text and was passed in from outside.  This maintains consistency
 263 regardless of \s-1PERL_UNICODE\s0 and other settings.
 264 .PP
 265 If the \f(CW\*(C`utf8\*(C'\fR option is not given, the encoding of its output file handle
 266 will be forced to the detected encoding of the input \s-1POD\s0, which preserves
 267 whatever the input text is.  This ensures backward compatibility with
 268 earlier, pre-Unicode versions of this module, without large numbers of
 269 Perl warnings.
 270 .PP
 271 This is not ideal, but it seems to be the best compromise.  If it doesn't
 272 work for you, please let me know the details of how it broke.
 273 .SH "NOTES"
 274 .IX Header "NOTES"
 275 This is a replacement for an earlier Pod::Text module written by Tom
 276 Christiansen.  It has a revamped interface, since it now uses Pod::Simple,
 277 but an interface roughly compatible with the old \fIPod::Text::pod2text()\fR
 278 function is still available.  Please change to the new calling convention,
 279 though.
 280 .PP
 281 The original Pod::Text contained code to do formatting via termcap
 282 sequences, although it wasn't turned on by default and it was problematic to
 283 get it to work at all.  This rewrite doesn't even try to do that, but a
 284 subclass of it does.  Look for Pod::Text::Termcap.
 285 .SH "SEE ALSO"
 286 .IX Header "SEE ALSO"
 287 Pod::Simple, Pod::Text::Termcap, \fIperlpod\fR\|(1), \fIpod2text\fR\|(1)
 288 .PP
 289 The current version of this module is always available from its web site at
 290 <http://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
 291 Perl core distribution as of 5.6.0.
 292 .SH "AUTHOR"
 293 .IX Header "AUTHOR"
 294 Russ Allbery <rra@stanford.edu>, based \fIvery\fR heavily on the original
 295 Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion to
 296 Pod::Parser by Brad Appleton <bradapp@enteract.com>.  Sean Burke's initial
 297 conversion of Pod::Man to use Pod::Simple provided much-needed guidance on
 298 how to use Pod::Simple.
 299 .SH "COPYRIGHT AND LICENSE"
 300 .IX Header "COPYRIGHT AND LICENSE"
 301 Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008 Russ Allbery
 302 <rra@stanford.edu>.
 303 .PP
 304 This program is free software; you may redistribute it and/or modify it
 305 under the same terms as Perl itself.