Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[PATCH] Clarify purpose of 'installhtml' #12331

Closed
p5pRT opened this issue Aug 13, 2012 · 5 comments
Closed

[PATCH] Clarify purpose of 'installhtml' #12331

p5pRT opened this issue Aug 13, 2012 · 5 comments

Comments

@p5pRT
Copy link

p5pRT commented Aug 13, 2012

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

Searchable as RT114466$

@p5pRT
Copy link
Author

p5pRT commented Aug 13, 2012

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
Copy link
Author

p5pRT commented Aug 13, 2012

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
Copy link
Author

p5pRT commented Dec 31, 2016

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
Copy link
Author

p5pRT commented Dec 31, 2016

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

@p5pRT
Copy link
Author

p5pRT commented Dec 31, 2016

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant