integrate cfgperl changes#6231..6240 into mainline

p4raw-link: @6240 on //depot/cfgperl: 514e70b26394e6b272960ab8b9b8b7dbb1e2c068
p4raw-link: @6231 on //depot/cfgperl: 7906debc4b99f108310cdade6e486754c15481e7

p4raw-id: //depot/perl@6355
p4raw-branched: from //depot/cfgperl@6353 'branch in' pod/perlutil.pod
p4raw-integrated: from //depot/cfgperl@6353 'copy in' pod/roffitall
	(@5753..) op.h (@5833..) README.cygwin (@6096..)
	lib/ExtUtils/MM_VMS.pm (@6140..) lib/File/Find.pm (@6156..)
	Configure config_h.SH hints/solaris_2.sh (@6217..) Todo-5.6
	(@6232..) keywords.h lib/warnings.pm opcode.h opnames.h pp.sym
	regnodes.h warnings.h (@6236..) 'ignore' ext/B/B/Asmdata.pm
	ext/ByteLoader/byterun.c ext/ByteLoader/byterun.h (@6236..)
p4raw-integrated: from //depot/cfgperl@6240 'copy in' utils/h2xs.PL
	(@6192..)
p4raw-integrated: from //depot/cfgperl@6238 'merge in' vms/vms.c
	(@6198..)
p4raw-integrated: from //depot/cfgperl@6237 'copy in' utf8.c (@6221..)
	pod/perlapi.pod pod/perlintern.pod pp_proto.h (@6236..)
	'ignore' embedvar.h perlapi.h (@6236..) 'merge in' embed.pl
	(@6225..) embed.h objXSUB.h perlapi.c proto.h (@6236..)
p4raw-integrated: from //depot/cfgperl@6232 'copy in' pod/Makefile
	pod/perltoc.pod (@6161..) MANIFEST (@6227..)

1 files changed, 185 insertions, 0 deletions

diff --git a/pod/perlutil.pod b/pod/perlutil.pod
new file mode 100644
index 0000000000..1b2c178b1f
--- /dev/null
+++ b/pod/perlutil.pod
@@ -0,0 +1,185 @@
+=head1 NAME
+
+perlutil - utilities packaged with the Perl distribution
+
+=head1 DESCRIPTION
+
+Along with the Perl interpreter itself, the Perl distribution installs a
+range of utilities on your system. There are also several utilities
+which are used by the Perl distribution itself as part of the install
+process. This document exists to list all of these utilities, explain
+what they are for and provide pointers to each module's documentation,
+if appropriate.
+
+=head2 DOCUMENTATION
+
+=over 3
+
+=item L<perldoc|perldoc>
+
+The main interface to Perl's documentation is C<perldoc>, although
+if you're reading this, it's more than likely that you've already found
+it. F<perldoc> will extract and format the documentation from any file
+in the current directory, any Perl module installed on the system, or
+any of the standard documentation pages, such as this one. Use 
+C<perldoc E<lt>nameE<gt>> to get information on any of the utilities
+described in this document.
+
+=item L<pod2man|pod2man> and L<pod2text|pod2text>
+
+If it's run from a terminal, F<perldoc> will usually call F<pod2man> to
+translate POD (Plain Old Documentation - see L<perlpod> for an
+explanation) into a man page, and then run F<man> to display it; if
+F<man> isn't available, F<pod2text> will be used instead and the output
+piped through your favourite pager.
+
+=item L<pod2html|pod2html> and L<pod2latex|pod2latex>
+
+As well as these two, there are two other convertors: F<pod2html> will
+produce HTML pages from POD, and F<pod2latex>, which produces LaTeX
+files.
+
+=item L<pod2usage|pod2usage>
+
+If you just want to know how to use the utilities described here,
+F<pod2usage> will just extract the "USAGE" section; some of
+the utilities will automatically call F<pod2usage> on themselves when
+you call them with C<-help>.
+
+=item L<podselect|podselect>
+
+F<pod2usage> is a special case of F<podselect>, a utility to extract
+named sections from documents written in POD. For instance, while
+utilities have "USAGE" sections, Perl modules usually have "SYNOPSIS"
+sections: C<podselect -s "SYNOPSIS" ...> will extract this section for
+a given file.
+
+=item L<podchecker|podchecker>
+
+If you're writing your own documentation in POD, the F<podchecker>
+utility will look for errors in your markup.
+
+=item L<splain|splain>
+
+F<splain> is an interface to L<perldiag> - paste in your error message
+to it, and it'll explain it for you.
+
+=item L<roffitall|roffitall>
+
+The C<roffitall> utility is not installed on your system but lives in
+the F<pod/> directory of your Perl source kit; it converts all the
+documentation from the distribution to F<*roff> format, and produces a
+typeset PostScript or text file of the whole lot.
+
+=back
+
+=head2 CONVERTORS
+
+To help you convert legacy programs to Perl, we've included three
+conversion filters:
+
+=over 3
+
+=item L<a2p|a2p>
+
+F<a2p> converts F<awk> scripts to Perl programs; for example, C<a2p -F:>
+on the simple F<awk> script C<{print $2}> will produce a Perl program
+based around this code:
+
+    while (<>) {
+        ($Fld1,$Fld2) = split(/[:\n]/, $_, 9999);
+        print $Fld2;
+    }
+
+=item L<s2p|s2p>
+
+Similarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run
+on C<s/foo/bar> will produce a Perl program based around this:
+
+    while (<>) {
+        chop;
+        s/foo/bar/g;
+        print if $printit;
+    }
+
+=item L<find2perl|find2perl>
+
+Finally, F<find2perl> translates C<find> commands to Perl equivalents which 
+use the L<File::Find|File::Find> module. As an example, 
+C<find2perl . -user root -perm 4000 -print> produces the following callback
+subroutine for C<File::Find>:
+
+    sub wanted {
+        my ($dev,$ino,$mode,$nlink,$uid,$gid);
+        (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) &&
+        $uid == $uid{'root'}) &&
+        (($mode & 0777) == 04000);
+        print("$name\n");
+    }
+
+=back
+
+As well as these filters for converting other languages, the
+L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries to 
+new-style Perl5 modules.
+
+=head2 Development
+
+There are a set of utilities which help you in developing Perl programs, 
+and in particular, extending Perl with C.
+
+=over 3
+
+=item L<perlbug|perlbug>
+
+F<perlbug> is the recommended way to report bugs in the perl interpreter
+itself or any of the standard library modules back to the developers;
+please read through the documentation for F<perlbug> thoroughly before
+using it to submit a bug report.
+
+=item L<h2ph|h2ph>
+
+Back before Perl had the XS system for connecting with C libraries,
+programmers used to get library constants by reading through the C
+header files. You may still see C<require 'syscall.ph'> or similar
+around - the F<.ph> file should be created by running F<h2ph> on the
+corresponding F<.h> file. See the F<h2ph> documentation for more on how
+to convert a whole bunch of header files at ones.
+
+=item L<c2ph|c2ph> and L<pstruct|pstruct>
+
+F<c2ph> and F<pstruct>, which are actually the same program but behave
+differently depending on how they are called, provide another way of
+getting at C with Perl - they'll convert C structures and union declarations
+to Perl code. This is deprecated in favour of F<h2xs> these days.
+
+=item L<h2xs|h2xs>
+
+F<h2xs> converts C header files into XS modules, and will try and write
+as much glue between C libraries and Perl modules as it can. It's also
+very useful for creating skeletons of pure Perl modules.
+
+=item L<dprofpp|dprofpp>
+
+Perl comes with a profiler, the F<Devel::Dprof> module. The
+F<dprofpp> utility analyzes the output of this profiler and tells you
+which subroutines are taking up the most run time. See L<Devel::Dprof>
+for more information.
+
+=item L<perlcc|perlcc>
+
+F<perlcc> is the interface to the experimental Perl compiler suite.
+
+=back
+
+=head2 SEE ALSO
+
+L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>,
+L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>,
+L<podchecker|podchecker>, L<splain|splain>, L<perldiag>,
+L<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>,
+L<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>,
+L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<dprofpp|dprofpp>,
+L<Devel::Dprof>, L<perlcc|perlcc>
+
+=cut