Front page | perl.perl5.porters |
Postings from August 2012
[perl #114466] Clarify purpose of 'installhtml'
From:
James E Keenan
Date:
August 12, 2012 19:03
Subject:
[perl #114466] Clarify purpose of 'installhtml'
Message ID:
rt-3.6.HEAD-11172-1344823367-1308.114466-75-0@perl.org
# 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