Pod-Html tests contradict instructions in documentation

[p5pRT]

Migrated from rt.perl.org#114028 (status was 'open')

Searchable as RT114028$

[p5pRT]

From @jkeenan

Created by @jkeenan

The documentation for Pod​::Html states​:

#####
htmlroot
  --htmlroot=name

  Sets the base URL for the HTML files. When
cross-references are made, the HTML root is prepended to the
URL.

  Do not use this if relative links are desired​: use
--htmldir instead.

  Do not pass both this and --htmldir to pod2html; they
are mutually exclusive.

...

htmldir
  --htmldir=name

  Sets the directory to which all cross references in the
resulting html file will be relative. Not passing this
causes all links to be absolute since this is the value that
tells Pod​::Html the root of the documentation tree.

  Do not use this and --htmlroot in the same call to
pod2html; they are mutually exclusive.

#####

Yet many of the tests in the 'ext/Pod-Html/t/' directory in
the Perl 5 core distribution end up assigning to *both*
'--htmlroot' and '--htmldir'. They do this because they rely
on a testing function, 'convert_n_test()', which is imported
from 't/pod2html-lib.pl'​:

#####
sub convert_n_test {
  my($podfile, $testname, @​p2h_args) = @​_;

...

  # To add/modify args to p2h, use @​p2h_args
  Pod​::Html​::pod2html(
  "--infile=$infile",
  "--outfile=$outfile",
  "--podpath=t",
  "--htmlroot=/",
  "--podroot=$cwd",
  @​p2h_args,
  );
#####

Note that if I am using convert_n_test(), '--htmlroot' is
clearly assigned to. If I were to follow the instructions
in the documentation, that would imply that no assignment to
'--htmldir' should occur as part of preparing '@​p2h_args' in
any call to pod2html() in any test file.

However, if I grep or ack the test directory, I see that
several tests violate this norm​:

#####
t/crossref2.t​:23​: convert_n_test("crossref", "cross references",
t/crossref2.t-24- "--podpath=t​:testdir/test.lib",
t/crossref2.t-25- "--podroot=$cwd",
t/crossref2.t-26- "--htmldir=$cwd",
t/crossref2.t-27- "--quiet",
t/crossref2.t-28- );

t/feature.t​:14​:convert_n_test("feature", "misc pod-html features",
t/feature.t-15- "--backlink",
t/feature.t-16- "--css=style.css",
t/feature.t-17- "--header", # no styling b/c of --ccs
t/feature.t-18- "--htmldir=". catdir($cwd, 't'),
t/feature.t-19- "--noindex",
t/feature.t-20- "--podpath=t",
t/feature.t-21- "--podroot=$cwd",
t/feature.t-22- "--title=a title",
t/feature.t-23- "--quiet",
t/feature.t-24- "--libpods=perlguts​:perlootut",
t/feature.t-25- );

t/htmldir1.t​:30​: convert_n_test("htmldir1", "test --htmldir and
--htmlroot 1a",
t/htmldir1.t-31- "--podpath=". catdir($relcwd, 't') . "​:" .
catfile($relcwd, 'testdir/test.lib'),
t/htmldir1.t-32- "--podroot=$v". File​::Spec->rootdir,
t/htmldir1.t-33- "--htmldir=t",
t/htmldir1.t-34- "--quiet",
t/htmldir1.t-35- );

t/htmldir1.t​:39​: convert_n_test("htmldir1", "test --htmldir and
--htmlroot 1b",
t/htmldir1.t-40- "--podpath=$relcwd",
t/htmldir1.t-41- "--podroot=$v". File​::Spec->rootdir,
t/htmldir1.t-42- "--htmldir=". catdir($relcwd, 't'),
t/htmldir1.t-43- "--htmlroot=/",
t/htmldir1.t-44- "--quiet",
t/htmldir1.t-45- );

t/htmldir2.t​:14​:convert_n_test("htmldir2", "test --htmldir and
--htmlroot 2a",
t/htmldir2.t-15- "--podpath=t",
t/htmldir2.t-16- "--htmldir=t",
t/htmldir2.t-17- "--quiet",
t/htmldir2.t-18-);

t/htmldir3.t​:27​: convert_n_test("htmldir3", "test --htmldir and
--htmlroot 3a",
t/htmldir3.t-28- "--podpath=$relcwd",
t/htmldir3.t-29- "--podroot=$v". File​::Spec->rootdir,
t/htmldir3.t-30- "--htmldir=". catdir($cwd, 't', ''), # test removal
trailing slash,
t/htmldir3.t-31- "--quiet",
t/htmldir3.t-32- );

t/htmldir3.t​:36​: convert_n_test("htmldir3", "test --htmldir and
--htmlroot 3b",
t/htmldir3.t-37- "--podpath=". catdir($relcwd, 't'),
t/htmldir3.t-38- "--podroot=$v". File​::Spec->rootdir,
t/htmldir3.t-39- "--htmldir=t",
t/htmldir3.t-40- "--outfile=t/htmldir3.html",
t/htmldir3.t-41- "--quiet",
t/htmldir3.t-42- );

t/htmldir4.t​:15​:convert_n_test("htmldir4", "test --htmldir and
--htmlroot 4a",
t/htmldir4.t-16- "--podpath=t",
t/htmldir4.t-17- "--htmldir=t",
t/htmldir4.t-18- "--outfile=". catfile('t', 'htmldir4.html'),
t/htmldir4.t-19- "--quiet",
t/htmldir4.t-20-);

t/htmldir4.t​:24​:convert_n_test("htmldir4", "test --htmldir and
--htmlroot 4b",
t/htmldir4.t-25- "--podpath=t",
t/htmldir4.t-26- "--podroot=$cwd",
t/htmldir4.t-27- "--htmldir=". catdir($cwd, 't'),
t/htmldir4.t-28- "--norecurse",
t/htmldir4.t-29- "--quiet",
t/htmldir4.t-30-);

t/htmldir5.t​:26​: convert_n_test("htmldir5", "test --htmldir and
--htmlroot 5",
t/htmldir5.t-27- "--podpath=t​:testdir/test.lib",
t/htmldir5.t-28- "--podroot=$cwd",
t/htmldir5.t-29- "--htmldir=$cwd",
t/htmldir5.t-30- "--htmlroot=/",
t/htmldir5.t-31- "--quiet",
t/htmldir5.t-32- );
#####

This raises the possibility that these twelve invocations of
convert_n_test() may give ambiguous, misleading or even
incorrect results. This warrants further investigation.

Thank you very much.
Jim Keenan

Perl Info

Flags:
     category=library
     severity=low
     module=Pod::Html

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]

From @jkeenan

It turns out that it is not just these tests in 'ext/Pod-Html/t/' which
violate the documentation in Pod​::Html. The Perl 5 core distribution
program 'installhtml' also assigns to *both* 'htmlroot' and 'htmldir'.

Here is the relevant code from that program in blead​:

##########
  548 # runpod2html - invokes pod2html to convert a .pod or .pm file
to a .html
  549 # file.
  550 #
  551 sub runpod2html {
  552 my($pod, $doindex) = @​_;
...
  569 # invoke pod2html
  570 print "$podroot/$pod => $htmldir/$html\n" if $verbose;
  571 Pod​::Html​::pod2html(
  572 "--htmldir=$htmldir",
  573 "--htmlroot=$htmlroot",
  574 "--podpath=".join("​:", @​podpath),
  575 "--podroot=$podroot",
  576 "--header",
  577 ($doindex ? "--index" : "--noindex"),
  578 "--" . ($recurse ? "" : "no") . "recurse",
  579 "--infile=$podroot/$pod", "--outfile=$htmldir/$html");
##########

I would guess that 'installhtml' is the real-world program most likely
to use Pod​::Html​::pod2html(). If that program is using Pod​::Html in
contradiction to that function's own documentation, then it is not
surprising that people experience problems installing HTML versions of POD.

Thank you very much.
Jim Keenan

[p5pRT]

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