develooper Front page | perl.perl5.porters | Postings from February 2006

[perl #38635] patch: perlutil.pod missing utilities

Thread Next
From:
Zsban Ambrus
Date:
February 25, 2006 08:01
Subject:
[perl #38635] patch: perlutil.pod missing utilities
Message ID:
rt-3.0.11-38635-130607.3.51531250888094@perl.org
# New Ticket Created by  Zsban Ambrus 
# Please include the string:  [perl #38635]
# in the subject line of all future correspondence about this issue. 
# <URL: https://rt.perl.org/rt3/Ticket/Display.html?id=38635 >


This is a bug report for perl from ambrus@math.bme.hu,
generated with the help of perlbug 1.35 running under perl v5.8.8.


-----------------------------------------------------------------
[Please enter your report here]


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 --------------------
--- 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<perldoc|perldoc>
@@ -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<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:

@@ -130,8 +132,15 @@
  =item L<libnetcfg|libnetcfg>

  To display and change the libnet configuration run the libnetcfg command.

+=item L<perlivp>
+
+The B<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 B<perl>
+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<perlbug> thoroughly before
  using it to submit a bug report.

+=item L<pl2pm>
+
+F<pl2pm> 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<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
@@ -168,8 +185,25 @@
  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>.
+
+I<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
  F<dprofpp> utility analyzes the output of this profiler and tells you
@@ -179,17 +213,56 @@
  =item L<perlcc|perlcc>

  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>.
+
+=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 Other
+
+=over 3
+
+=item L<piconv>
+
+B<piconv> is 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.
+
  =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>
+L<perldoc>, L<pod2man>, L<perlpod>, L<pod2text>, L<pod2html>,
+L<pod2latex>, L<pod2usage>, L<podselect>, L<podchecker>, L<splain>,
+L<perldiag>, L<roffitall>, L<a2p>, L<s2p>, L<psed>, L<find2perl>,
+L<File::Find>, L<libnetcfg>, L<perlivp>, L<perlbug>, L<pl2pm>, L<h2ph>,
+L<c2ph>, L<pstruct>, L<h2xs>, L<enc2xs>, L<xsubpp>, L<dprofpp>, L<perlcc>,
+L<prove>, L<cpan>, L<instmodsh>, L<piconv>

  =cut
-------------------- diff ends here --------------------


[Please do not change anything below this line]
-----------------------------------------------------------------
---
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


Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About