Initial Commit

database/perl/lib/pods/perldoc.pod

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