Front page | perl.perl5.porters |
Postings from July 2012
[perl #114316] '--splithead' option to 'installhtml' fails to clean up after itself
From:
James E Keenan
Date:
July 29, 2012 18:50
Subject:
[perl #114316] '--splithead' option to 'installhtml' fails to clean up after itself
Message ID:
rt-3.6.HEAD-11172-1343612990-652.114316-75-0@perl.org
# New Ticket Created by James E Keenan
# Please include the string: [perl #114316]
# in the subject line of all future correspondence about this issue.
# <URL: https://rt.perl.org:443/rt3/Ticket/Display.html?id=114316 >
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.
In the course of studying and working on Pod-Html
(https://github.com/jkeenan/Pod-Html), I have also had occasion to study
the program 'installhtml' which is included in the Perl 5 core
distribution. 'installhtml' is a program which prepares and executes
repeated calls of Pod::Html::pod2html() on a selection of files
containing documentation in POD format. That preparatory code is
documented in a usage() statement but is non-trivial, only partially
encapsulated in subroutines and lacks unit tests. I have begun writing
such unit tests and, not surprisingly, have begun to come across that I
think are bugs. This is the first of what are likely to be a series of
bug reports.
Bug: The '--splithead' option to 'installhtml' fails to clean up after
itself.
'installhtml' documents the '--splithead' option as follows:
#####
--splithead: POD files to split on =head directive
Comma-separated list of pod files to split by the =head directive. The
.pod suffix is optional. These files should have names specified
relative to podroot.
#####
Let's suppose that I have several files containing POD named like this:
#####
xt/split/splithead1.pod
xt/split/splithead2.pod
#####
... and that these files have contents like this:
#####
$ cat xt/split/splithead1.pod
=head1 Feature A
A paragraph
=head1 Feature B
some text but not a link
=cut
#####
I would expect that if I were to call:
#####
installhtml \
--podroot=./xt \
--podpath=split \
--splithead=split/splithead1.pod,split/splithead2.pod \
--htmldir=./tmphtml \
--recurse
#####
... I would end up with these new .html files:
#####
tmphtml/split/splithead1.html
tmphtml/split/splithead1/feature_a.html
tmphtml/split/splithead1/feature_b.html
tmphtml/split/splithead1.html
tmphtml/split/splithead2/feature_c.html
tmphtml/split/splithead2/feature_d.html
#####
But I would *not* expect to end up with any new .pod files under
xt/split/. In other words, I would expect 'installhtml' to remove any
.pod files it created as intermediate steps toward the creation of
per-POD-head .pod files.
In fact, however, 'installhtml' creates intermediate .pod files and
directories to hold those files:
#####
./xt/split/splithead1.pod
./xt/split/splithead1/feature_a.pod
./xt/split/splithead1/feature_b.pod
./xt/split/splithead2.pod
./xt/split/splithead2/feature_c.pod
./xt/split/splithead2/feature_d.pod
#####
The splithead1/ and splithead2/ subdirectories and the four
'feature-*.pod' files, AFAICT, serve no purpose after the corresponding
.html files have been created.
These .pod files and directories ought to be cleaned up automatically;
currently, they are not. This needs to be fixed, perhaps by using
File::Temp to create a tempdir in which to perform these intermediate steps.
(At https://github.com/jkeenan/Pod-Html/tree/fork_original I have add
t/install_html_splithead.t which contains TODO-ed tests concerning this
lack of cleanup. The 'fork_original' branch is intended to be Pod::Html
and installhtml as they are found in blead, with source code modified
just enough to get them to enable them to be tested with 'dzil test'.)
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 #114316] '--splithead' option to 'installhtml' fails to clean up after itself
by James E Keenan