[perl #114316] '--splithead' option to 'installhtml' fails to clean up after itself

# 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