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<-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