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