[perl #114466] Clarify purpose of 'installhtml'

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


This is a bug report for perl from jkeenan@cpan.org,
generated with the help of perlbug 1.39 running under perl 5.16.0.

The program 'installhtml' is included in the Perl 5 core distribution 
and lives at the top level thereof -- the same level as similarly named 
programs 'installperl' and 'installman'.  installhtml's DESCRIPTION states:

#####
I<installhtml> converts a collection of POD pages to a corresponding
collection of HTML pages.  This is *primarily* used to convert the pod
pages found in the perl distribution.  [Emphasis added.]
#####

I believe the use of the work "primarily" here is misleading, as it 
implies that quite possibly 'installhtml' has some use as a POD to HTML 
converter for sets of files *other than* the Perl 5 core distribution. 
To the contrary:  'installhtml' is *only* of use in the context of the 
Perl 5 core distribution.  It cannot be used elsewhere because its 
'--splitpod' command-line option requires the existence of a *separate* 
executable called 'pod/splitpod'.  Such an executable happens to exist 
in the Perl 5 core distribution but is unlikely to appear in any other 
collection of files containing POD.

Moreover, unlike 'installperl' and 'installman', 'installhtml' appears 
to be an "after-market" program, that is, it's not part of a regular 
Perl 5 installation but is something which a user who wants core 
documentation in HTML format would use after regular installation -- 
including POD and man page installation -- has completed.  This is 
evident from this section from 'INSTALL':

#####
Some sites may wish to make perl documentation available in HTML
format.  The installhtml utility can be used to convert pod
documentation into linked HTML files and install them.

Currently, the supplied ./installhtml script does not make use of the
html Configure variables.  This should be fixed in a future release.

The following command-line is an example of one used to convert
perl documentation:

   ./installhtml                   \
       --podroot=.                 \
       --podpath=lib:ext:pod:vms   \
       --recurse                   \
       --htmldir=/perl/nmanual     \
       --htmlroot=/perl/nmanual    \
       --splithead=pod/perlipc     \
       --splititem=pod/perlfunc    \
       --verbose
#####

Hence, I believe the documentation in 'installhtml' should be modified 
to make clear that it is not a general-purpose installer of HTML files 
containing POD, but rather something of use only in the context of the 
Perl 5 core distribution -- and optionally so at that.

Please review the patch attached.

Thank you very much.
Jim Keenan

---
Flags:
     category=utilities
     severity=low
---
Site configuration information for perl 5.16.0:

Configured by jimk at Sun May 20 20:01:26 EDT 2012.

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'

Locally applied patches:


---
@INC for perl 5.16.0:
     /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
     .

---
Environment for perl 5.16.0:
 
DYLD_LIBRARY_PATH=/Users/jimk/work/pseudoinstall/lib:/Users/jimk/gitwork/parrot/blib/lib
     HOME=/Users/jimk
     LANG (unset)
     LANGUAGE (unset)
     LD_LIBRARY_PATH (unset)
     LOGDIR (unset)
 
PATH=/usr/local/bin:/opt/local/bin:/opt/local/sbin:/usr/local/bin:/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/Users/jimk/bin:/Users/jimk/bin/perl:/Users/jimk/bin/c:/Users/jimk/bin/shell:/sw/lib:/sw/bin:/Users/jimk/bin:/Users/jimk/bin/perl:/Users/jimk/bin/c:/Users/jimk/bin/shell:/sw/lib:/sw/bin
     PERL_BADLANG (unset)
     SHELL=/bin/bash

• [perl #114466] Clarify purpose of 'installhtml' by James E Keenan