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.

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-archive.perl.org/perl5/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">"Feature B" 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

From @jkeenan

Clarification of one point​:

[snip]

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>
#####

The problem with the basename in the link is not that the "Feature-A" is
Initial Caps; the link is case-insensitive. The problem is that we get
a hyphen rather than an underscore. We need "Feature_A" or "feature_a",
but not "Feature-A".

jimk

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

From @druud62

On 2012-07-31 02​:49, James E Keenan via RT wrote​:

#####
<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>
#####

The problem with the basename in the link is not that the "Feature-A" is
Initial Caps; the link is case-insensitive.

Side issue​:

Why is the link considered case-insensitive?

"Domain names are not case-sensitive, but other parts of URLs can be."

"URLs in general are case-sensitive (with the exception of machine names)."

http​://www.google.com/intl/en/ABOUT/corporate/index.html
HTTP​://WWW.GOOGLE.COM/intl/en/about/corporate/index.html

--
Ruud

From zefram@fysh.org

This was fixed recently in commit
0bd1c35.

-zefram

@iabyn - Status changed from 'open' to 'pending release'

From @khwilliamson

Thank you for filing this report. You have helped make Perl better.

With the release yesterday of Perl 5.28.0, this and 185 other issues have been
resolved.

Perl 5.28.0 may be downloaded via​:
https://metacpan.org/release/XSAWYERX/perl-5.28.0

If you find that the problem persists, feel free to reopen this ticket.

@khwilliamson - Status changed from 'pending release' to 'resolved'