[perl #114028] Pod-Html tests contradict instructions in documentation

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




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.


-----------------------------------------------------------------
[Please describe your issue here]

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

[Please do not change anything below this line]
-----------------------------------------------------------------
---
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

• [perl #114028] Pod-Html tests contradict instructions in documentation by James E Keenan