|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=head1 NAME
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc - Look up Perl documentation in Pod format.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=head1 SYNOPSIS
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc [-h] [-D] [-t] [-u] [-m] [-l] [-U] [-F]
|
|
Packit |
a38e86 |
[-i] [-V] [-T] [-r]
|
|
Packit |
a38e86 |
[-d destination_file]
|
|
Packit |
a38e86 |
[-o formatname]
|
|
Packit |
a38e86 |
[-M FormatterClassName]
|
|
Packit |
a38e86 |
[-w formatteroption:value]
|
|
Packit |
a38e86 |
[-n nroff-replacement]
|
|
Packit |
a38e86 |
[-X]
|
|
Packit |
a38e86 |
[-L language_code]
|
|
Packit |
a38e86 |
PageName|ModuleName|ProgramName|URL
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Examples:
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -f BuiltinFunction
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -L it -f BuiltinFunction
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -q FAQ Keyword
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -L fr -q FAQ Keyword
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -v PerlVariable
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -a PerlAPI
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
See below for more description of the switches.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=head1 DESCRIPTION
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
B<perldoc> looks up documentation in .pod format that is embedded in the perl
|
|
Packit |
a38e86 |
installation tree or in a perl script, and displays it using a variety of
|
|
Packit |
a38e86 |
formatters. This is primarily used for the documentation for the perl library
|
|
Packit |
a38e86 |
modules.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Your system may also have man pages installed for those modules, in
|
|
Packit |
a38e86 |
which case you can probably just use the man(1) command.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
If you are looking for a table of contents to the Perl library modules
|
|
Packit |
a38e86 |
documentation, see the L<perltoc> page.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=head1 OPTIONS
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=over 5
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-h>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Prints out a brief B<h>elp message.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-D>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
B<D>escribes search for the item in B<d>etail.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-t>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Display docs using plain B<t>ext converter, instead of nroff. This may be faster,
|
|
Packit |
a38e86 |
but it probably won't look as nice.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-u>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Skip the real Pod formatting, and just show the raw Pod source (B<U>nformatted)
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-m> I<module>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Display the entire module: both code and unformatted pod documentation.
|
|
Packit |
a38e86 |
This may be useful if the docs don't explain a function in the detail
|
|
Packit |
a38e86 |
you need, and you'd like to inspect the code directly; perldoc will find
|
|
Packit |
a38e86 |
the file for you and simply hand it off for display.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-l>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Display onB<l>y the file name of the module found.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-U>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
When running as the superuser, don't attempt drop privileges for security.
|
|
Packit |
a38e86 |
This option is implied with B<-F>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
B<NOTE>: Please see the heading SECURITY below for more information.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-F>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Consider arguments as file names; no search in directories will be performed.
|
|
Packit |
a38e86 |
Implies B<-U> if run as the superuser.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-f> I<perlfunc>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
The B<-f> option followed by the name of a perl built-in function will
|
|
Packit |
a38e86 |
extract the documentation of this function from L<perlfunc>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Example:
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -f sprintf
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-q> I<perlfaq-search-regexp>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
The B<-q> option takes a regular expression as an argument. It will search
|
|
Packit |
a38e86 |
the B<q>uestion headings in perlfaq[1-9] and print the entries matching
|
|
Packit |
a38e86 |
the regular expression.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Example:
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -q shuffle
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-a> I<perlapifunc>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
The B<-a> option followed by the name of a perl api function will
|
|
Packit |
a38e86 |
extract the documentation of this function from L<perlapi>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Example:
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -a newHV
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-v> I<perlvar>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
The B<-v> option followed by the name of a Perl predefined variable will
|
|
Packit |
a38e86 |
extract the documentation of this variable from L<perlvar>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Examples:
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
perldoc -v '$"'
|
|
Packit |
a38e86 |
perldoc -v @+
|
|
Packit |
a38e86 |
perldoc -v DATA
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-T>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
This specifies that the output is not to be sent to a pager, but is to
|
|
Packit |
a38e86 |
be sent directly to STDOUT.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-d> I<destination-filename>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
This specifies that the output is to be sent neither to a pager nor
|
|
Packit |
a38e86 |
to STDOUT, but is to be saved to the specified filename. Example:
|
|
Packit |
a38e86 |
C<perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-o> I<output-formatname>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
This specifies that you want Perldoc to try using a Pod-formatting
|
|
Packit |
a38e86 |
class for the output format that you specify. For example:
|
|
Packit |
a38e86 |
C<-oman>. This is actually just a wrapper around the C<-M> switch;
|
|
Packit |
a38e86 |
using C<-oI<formatname>> just looks for a loadable class by adding
|
|
Packit |
a38e86 |
that format name (with different capitalizations) to the end of
|
|
Packit |
a38e86 |
different classname prefixes.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
For example, C<-oLaTeX> currently tries all of the following classes:
|
|
Packit |
a38e86 |
Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex
|
|
Packit |
a38e86 |
Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex
|
|
Packit |
a38e86 |
Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex
|
|
Packit |
a38e86 |
Pod::LATEX.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-M> I<module-name>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
This specifies the module that you want to try using for formatting the
|
|
Packit |
a38e86 |
pod. The class must at least provide a C<parse_from_file> method.
|
|
Packit |
a38e86 |
For example: C<perldoc -MPod::Perldoc::ToChecker>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
You can specify several classes to try by joining them with commas
|
|
Packit |
a38e86 |
or semicolons, as in C<-MTk::SuperPod;Tk::Pod>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-w> I<option:value> or B<-w> I<option>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
This specifies an option to call the formatter B<w>ith. For example,
|
|
Packit |
a38e86 |
C<-w textsize:15> will call
|
|
Packit |
a38e86 |
C<< $formatter->textsize(15) >> on the formatter object before it is
|
|
Packit |
a38e86 |
used to format the object. For this to be valid, the formatter class
|
|
Packit |
a38e86 |
must provide such a method, and the value you pass should be valid.
|
|
Packit |
a38e86 |
(So if C<textsize> expects an integer, and you do C<-w textsize:big>,
|
|
Packit |
a38e86 |
expect trouble.)
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
You can use C<-w optionname> (without a value) as shorthand for
|
|
Packit |
a38e86 |
C<-w optionname:I<TRUE>>. This is presumably useful in cases of on/off
|
|
Packit |
a38e86 |
features like: C<-w page_numbering>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
You can use an "=" instead of the ":", as in: C<-w textsize=15>. This
|
|
Packit |
a38e86 |
might be more (or less) convenient, depending on what shell you use.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-X>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Use an index if it is present. The B<-X> option looks for an entry
|
|
Packit |
a38e86 |
whose basename matches the name given on the command line in the file
|
|
Packit |
a38e86 |
C<$Config{archlib}/pod.idx>. The F<pod.idx> file should contain fully
|
|
Packit |
a38e86 |
qualified filenames, one per line.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-L> I<language_code>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
This allows one to specify the I<language code> for the desired language
|
|
Packit |
a38e86 |
translation. If the C<POD2::E<lt>language_codeE<gt>> package isn't
|
|
Packit |
a38e86 |
installed in your system, the switch is ignored.
|
|
Packit |
a38e86 |
All available translation packages are to be found under the C<POD2::>
|
|
Packit |
a38e86 |
namespace. See L<POD2::IT> (or L<POD2::FR>) to see how to create new
|
|
Packit |
a38e86 |
localized C<POD2::*> documentation packages and integrate them into
|
|
Packit |
a38e86 |
L<Pod::Perldoc>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<PageName|ModuleName|ProgramName|URL>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
The item you want to look up. Nested modules (such as C<File::Basename>)
|
|
Packit |
a38e86 |
are specified either as C<File::Basename> or C<< File/Basename >>. You may also
|
|
Packit |
a38e86 |
give a descriptive name of a page, such as C<perlfunc>. For URLs, HTTP and
|
|
Packit |
a38e86 |
HTTPS are the only kind currently supported.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
For simple names like 'foo', when the normal search fails to find
|
|
Packit |
a38e86 |
a matching page, a search with the "perl" prefix is tried as well.
|
|
Packit |
a38e86 |
So "perldoc intro" is enough to find/render "perlintro.pod".
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-n> I<some-formatter>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Specify replacement for groff
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-r>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Recursive search.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-i>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Ignore case.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=item B<-V>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Displays the version of perldoc you're running.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=back
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=head1 SECURITY
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Because B<perldoc> does not run properly tainted, and is known to
|
|
Packit |
a38e86 |
have security issues, when run as the superuser it will attempt to
|
|
Packit |
a38e86 |
drop privileges by setting the effective and real IDs to nobody's
|
|
Packit |
a38e86 |
or nouser's account, or -2 if unavailable. If it cannot relinquish
|
|
Packit |
a38e86 |
its privileges, it will not run.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
See the C<-U> option if you do not want this behavior but B<beware>
|
|
Packit |
a38e86 |
that there are significant security risks if you choose to use C<-U>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Since 3.26, using C<-F> as the superuser also implies C<-U> as opening
|
|
Packit |
a38e86 |
most files and traversing directories requires privileges that are
|
|
Packit |
a38e86 |
above the nobody/nogroup level.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=head1 ENVIRONMENT
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Any switches in the C<PERLDOC> environment variable will be used before the
|
|
Packit |
a38e86 |
command line arguments.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Useful values for C<PERLDOC> include C<-oterm>, C<-otext>, C<-ortf>,
|
|
Packit |
a38e86 |
C<-oxml>, and so on, depending on what modules you have on hand; or
|
|
Packit |
a38e86 |
the formatter class may be specified exactly with C<-MPod::Perldoc::ToTerm>
|
|
Packit |
a38e86 |
or the like.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
C<perldoc> also searches directories
|
|
Packit |
a38e86 |
specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
|
|
Packit |
a38e86 |
defined) and C<PATH> environment variables.
|
|
Packit |
a38e86 |
(The latter is so that embedded pods for executables, such as
|
|
Packit |
a38e86 |
C<perldoc> itself, are available.)
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
In directories where either C<Makefile.PL> or C<Build.PL> exist, C<perldoc>
|
|
Packit |
a38e86 |
will add C<.> and C<lib> first to its search path, and as long as you're not
|
|
Packit |
a38e86 |
the superuser will add C<blib> too. This is really helpful if you're working
|
|
Packit |
a38e86 |
inside of a build directory and want to read through the docs even if you
|
|
Packit |
a38e86 |
have a version of a module previously installed.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
C<perldoc> will use, in order of preference, the pager defined in
|
|
Packit |
a38e86 |
C<PERLDOC_PAGER>, C<MANPAGER>, or C<PAGER> before trying to find a pager
|
|
Packit |
a38e86 |
on its own. (C<MANPAGER> is not used if C<perldoc> was told to display
|
|
Packit |
a38e86 |
plain text or unformatted pod.)
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
When using perldoc in it's C<-m> mode (display module source code),
|
|
Packit |
a38e86 |
C<perldoc> will attempt to use the pager set in C<PERLDOC_SRC_PAGER>.
|
|
Packit |
a38e86 |
A useful setting for this command is your favorite editor as in
|
|
Packit |
a38e86 |
C</usr/bin/nano>. (Don't judge me.)
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
One useful value for C<PERLDOC_PAGER> is C<less -+C -E>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Having PERLDOCDEBUG set to a positive integer will make perldoc emit
|
|
Packit |
a38e86 |
even more descriptive output than the C<-D> switch does; the higher the
|
|
Packit |
a38e86 |
number, the more it emits.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=head1 CHANGES
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Up to 3.14_05, the switch B<-v> was used to produce verbose
|
|
Packit |
a38e86 |
messages of B<perldoc> operation, which is now enabled by B<-D>.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=head1 SEE ALSO
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
L<perlpod>, L<Pod::Perldoc>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=head1 AUTHOR
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Current maintainer: Mark Allen C<< <mallen@cpan.org> >>
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
Past contributors are:
|
|
Packit |
a38e86 |
brian d foy C<< <bdfoy@cpan.org> >>
|
|
Packit |
a38e86 |
Adriano R. Ferreira C<< <ferreira@cpan.org> >>,
|
|
Packit |
a38e86 |
Sean M. Burke C<< <sburke@cpan.org> >>,
|
|
Packit |
a38e86 |
Kenneth Albanowski C<< <kjahds@kjahds.com> >>,
|
|
Packit |
a38e86 |
Andy Dougherty C<< <doughera@lafcol.lafayette.edu> >>,
|
|
Packit |
a38e86 |
and many others.
|
|
Packit |
a38e86 |
|
|
Packit |
a38e86 |
=cut
|