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