[perl #117003] Porting/pod_lib.pl: Add documentation in POD format

# New Ticket Created by  James E Keenan 
# Please include the string:  [perl #117003]
# in the subject line of all future correspondence about this issue. 
# <URL: https://rt.perl.org:443/rt3/Ticket/Display.html?id=117003 >


During the course of the New York Perl Hackathon, we realized that 
Porting/pod_lib.pl lacked any documentation in POD format.  Since its 
functions are used in about a half dozen other programs in the Perl 5 
core distribution, it would be good to have subroutine-level 
documentation accessible via 'perldoc'.

Attached is a patch which begins this documentation.  Other participants 
in the hackathon will be picking it up and writing the subroutine-level 
descriptions.

Thank you very much.
Jim Keenan

-----
Summary of my perl5 (revision 5 version 16 subversion 0) configuration:

   Platform:
     osname=darwin, osvers=8.11.0, archname=darwin-2level
     uname='darwin macintosh-8.local 8.11.0 darwin kernel version 
8.11.0: wed oct 10 18:26:00 pdt 2007; root:xnu-792.24.17~1release_ppc 
power macintosh powerpc '
     config_args='-des'
     hint=recommended, useposix=true, d_sigaction=define
     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='cc', ccflags ='-fno-common -DPERL_DARWIN -fno-strict-aliasing 
-pipe -I/usr/local/include -I/opt/local/include',
     optimize='-O3',
     cppflags='-fno-common -DPERL_DARWIN -fno-strict-aliasing -pipe 
-I/usr/local/include -I/opt/local/include'
     ccversion='', gccversion='4.0.1 (Apple Computer, Inc. build 5250)', 
gccosandvers=''
     intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=4321
     d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
     ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t', 
lseeksize=8
     alignbytes=8, prototype=define
   Linker and Libraries:
     ld='env MACOSX_DEPLOYMENT_TARGET=10.3 cc', ldflags =' 
-L/usr/local/lib -L/opt/local/lib'
     libpth=/usr/local/lib /opt/local/lib /usr/lib
     libs=-ldbm -ldl -lm -lc
     perllibs=-ldl -lm -lc
     libc=, so=dylib, useshrplib=false, libperl=libperl.a
     gnulibc_version=''
   Dynamic Linking:
     dlsrc=dl_dlopen.xs, dlext=bundle, d_dlsymun=undef, ccdlflags=' '
     cccdlflags=' ', lddlflags=' -bundle -undefined dynamic_lookup 
-L/usr/local/lib -L/opt/local/lib'


Characteristics of this binary (from libperl):
   Compile-time options: HAS_TIMES PERLIO_LAYERS PERL_DONT_CREATE_GVSV
                         PERL_MALLOC_WRAP PERL_PRESERVE_IVUV USE_LARGE_FILES
                         USE_LOCALE USE_LOCALE_COLLATE USE_LOCALE_CTYPE
                         USE_LOCALE_NUMERIC USE_PERLIO USE_PERL_ATOF
   Built under darwin
   Compiled at May 20 2012 20:33:05
   %ENV:
     PERLBREW_BASHRC_VERSION="0.59"
     PERLBREW_HOME="/Users/jimk/.perlbrew"
     PERLBREW_ROOT="/Users/jimk/perl5/perlbrew"
   @INC:
     /usr/local/lib/perl5/site_perl/5.16.0/darwin-2level
     /usr/local/lib/perl5/site_perl/5.16.0
     /usr/local/lib/perl5/5.16.0/darwin-2level
     /usr/local/lib/perl5/5.16.0
     /usr/local/lib/perl5/site_perl/5.14.2
     /usr/local/lib/perl5/site_perl/5.14.0
     /usr/local/lib/perl5/site_perl/5.12.0
     /usr/local/lib/perl5/site_perl/5.10.1
     /usr/local/lib/perl5/site_perl/5.10.0
     /usr/local/lib/perl5/site_perl

• [perl #117003] Porting/pod_lib.pl: Add documentation in POD format by James E Keenan