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