patch: perlutil.pod missing utilities

From ambrus@math.bme.hu

Created by ambrus@math.bme.hu

This is a documentation bug for the perlutil pod.

This pod claims to document all utilities that come with the perl distribution. Contrary to this\, some utilities are missing from it\, most importantly "cpan" and "prove".

I've edited the pod to include all utilities that got installed for me\, but the edit is not very high quality. I don't even know some of these utilities\, so I've just copied a paragraph from the pod of the respective utilities in most cases. I'm also in trouble with categorizing them\, and I'm not even sure that all utilities belong here and that I've not missed anything.

So\, the diff for perlutil.pod I include should be taken as a starting point\, and you should review and possibly rewrite all of my edits.

For reference\, here's the list of utilities I've added: psed\, perlivp\, pl2pm\, enc2xs\, xsubpp\, prove\, cpan\, instmodsh\, piconv.

Thanks\,

ambrus

-------------------- diff begins here --------------------

Inline Patch

```diff --- pod/perlutil.pod 2001-12-29 17:10:17.000000000 +0100 +++ pod/perlutil.pod 2006-02-25 16:34:51.000000000 +0100 @@ -10,9 +10,11 @@ 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 =item L @@ -72,9 +74,9 @@ 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: @@ -90,9 +92,9 @@ ($Fld1,$Fld2) = split(/[:\n]/, $_, 9999); print $Fld2; } -=item L +=item L and L Similarly, F converts F scripts to Perl programs. F run on C will produce a Perl program based around this: @@ -130,8 +132,15 @@ =item L To display and change the libnet configuration run the libnetcfg command. +=item L + +The B 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 (or your platform's equivalent procedure) to verify that B +and its libraries have been installed correctly. + =back =head2 Development @@ -146,8 +155,16 @@ itself or any of the standard library modules back to the developers; please read through the documentation for F thoroughly before using it to submit a bug report. +=item L + +F is a tool to aid in the conversion of Perl4-style .pl +library files to Perl5-style library modules. Usually, your old .pl +file will still work fine and you should only use this tool if you +plan to update your library to use some of the newer Perl 5 features, +such as AutoLoading. + =item L Back before Perl had the XS system for connecting with C libraries, programmers used to get library constants by reading through the C @@ -168,8 +185,25 @@ F 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 + +F 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 to add your own encoding to perl. +No knowledge of XS is necessary. + +=item L + +F is a compiler to convert Perl XS code into C code. +It is typically run by the makefiles created by L. + +I 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 Perl comes with a profiler, the F module. The F utility analyzes the output of this profiler and tells you @@ -179,17 +213,56 @@ =item L F is the interface to the experimental Perl compiler suite. +=item L + +F is a command-line interface to the test-running functionality of +of F. It's an alternative to C. + +=back + +=head2 Installation + +These utilities help manage extra perl modules that don't come with the perl +distribution. + +=over 3 + +=item L + +F 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 module, + + perl -MCPAN -e shell + +=item L + +A little interface to ExtUtils::Installed to examine installed modules, +validate your packlists and even create a tarball from an installed module. + +=back + +=head2 Other + +=over 3 + +=item L + +B is perl version of B, 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. + =back =head2 SEE ALSO -L, L, L, -L, L, L, -L, L, L, -L, L, L, L, -L, L, L, -L, L, L, L, -L, L +L, L, L, L, L, +L, L, L, L, L, +L, L, L, L, L, L, +L, L, L, L, L, L, +L, L, L, L, L, L, L, +L, L, L, L =cut -------------------- diff ends here -------------------- ```

Perl Info
``` Flags: category=docs severity=low Site configuration information for perl v5.8.8: Configured by ambrus at Sun Feb 19 14:25:24 CET 2006. Summary of my perl5 (revision 5 version 8 subversion 8) configuration: Platform: osname=linux, osvers=2.4.32, archname=i686-linux uname='linux king 2.4.32 #4 sun jan 15 14:34:03 cet 2006 i686 intel(r) celeron(r) cpu 3.20ghz genuineintel gnulinux ' config_args='' hint=recommended, useposix=true, d_sigaction=define usethreads=undef use5005threads=undef useithreads=undef usemultiplicity=undef useperlio=define d_sfio=undef uselargefiles=define usesocks=undef use64bitint=undef use64bitall=undef uselongdouble=undef usemymalloc=n, bincompat5005=undef Compiler: cc='gcc4', ccflags ='-fno-strict-aliasing -pipe -Wdeclaration-after-statement -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64', optimize='-O2', cppflags='-fno-strict-aliasing -pipe -Wdeclaration-after-statement -I/usr/local/include' ccversion='', gccversion='4.0.0', gccosandvers='' intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234 d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12 ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8 alignbytes=4, prototype=define Linker and Libraries: ld='gcc4', ldflags =' -L/usr/local/lib' libpth=/usr/local/lib /lib /usr/lib libs=-lnsl -lndbm -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc perllibs=-lnsl -ldl -lm -lcrypt -lutil -lc libc=/lib/libc-2.3.5.so, so=so, useshrplib=false, libperl=libperl.a gnulibc_version='2.3.5' Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E' cccdlflags='-fpic', lddlflags='-shared -L/usr/local/lib' Locally applied patches: @INC for perl v5.8.8: /usr/local/lib/perl5/5.8.8/i686-linux /usr/local/lib/perl5/5.8.8 /usr/local/lib/perl5/site_perl/5.8.8/i686-linux /usr/local/lib/perl5/site_perl/5.8.8 /usr/local/lib/perl5/site_perl/5.8.5/i686-linux /usr/local/lib/perl5/site_perl/5.8.5 /usr/local/lib/perl5/site_perl . Environment for perl v5.8.8: HOME=/home/ambrus LANG (unset) LANGUAGE (unset) LC_CTYPE=hu_HU LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=/home/ambrus/local/bin:/usr/local/bin:/bin:/usr/bin:/usr/games/bin:/usr/X11R6/bin:/usr/qt/3/bin:/usr/kde/3.2/bin:/opt/Acrobat5:/opt/blackdown-jdk-1.4.1/bin:/opt/blackdown-jdk-1.4.1/jre/bin PERLDOC_PAGER=/usr/bin/less -R PERL_BADLANG (unset) SHELL=/bin/bash ```

Perl / perl5

patch: perlutil.pod missing utilities #8348

From ambrus@math.bme.hu

Created by ambrus@math.bme.hu

From @rgs