[perl #114022] Pod-Html output differs between explicit outfile and redirection from STDOUT

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


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 the 'pod2html' utility states that it is called:

#####
pod2html --help --htmlroot=<name> --infile=<name> --outfile=<name>
         --podpath=<name>:...:<name> --podroot=<name>
         --recurse --norecurse --verbose
         --index --noindex --title=<name>
#####

... and goes on to state:

#####
outfile
     --outfile=name

     Specify the HTML file to create.  Output goes to STDOUT if no 
outfile is specified.
#####

The POD for core module Pod::Html (around which pod2html is a simple 
wrapper) states much the same with respect to 'outfile'.

I would intuitively expect that if I (1) ran pod2html with '--outfile' 
set; (2) then ran it again *without* setting '--outfile' but redirecting 
STDOUT to a file; that (3) there would be no difference between the 
.html files created by either approach.

Peeking further into the Pod::Html code, I would also intuitively expect 
that if I (1) ran pod2html with '--outfile' set to a file; (2) then ran 
it again with '--outfile=-' (i.e., STDOUT); that (3) there would also be 
no difference between the .html files created by either approach.

Either my expectation is incorrect or there is a bug in Pod::Html.

The program attached, 'feature.pl', is adapted from 
'ext/Pod-Html/t/feature.t' in the Perl 5 distribution.  't/feature.t' 
reads a .pod file, writes an .html file, creates a second .html file 
based on HTML code found in the __DATA__ section of 't/feature.t', then 
runs a diff on the two files.

'feature.pl' has been modified to remove the explicit testing features 
and to respond differently on the basis of a command-line option 
'--control' which may be 0, 1 or 2:

#####
perl -Ilib feature.pl --control=0
#   0:  --outfile is explicitly set to a file called '.t/feature.html'

perl -Ilib feature.pl --control=1 1> t/1feature.html
#   1:  --outfile is set to '-'; STDOUT is redirected to 't/1feature.html'

perl -Ilib feature.pl --control=2 1> t/2feature.html
#   2:  --outfile is not set; STDOUT is redirected to 't/2feature.html'
#####

Here is the diff between the first two .html files:
#####
$ diff ./t/feature.html ./t/1feature.html
32c32
< <p>some text and a link <a href="t/crossref.html">crossref</a></p>
---
 > <p>some text and a link <a href="/t/crossref.html">crossref</a></p>
#####

Option '--control=2' produced exactly the same output as '--control=1', 
so '2' produces the same diff with respect to '0' as does '1'.

Thus, running pod2hml or Pod::Html does not produce the same .html 
output when sent to STDOUT as opposed to being sent to an explicit file. 
  This contradicts my intuitive expectation and is, I assert, a bug.

I discovered this bug in the course of working on my fork of Pod::Html 
(https://github.com/jkeenan/Pod-Html).  When I ran coverage analysis, I 
began to suspect that the "print directly to STDOUT" option was not 
being tested by the current Pod::Html test suite.  This was not really 
surprising, as I have had difficulty writing tests for this option 
notwithstanding a lot of refactoring to make the code more explicitly 
testable (http://thenceforward.net/Pod-Html/coverage/lib-Pod-Html-pm.html).

My hunch is that this bug lies in either the code or the usage of 
subroutine relativize_url() found in the 
Pod::Simple::XHTML::LocalPodLinks, itself found in lib/Pod/Html.pm.  But 
I don't understand the code well enough to pinpoint the problem -- and 
I'm not really sure what the correct output should be.

Thoughts?  Thank you very much.


[Please do not change anything below this line]
-----------------------------------------------------------------
---
Flags:
     category=library
     severity=medium
     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 #114022] Pod-Html output differs between explicit outfile and redirection from STDOUT by James E Keenan via RT
• [perl #114022] Pod-Html output differs between explicit outfile and redirection from STDOUT by James E Keenan
• Re: [perl #114022] Pod-Html output differs between explicit outfileand redirection from STDOUT by Nicholas Clark