Add all new utilities in the perlutil man page.

Includes lots of work by Zsban Ambrus.

p4raw-id: //depot/perl@27390

1 files changed, 101 insertions, 8 deletions

diff --git a/pod/perlutil.pod b/pod/perlutil.pod
index 5da4860e3f..19d2decce1 100644
--- a/pod/perlutil.pod
+++ b/pod/perlutil.pod
@@ -11,7 +11,9 @@ 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
+=head1 LIST OF UTILITIES
+
+=head2 Documentation
 
 =over 3
 
@@ -73,7 +75,7 @@ typeset PostScript or text file of the whole lot.
 
 =back
 
-=head2 CONVERTORS
+=head2 Convertors
 
 To help you convert legacy programs to Perl, we've included three
 conversion filters:
@@ -91,7 +93,7 @@ based around this code:
         print $Fld2;
     }
 
-=item L<s2p|s2p>
+=item L<s2p|s2p> and L<psed>
 
 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:
@@ -102,6 +104,9 @@ on C<s/foo/bar> will produce a Perl program based around this:
         print if $printit;
     }
 
+When invoked as F<psed>, it behaves as a F<sed> implementation, written in
+Perl.
+
 =item L<find2perl|find2perl>
 
 Finally, F<find2perl> translates C<find> commands to Perl equivalents which 
@@ -127,14 +132,21 @@ new-style Perl5 modules.
 
 =over 3
 
+=item L<config_data|config_data>
+
+Query or change configuration of Perl modules that use Module::Build-based
+configuration files for features and config data.
+
 =item L<libnetcfg|libnetcfg>
 
 To display and change the libnet configuration run the libnetcfg command.
 
-=item L<config_data|config_data>
+=item L<perlivp>
 
-Query or change configuration of Perl modules that use Module::Build-based
-configuration files for features and config data.
+The F<perlivp> program is set up at Perl source code build time to test
+the Perl version it was built under.  It can be used after running C<make
+install> (or your platform's equivalent procedure) to verify that perl
+and its libraries have been installed correctly.
 
 =back
 
@@ -174,6 +186,23 @@ 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<enc2xs>
+
+F<enc2xs> builds a Perl extension for use by Encode from either
+Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc).
+Besides being used internally during the build process of the Encode
+module, you can use F<enc2xs> to add your own encoding to perl.
+No knowledge of XS is necessary.
+
+=item L<xsubpp>
+
+F<xsubpp> is a compiler to convert Perl XS code into C code.
+It is typically run by the makefiles created by L<ExtUtils::MakeMaker>.
+
+F<xsubpp> will compile XS code into C code by embedding the constructs
+necessary to let C functions manipulate Perl values and creates the glue
+necessary to let Perl access those functions.
+
 =item L<dprofpp|dprofpp>
 
 Perl comes with a profiler, the F<Devel::DProf> module. The
@@ -185,9 +214,71 @@ for more information.
 
 F<perlcc> is the interface to the experimental Perl compiler suite.
 
+=item L<prove>
+
+F<prove> is a command-line interface to the test-running functionality of
+of F<Test::Harness>.  It's an alternative to C<make test>.
+
+=item L<corelist>
+
+A command-line front-end to C<Module::CoreList>, to query what modules
+were shipped with given versions of perl.
+
+=back
+
+=head2 General tools
+
+A few general-purpose tools are shipped with perl, mostly because they
+came along modules included in the perl distribution.
+
+=over 3
+
+=item L<piconv>
+
+B<piconv> is a Perl version of B<iconv>, a character encoding converter
+widely available for various Unixen today.  This script was primarily a
+technology demonstrator for Perl 5.8.0, but you can use piconv in the
+place of iconv for virtually any case.
+
+=item L<ptar>
+
+F<ptar> is a tar-like program, written in pure Perl.
+
+=item L<ptardiff>
+
+F<ptardiff> is a small utility that produces a diff between an extracted
+archive and an unextracted one.
+
+=item L<shasum>
+
+This utility, that comes with the C<Digest::SHA> module, is used to print
+or verify SHA checksums.
+
+=back
+
+=head2 Installation
+
+These utilities help manage extra Perl modules that don't come with the perl
+distribution.
+
+=over 3
+
+=item L<cpan>
+
+F<cpan> is a command-line interface to CPAN.pm.  It allows you to install
+modules or distributions from CPAN, or just get information about them, and
+a lot more.  It is similar to the command line mode of the L<CPAN> module,
+
+    perl -MCPAN -e shell
+
+=item L<instmodsh>
+
+A little interface to ExtUtils::Installed to examine installed modules,
+validate your packlists and even create a tarball from an installed module.
+
 =back
 
-=head2 SEE ALSO
+=head1 SEE ALSO
 
 L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>,
 L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>,
@@ -195,6 +286,8 @@ 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>
+L<Devel::DProf>, L<perlcc|perlcc>, L<enc2xs>, L<xsubpp>, L<cpan>,
+L<instmodsh>, L<piconv>, L<prove>, L<corelist>, L<ptar>, L<ptardiff>,
+L<shasum>
 
 =cut