[Summary view] [Print] [Text view]

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