Move perldoc.pod to the dist it belongs to

1 files changed, 269 insertions, 0 deletions

diff --git a/dist/Pod-Perldoc/lib/perldoc.pod b/dist/Pod-Perldoc/lib/perldoc.pod
new file mode 100644
index 0000000000..d70625c451
--- /dev/null
+++ b/dist/Pod-Perldoc/lib/perldoc.pod
@@ -0,0 +1,269 @@
+
+=head1 NAME
+
+perldoc - Look up Perl documentation in Pod format.
+
+=head1 SYNOPSIS
+
+B<perldoc> [B<-h>] [B<-D>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]
+[B<-i>] [B<-V>] [B<-T>] [B<-r>]
+[B<-dI<destination_file>>]
+[B<-oI<formatname>>]
+[B<-MI<FormatterClassName>>]
+[B<-wI<formatteroption:value>>]
+[B<-n>I<nroff-replacement>]
+[B<-X>]
+[B<-L> I<language_code>]
+PageName|ModuleName|ProgramName
+
+B<perldoc> B<-f> BuiltinFunction
+
+B<perldoc> B<-L> it B<-f> BuiltinFunction
+
+B<perldoc> B<-q> FAQ Keyword
+
+B<perldoc> B<-L> fr B<-q> FAQ Keyword
+
+B<perldoc> B<-v> PerlVariable
+
+See below for more description of the switches.
+
+=head1 DESCRIPTION
+
+I<perldoc> looks up a piece of documentation in .pod format that is embedded
+in the perl installation tree or in a perl script, and displays it via
+C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
+C<col -x> will be used.) 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<-F>
+
+Consider arguments as file names; no search in directories will be performed.
+
+=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<-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 right 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>
+
+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 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 nroff
+
+=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.
+
+
+=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<-oman>, C<-otext>, C<-otk>, 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::ToMan>
+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.)
+
+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.)
+
+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<-v> 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: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributors are:
+Sean M. Burke <sburke@cpan.org>,
+Kenneth Albanowski <kjahds@kjahds.com>,
+Andy Dougherty  <doughera@lafcol.lafayette.edu>,
+and many others.
+
+=cut