pod/perldoc.pod

   1
   2 =head1 NAME
   3
   4 perldoc - Look up Perl documentation in Pod format.
   5
   6 =head1 SYNOPSIS
   7
   8 B<perldoc> [B<-h>] [B<-D>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]
   9 [B<-i>] [B<-V>] [B<-T>] [B<-r>]
  10 [B<-dI<destination_file>>]
  11 [B<-oI<formatname>>]
  12 [B<-MI<FormatterClassName>>]
  13 [B<-wI<formatteroption:value>>]
  14 [B<-n>I<nroff-replacement>]
  15 [B<-X>]
  16 [B<-L> I<language_code>]
  17 PageName|ModuleName|ProgramName
  18
  19 B<perldoc> B<-f> BuiltinFunction
  20
  21 B<perldoc> B<-L> it B<-f> BuiltinFunction
  22
  23 B<perldoc> B<-q> FAQ Keyword
  24
  25 B<perldoc> B<-L> fr B<-q> FAQ Keyword
  26
  27 B<perldoc> B<-v> PerlVariable
  28
  29 See below for more description of the switches.
  30
  31 =head1 DESCRIPTION
  32
  33 I<perldoc> looks up a piece of documentation in .pod format that is embedded
  34 in the perl installation tree or in a perl script, and displays it via
  35 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
  36 C<col -x> will be used.) This is primarily used for the documentation for
  37 the perl library modules.
  38
  39 Your system may also have man pages installed for those modules, in
  40 which case you can probably just use the man(1) command.
  41
  42 If you are looking for a table of contents to the Perl library modules
  43 documentation, see the L<perltoc> page.
  44
  45 =head1 OPTIONS
  46
  47 =over 5
  48
  49 =item B<-h>
  50
  51 Prints out a brief B<h>elp message.
  52
  53 =item B<-D>
  54
  55 B<D>escribes search for the item in B<d>etail.
  56
  57 =item B<-t>
  58
  59 Display docs using plain B<t>ext converter, instead of nroff. This may be faster,
  60 but it probably won't look as nice.
  61
  62 =item B<-u>
  63
  64 Skip the real Pod formatting, and just show the raw Pod source (B<U>nformatted)
  65
  66 =item B<-m> I<module>
  67
  68 Display the entire module: both code and unformatted pod documentation.
  69 This may be useful if the docs don't explain a function in the detail
  70 you need, and you'd like to inspect the code directly; perldoc will find
  71 the file for you and simply hand it off for display.
  72
  73 =item B<-l>
  74
  75 Display onB<l>y the file name of the module found.
  76
  77 =item B<-F>
  78
  79 Consider arguments as file names; no search in directories will be performed.
  80
  81 =item B<-f> I<perlfunc>
  82
  83 The B<-f> option followed by the name of a perl built in function will
  84 extract the documentation of this function from L<perlfunc>.
  85
  86 Example:
  87
  88       perldoc -f sprintf
  89
  90
  91 =item B<-q> I<perlfaq-search-regexp>
  92
  93 The B<-q> option takes a regular expression as an argument.  It will search
  94 the B<q>uestion headings in perlfaq[1-9] and print the entries matching
  95 the regular expression.
  96
  97 Example:
  98
  99      perldoc -q shuffle
 100
 101
 102 =item B<-v> I<perlvar>
 103
 104 The B<-v> option followed by the name of a Perl predefined variable will
 105 extract the documentation of this variable from L<perlvar>.
 106
 107 Examples:
 108
 109      perldoc -v '$"'
 110      perldoc -v @+
 111      perldoc -v DATA
 112
 113
 114 =item B<-T>
 115
 116 This specifies that the output is not to be sent to a pager, but is to
 117 be sent right to STDOUT.
 118
 119 =item B<-d> I<destination-filename>
 120
 121 This specifies that the output is to be sent neither to a pager nor
 122 to STDOUT, but is to be saved to the specified filename.  Example:
 123 C<perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap>
 124
 125 =item B<-o> I<output-formatname>
 126
 127 This specifies that you want Perldoc to try using a Pod-formatting
 128 class for the output format that you specify.  For example:
 129 C<-oman>.  This is actually just a wrapper around the C<-M> switch;
 130 using C<-oI<formatname>> just looks for a loadable class by adding
 131 that format name (with different capitalizations) to the end of
 132 different classname prefixes.
 133
 134 For example, C<-oLaTeX> currently tries all of the following classes:
 135 Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex
 136 Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex
 137 Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex
 138 Pod::LATEX.
 139
 140 =item B<-M> I<module-name>
 141
 142 This specifies the module that you want to try using for formatting the
 143 pod.  The class must at least provide a C<parse_from_file> method.
 144 For example: C<perldoc -MPod::Perldoc::ToChecker>.
 145
 146 You can specify several classes to try by joining them with commas
 147 or semicolons, as in C<-MTk::SuperPod;Tk::Pod>.
 148
 149 =item B<-w> I<option:value> or B<-w> I<option>
 150
 151 This specifies an option to call the formatter B<w>ith.  For example,
 152 C<-w textsize:15> will call
 153 C<< $formatter->textsize(15) >> on the formatter object before it is
 154 used to format the object.  For this to be valid, the formatter class
 155 must provide such a method, and the value you pass should be valid.
 156 (So if C<textsize> expects an integer, and you do C<-w textsize:big>,
 157 expect trouble.)
 158
 159 You can use C<-w optionname> (without a value) as shorthand for
 160 C<-w optionname:I<TRUE>>.  This is presumably useful in cases of on/off
 161 features like: C<-w page_numbering>.
 162
 163 You can use a "=" instead of the ":", as in: C<-w textsize=15>.  This
 164 might be more (or less) convenient, depending on what shell you use.
 165
 166 =item B<-X>
 167
 168 Use an index if it is present -- the B<-X> option looks for an entry
 169 whose basename matches the name given on the command line in the file
 170 C<$Config{archlib}/pod.idx>. The F<pod.idx> file should contain fully
 171 qualified filenames, one per line.
 172
 173 =item B<-L> I<language_code>
 174
 175 This allows to specify the I<language code> for desired language translation.
 176 If C<POD2::E<lt>language_codeE<gt>> package doesn't exist (or isn't installed
 177 in your system), the switch will be ignored.
 178 All available translation packages should be found under the C<POD2::>
 179 namespace. See L<POD2::IT> (or L<POD2::FR>) in order to see how to create and
 180 integrate new localized C<POD2::*> pod documentation packages in
 181 L<Pod::Perldoc>.
 182
 183 =item B<PageName|ModuleName|ProgramName>
 184
 185 The item you want to look up.  Nested modules (such as C<File::Basename>)
 186 are specified either as C<File::Basename> or C<File/Basename>.  You may also
 187 give a descriptive name of a page, such as C<perlfunc>.
 188
 189 For simple names like 'foo', when the normal search fails to find
 190 a matching page, a search with the "perl" prefix is tried as well.
 191 So "perldoc intro" is enough to find/render "perlintro.pod".
 192
 193 =item B<-n> I<some-formatter>
 194
 195 Specify replacement for nroff
 196
 197 =item B<-r>
 198
 199 Recursive search.
 200
 201 =item B<-i>
 202
 203 Ignore case.
 204
 205 =item B<-V>
 206
 207 Displays the version of perldoc you're running.
 208
 209 =back
 210
 211
 212
 213 =head1 SECURITY
 214
 215 Because B<perldoc> does not run properly tainted, and is known to
 216 have security issues, when run as the superuser it will attempt to
 217 drop privileges by setting the effective and real IDs to nobody's
 218 or nouser's account, or -2 if unavailable.  If it cannot relinquish
 219 its privileges, it will not run.
 220
 221
 222 =head1 ENVIRONMENT
 223
 224 Any switches in the C<PERLDOC> environment variable will be used before the
 225 command line arguments.
 226
 227 Useful values for C<PERLDOC> include C<-oman>, C<-otext>, C<-otk>, C<-ortf>,
 228 C<-oxml>, and so on, depending on what modules you have on hand; or
 229 exactly specify the formatter class with C<-MPod::Perldoc::ToMan>
 230 or the like.
 231
 232 C<perldoc> also searches directories
 233 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
 234 defined) and C<PATH> environment variables.
 235 (The latter is so that embedded pods for executables, such as
 236 C<perldoc> itself, are available.)
 237
 238 C<perldoc> will use, in order of preference, the pager defined in
 239 C<PERLDOC_PAGER>, C<MANPAGER>, or C<PAGER> before trying to find a pager
 240 on its own. (C<MANPAGER> is not used if C<perldoc> was told to display
 241 plain text or unformatted pod.)
 242
 243 One useful value for C<PERLDOC_PAGER> is C<less -+C -E>.
 244
 245 Having PERLDOCDEBUG set to a positive integer will make perldoc emit
 246 even more descriptive output than the C<-v> switch does -- the higher the
 247 number, the more it emits.
 248
 249
 250 =head1 CHANGES
 251
 252 Up to 3.14_05, the switch B<-v> was used to produce verbose
 253 messages of B<perldoc> operation, which is now enabled by B<-D>.
 254
 255 =head1 SEE ALSO
 256
 257 L<perlpod>, L<Pod::Perldoc>
 258
 259 =head1 AUTHOR
 260
 261 Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
 262
 263 Past contributors are:
 264 Sean M. Burke <sburke@cpan.org>,
 265 Kenneth Albanowski <kjahds@kjahds.com>,
 266 Andy Dougherty  <doughera@lafcol.lafayette.edu>,
 267 and many others.
 268
 269 =cut
 270