local-lib5/man/man1/pod2text.1p

   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 "POD2TEXT 1"
 132 .TH POD2TEXT 1 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 pod2text \- Convert POD data to formatted ASCII text
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 pod2text [\fB\-aclostu\fR] [\fB\-\-code\fR] [\fB\-i\fR \fIindent\fR] [\fB\-q\fR\ \fIquotes\fR]
 138     [\fB\-\-stderr\fR] [\fB\-w\fR\ \fIwidth\fR] [\fIinput\fR [\fIoutput\fR ...]]
 139 .PP
 140 pod2text \fB\-h\fR
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 \&\fBpod2text\fR is a front-end for Pod::Text and its subclasses.  It uses them
 144 to generate formatted \s-1ASCII\s0 text from \s-1POD\s0 source.  It can optionally use
 145 either termcap sequences or \s-1ANSI\s0 color escape sequences to format the text.
 146 .PP
 147 \&\fIinput\fR is the file to read for \s-1POD\s0 source (the \s-1POD\s0 can be embedded in
 148 code).  If \fIinput\fR isn't given, it defaults to \f(CW\*(C`STDIN\*(C'\fR.  \fIoutput\fR, if
 149 given, is the file to which to write the formatted output.  If \fIoutput\fR
 150 isn't given, the formatted output is written to \f(CW\*(C`STDOUT\*(C'\fR.  Several \s-1POD\s0
 151 files can be processed in the same \fBpod2text\fR invocation (saving module
 152 load and compile times) by providing multiple pairs of \fIinput\fR and
 153 \&\fIoutput\fR files on the command line.
 154 .SH "OPTIONS"
 155 .IX Header "OPTIONS"
 156 .IP "\fB\-a\fR, \fB\-\-alt\fR" 4
 157 .IX Item "-a, --alt"
 158 Use an alternate output format that, among other things, uses a different
 159 heading style and marks \f(CW\*(C`=item\*(C'\fR entries with a colon in the left margin.
 160 .IP "\fB\-\-code\fR" 4
 161 .IX Item "--code"
 162 Include any non-POD text from the input file in the output as well.  Useful
 163 for viewing code documented with \s-1POD\s0 blocks with the \s-1POD\s0 rendered and the
 164 code left intact.
 165 .IP "\fB\-c\fR, \fB\-\-color\fR" 4
 166 .IX Item "-c, --color"
 167 Format the output with \s-1ANSI\s0 color escape sequences.  Using this option
 168 requires that Term::ANSIColor be installed on your system.
 169 .IP "\fB\-i\fR \fIindent\fR, \fB\-\-indent=\fR\fIindent\fR" 4
 170 .IX Item "-i indent, --indent=indent"
 171 Set the number of spaces to indent regular text, and the default indentation
 172 for \f(CW\*(C`=over\*(C'\fR blocks.  Defaults to 4 spaces if this option isn't given.
 173 .IP "\fB\-h\fR, \fB\-\-help\fR" 4
 174 .IX Item "-h, --help"
 175 Print out usage information and exit.
 176 .IP "\fB\-l\fR, \fB\-\-loose\fR" 4
 177 .IX Item "-l, --loose"
 178 Print a blank line after a \f(CW\*(C`=head1\*(C'\fR heading.  Normally, no blank line is
 179 printed after \f(CW\*(C`=head1\*(C'\fR, although one is still printed after \f(CW\*(C`=head2\*(C'\fR,
 180 because this is the expected formatting for manual pages; if you're
 181 formatting arbitrary text documents, using this option is recommended.
 182 .IP "\fB\-m\fR \fIwidth\fR, \fB\-\-left\-margin\fR=\fIwidth\fR, \fB\-\-margin\fR=\fIwidth\fR" 4
 183 .IX Item "-m width, --left-margin=width, --margin=width"
 184 The width of the left margin in spaces.  Defaults to 0.  This is the margin
 185 for all text, including headings, not the amount by which regular text is
 186 indented; for the latter, see \fB\-i\fR option.
 187 .IP "\fB\-o\fR, \fB\-\-overstrike\fR" 4
 188 .IX Item "-o, --overstrike"
 189 Format the output with overstrike printing.  Bold text is rendered as
 190 character, backspace, character.  Italics and file names are rendered as
 191 underscore, backspace, character.  Many pagers, such as \fBless\fR, know how
 192 to convert this to bold or underlined text.
 193 .IP "\fB\-q\fR \fIquotes\fR, \fB\-\-quotes\fR=\fIquotes\fR" 4
 194 .IX Item "-q quotes, --quotes=quotes"
 195 Sets the quote marks used to surround C<> text to \fIquotes\fR.  If
 196 \&\fIquotes\fR is a single character, it is used as both the left and right
 197 quote; if \fIquotes\fR is two characters, the first character is used as the
 198 left quote and the second as the right quoted; and if \fIquotes\fR is four
 199 characters, the first two are used as the left quote and the second two as
 200 the right quote.
 201 .Sp
 202 \&\fIquotes\fR may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no
 203 quote marks are added around C<> text.
 204 .IP "\fB\-s\fR, \fB\-\-sentence\fR" 4
 205 .IX Item "-s, --sentence"
 206 Assume each sentence ends with two spaces and try to preserve that spacing.
 207 Without this option, all consecutive whitespace in non-verbatim paragraphs
 208 is compressed into a single space.
 209 .IP "\fB\-\-stderr\fR" 4
 210 .IX Item "--stderr"
 211 By default, \fBpod2text\fR puts any errors detected in the \s-1POD\s0 input in a \s-1POD\s0
 212 \&\s-1ERRORS\s0 section in the output manual page.  If \fB\-\-stderr\fR is given, errors
 213 are sent to standard error instead and the \s-1POD\s0 \s-1ERRORS\s0 section is
 214 suppressed.
 215 .IP "\fB\-t\fR, \fB\-\-termcap\fR" 4
 216 .IX Item "-t, --termcap"
 217 Try to determine the width of the screen and the bold and underline
 218 sequences for the terminal from termcap, and use that information in
 219 formatting the output.  Output will be wrapped at two columns less than the
 220 width of your terminal device.  Using this option requires that your system
 221 have a termcap file somewhere where Term::Cap can find it and requires that
 222 your system support termios.  With this option, the output of \fBpod2text\fR
 223 will contain terminal control sequences for your current terminal type.
 224 .IP "\fB\-u\fR, \fB\-\-utf8\fR" 4
 225 .IX Item "-u, --utf8"
 226 By default, \fBpod2text\fR tries to use the same output encoding as its input
 227 encoding (to be backward-compatible with older versions).  This option
 228 says to instead force the output encoding to \s-1UTF\-8\s0.
 229 .Sp
 230 Be aware that, when using this option, the input encoding of your \s-1POD\s0
 231 source must be properly declared unless it is US-ASCII or Latin\-1.  \s-1POD\s0
 232 input without an \f(CW\*(C`=encoding\*(C'\fR command will be assumed to be in Latin\-1,
 233 and if it's actually in \s-1UTF\-8\s0, the output will be double\-encoded.  See
 234 \&\fIperlpod\fR\|(1) for more information on the \f(CW\*(C`=encoding\*(C'\fR command.
 235 .IP "\fB\-w\fR, \fB\-\-width=\fR\fIwidth\fR, \fB\-\fR\fIwidth\fR" 4
 236 .IX Item "-w, --width=width, -width"
 237 The column at which to wrap text on the right-hand side.  Defaults to 76,
 238 unless \fB\-t\fR is given, in which case it's two columns less than the width of
 239 your terminal device.
 240 .SH "DIAGNOSTICS"
 241 .IX Header "DIAGNOSTICS"
 242 If \fBpod2text\fR fails with errors, see Pod::Text and Pod::Simple for
 243 information about what those errors might mean.  Internally, it can also
 244 produce the following diagnostics:
 245 .IP "\-c (\-\-color) requires Term::ANSIColor be installed" 4
 246 .IX Item "-c (--color) requires Term::ANSIColor be installed"
 247 (F) \fB\-c\fR or \fB\-\-color\fR were given, but Term::ANSIColor could not be
 248 loaded.
 249 .ie n .IP "Unknown option: %s" 4
 250 .el .IP "Unknown option: \f(CW%s\fR" 4
 251 .IX Item "Unknown option: %s"
 252 (F) An unknown command line option was given.
 253 .PP
 254 In addition, other Getopt::Long error messages may result from invalid
 255 command-line options.
 256 .SH "ENVIRONMENT"
 257 .IX Header "ENVIRONMENT"
 258 .IP "\s-1COLUMNS\s0" 4
 259 .IX Item "COLUMNS"
 260 If \fB\-t\fR is given, \fBpod2text\fR will take the current width of your screen
 261 from this environment variable, if available.  It overrides terminal width
 262 information in \s-1TERMCAP\s0.
 263 .IP "\s-1TERMCAP\s0" 4
 264 .IX Item "TERMCAP"
 265 If \fB\-t\fR is given, \fBpod2text\fR will use the contents of this environment
 266 variable if available to determine the correct formatting sequences for your
 267 current terminal device.
 268 .SH "SEE ALSO"
 269 .IX Header "SEE ALSO"
 270 Pod::Text, Pod::Text::Color, Pod::Text::Overstrike,
 271 Pod::Text::Termcap, Pod::Simple, \fIperlpod\fR\|(1)
 272 .PP
 273 The current version of this script is always available from its web site at
 274 <http://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
 275 Perl core distribution as of 5.6.0.
 276 .SH "AUTHOR"
 277 .IX Header "AUTHOR"
 278 Russ Allbery <rra@stanford.edu>.
 279 .SH "COPYRIGHT AND LICENSE"
 280 .IX Header "COPYRIGHT AND LICENSE"
 281 Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery
 282 <rra@stanford.edu>.
 283 .PP
 284 This program is free software; you may redistribute it and/or modify it
 285 under the same terms as Perl itself.