4 perldoc - Look up Perl documentation in Pod format.
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>>]
12 [B<-MI<FormatterClassName>>]
13 [B<-wI<formatteroption:value>>]
14 [B<-n>I<nroff-replacement>]
16 [B<-L> I<language_code>]
17 PageName|ModuleName|ProgramName
19 B<perldoc> B<-f> BuiltinFunction
21 B<perldoc> B<-L> it B<-f> BuiltinFunction
23 B<perldoc> B<-q> FAQ Keyword
25 B<perldoc> B<-L> fr B<-q> FAQ Keyword
27 See below for more description of the switches.
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.
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.
40 If you are looking for a table of contents to the Perl library modules
41 documentation, see the L<perltoc> page.
49 Prints out a brief B<h>elp message.
53 Describes search for the item in detail (B<v>erbosely).
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.
62 Skip the real Pod formatting, and just show the raw Pod source (B<U>nformatted)
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.
73 Display onB<l>y the file name of the module found.
77 Consider arguments as file names; no search in directories will be performed.
79 =item B<-f> I<perlfunc>
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>.
88 =item B<-q> I<perlfaq-search-regexp>
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>
96 This specifies that the output is not to be sent to a pager, but is to
97 be sent right to STDOUT.
99 =item B<-d> I<destination-filename>
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>
105 =item B<-o> I<output-formatname>
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.
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
120 =item B<-M> I<module-name>
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>.
126 You can specify several classes to try by joining them with commas
127 or semicolons, as in C<-MTk::SuperPod;Tk::Pod>.
129 =item B<-w> I<option:value> or B<-w> I<option>
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>,
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>.
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.
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.
153 =item B<-L> I<language_code>
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
163 =item B<PageName|ModuleName|ProgramName>
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>.
169 =item B<-n> I<some-formatter>
171 Specify replacement for nroff
183 Displays the version of perldoc you're running.
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.
200 Any switches in the C<PERLDOC> environment variable will be used before the
201 command line arguments.
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>
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.)
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.)
219 One useful value for C<PERLDOC_PAGER> is C<less -+C -E>.
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.
227 Current maintainer: Sean M. Burke, <sburke@cpan.org>
229 Past contributors are:
230 Kenneth Albanowski <kjahds@kjahds.com>,
231 Andy Dougherty <doughera@lafcol.lafayette.edu>,