RE: How to load a "loadable object" that has a non-default file extension ?
[perl.git] / 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