[perl #114318] '--splithead' option to 'installhtml' creates incorrect links

# New Ticket Created by  James E Keenan 
# Please include the string:  [perl #114318]
# in the subject line of all future correspondence about this issue. 
# <URL: https://rt.perl.org:443/rt3/Ticket/Display.html?id=114318 >


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.

This is the second in a series of bug reports about 'installhtml' -- a 
program, found in the Perl 5 core distribution, which prepares and 
executes repeated calls of Pod::Html::pod2html() on a selection of files 
containing documentation in POD format.  (See the "Links" in RT or 
https://rt.perl.org/rt3/Ticket/Display.html?id=112014 for related tickets.)

Bug:  The '--splithead' option to installhtml creates incorrect indices 
and other cross-links in .html files generated by its calls to 
Pod::Html::pod2html().

'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

$ cat xt/split/splithead2.pod
=head1 Feature C

Yet another paragraph

=head1 Feature D

More text; still no link.

=cut
#####

When I call:

#####
installhtml \
   --podroot=./xt \
   --podpath=split \
   --splithead=split/splithead1.pod,split/splithead2.pod \
   --htmldir=./tmphtml \
   --recurse
#####

... I end up with these .html files:

#####
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
tmphtml/split/splithead2.html
#####

Note that in the source code .pod files, the values for the =head1 
entries are *Initial Caps*.  The files that get created however, are 
named *all_lower_case*, with underscores substituting for spacebands.

In the generated .html files however, the links tend to be composed as 
expecting Initial Caps.  For example, in tmphtml/split/splithead1.html, 
I get:

#####
  <ul id="index">
   <li><a href="../../splithead1/Feature-A.html">Feature A</a></li>
   <li><a href="../../splithead1/Feature-B.html">Feature B</a></li>
</ul>
#####

Clicking on those links generates Page Load Errors.  There are at least 
two problems here:

(1) the "../../" is not resolving to "tmphtml/split/" but to ".".  (This 
may be a lack of understanding on my part.)

(2) The link is looking for a generated .html file with a basename 
"Feature_A.html"  The file actually created was "feature_a.html".

Turning to tmphtml/split/splithead1/feature_a.html, I get these links:

#####
<ul>

<li><p>Forward to <a 
href="../../../split/splithead1.html#Feature-B">&quot;Feature B&quot; in 
splithead1</a></p>

</li>
<li><p>Up to <a href="../../../split/splithead1.html">splithead1</a></p>

</li>
</ul>
#####

(3) The "../../../split/" in both of the "Forward to" and the "Up to" 
links lack the 'tmphtml/' part of the path needed to resolve correctly.

The .html files are being generated in the directories I expect, but 
their links are not correct.

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 #114318] '--splithead' option to 'installhtml' creates incorrect links by James E Keenan via RT
• Re: [perl #114318] '--splithead' option to 'installhtml' createsincorrect links by Dr.Ruud
• [perl #114318] '--splithead' option to 'installhtml' creates incorrect links by James E Keenan