[PATCH] Clarify purpose of 'installhtml' #12331

p5pRT · 2012-08-13T02:02:46Z

Migrated from rt.perl.org#114466 (status was 'resolved')

Searchable as RT114466$

p5pRT · 2012-08-13T02:02:46Z

From @jkeenan

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

p5pRT · 2012-08-13T02:02:46Z

From @jkeenan

0001-Clarify-that-installhtml-is-intended-only-for-use-in.patch

From 95d1b7c2ae6f6ea9fb8aab88d5c82d430a5ff5c9 Mon Sep 17 00:00:00 2001
From: jkeenan <jkeenan@cpan.org>
Date: Sun, 12 Aug 2012 21:55:42 -0400
Subject: [PATCH] Clarify that 'installhtml' is intended only for use in the Perl 5 core distribution.

---
 installhtml |   15 +++++++++------
 1 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/installhtml b/installhtml
index 75d6adc..2043b1e 100644
--- a/installhtml
+++ b/installhtml
@@ -23,8 +23,10 @@ installhtml - converts a collection of POD pages to HTML format.
 =head1 DESCRIPTION
 
 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.
+collection of HTML pages.  This is used to convert the pod
+pages found in the perl distribution.  (It is not intended as a
+general-purpose converter/installer of POD pages in HTML format.  See
+L<Pod::Html>.)
 
 =head1 OPTIONS
 
@@ -67,10 +69,11 @@ relative to podroot.
 
 =item B<--splititem> POD files to split on =item directive
 
-Comma-separated list of all pod files to split by the =item directive.
-The .pod suffix is optional.  I<installhtml> does not do the actual
-split, rather it invokes I<splitpod> to do the dirty work.  As with
---splithead, these files should have names specified relative to podroot.
+Comma-separated list of all pod files to split by the =item directive.  The
+.pod suffix is optional.  I<installhtml> does not do the actual split, rather
+it invokes I<splitpod>, a separate program in the Perl 5 core distribution,
+to do the dirty work.  As with --splithead, these files should have names
+specified relative to podroot.
 
 =item B<--splitpod> Directory containing the splitpod program
 
-- 
1.6.3.2

p5pRT · 2016-12-31T15:59:08Z

From @jkeenan

On Mon, 13 Aug 2012 02:02:46 GMT, jkeen@verizon.net wrote:

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

Pushed to blead (with some line rebreaking) in commit 4446c20.

Marking ticket Resolved.

Thank you very much.

--
James E Keenan (jkeenan@cpan.org)

p5pRT · 2016-12-31T15:59:08Z

The RT System itself - Status changed from 'new' to 'open'

p5pRT · 2016-12-31T15:59:08Z

@jkeenan - Status changed from 'open' to 'resolved'

p5pRT closed this as completed Dec 31, 2016

p5pRT added Severity Low distro-All documentation hasPatch type-utilities labels Oct 19, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[PATCH] Clarify purpose of 'installhtml' #12331

[PATCH] Clarify purpose of 'installhtml' #12331

p5pRT commented Aug 13, 2012

p5pRT commented Aug 13, 2012

p5pRT commented Aug 13, 2012

p5pRT commented Dec 31, 2016

p5pRT commented Dec 31, 2016

p5pRT commented Dec 31, 2016

[PATCH] Clarify purpose of 'installhtml' #12331

[PATCH] Clarify purpose of 'installhtml' #12331

Comments

p5pRT commented Aug 13, 2012

p5pRT commented Aug 13, 2012

From @jkeenan

p5pRT commented Aug 13, 2012

From @jkeenan

p5pRT commented Dec 31, 2016

From @jkeenan

p5pRT commented Dec 31, 2016

p5pRT commented Dec 31, 2016