From @jkeenan

Created by @jkeenan

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.

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

From @jkeenan

feature.pl

From @jkeenan

=head1 Head 1

A paragraph

=for html some html

=begin image

|--|
| |
|--|

=end image

Another paragraph

=head1 Another Head 1

some text and a link L<crossref>

=cut

From @jkeenan

Here is some data that may ultimately be the same bug ... only this time
from the STDIN side rather than STDOUT.

There exists in the Pod​::Html test suite a file called 't/feature.t'
which uses 't/feature.pod' as its '--infile' value. Suppose we modify
sub convert_n_test() from 't/pod2html-lib.pl' to not unlink any .html
file created by running a test. Then, when we run​:

#####
prove -Ilib -v t/feature.t
#####

... there will be created a file called 't/feature.html'.

Now suppose that we create a situation where the POD source is coming in
on STDIN. Note that there is currently no test for this in the
Pod​::Html test suite. To mimic the functionality of convert_n_test()
and the specific arguments used in 't/feature.t', we would say this​:

#####
$ perl -Ilib -MPod​::Html -MCwd -MFile​::Spec​::Functions -e '$cwd =
cwd(); pod2html("",
"--outfile=t/from_stdin_feature.html",
"--podpath=t",
"--htmlroot=/",
"--podroot=$cwd",
"--backlink",
"--css=style.css",
"--header", # no styling b/c of --ccs
"--htmldir=". catdir($cwd, 't'),
"--noindex",
"--podpath=t",
"--podroot=$cwd",
"--title=a title",
"--quiet",
"--libpods=perlguts​:perlootut",);' < t/feature.pod
#####

The result would be 't/from_stdin_feature.html'. Diffing this against
our first .html output, we get​:

#####
$ diff t/feature.html t/from_stdin_feature.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>
#####

Exactly the same difference as reported in the OP. So either the code
is correct but counterintuitive or incorrect and a bug.

Thank you very much.
Jim Keenan

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

From @nwc10

On Fri, Jul 06, 2012 at 05​:41​:02PM -0700, James E Keenan wrote​:

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.

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

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.

From your description, it sounds like Pod​::Html is conflating two things

1) the name of the file on disk to write output to
2) the path within the document tree that the contents represent

It feels like there should be a distinct separate option to specify the
path within the document tree (used to generate relative URLs), and if that's
not specified, assume nothing and not generate relative URLs.

Also, if it's generating relative URLs *correctly*, are they just a space
optimisation? As in, if the existing code to generate relative URLs where
possible is disabled, do any previously working links break? Which would
mean that it should be safe to change the behaviour for --outfile explicitly
set to be the same as that for unset, or set to - (ie STDOUT)

(I've not looked at the code)

So, yes, smells like a bug to me.

Nicholas Clark

From @jkeenan

Created by @jkeenan

The documentation for the 'pod2html' utility states that it is called​:

pod2html --help --htmlroot= --infile= --outfile=
--podpath=​:...​: --podroot=
--recurse --norecurse --verbose
--index --noindex --title=

... 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.
[snip]

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

Taking another look at this bug report I filed back in my (P5P) youth, I find that I cannot reproduce the original problem, so I infer it must have gotten fixed somehow in the intervening 8-1/2 years.

Dummy copy file:

$ cat t/feature.pod
=head1 Head 1

A paragraph

=for html some html

=begin image

|--|
|  |
|--|

=end image

Another paragraph

=head1 Another Head 1

some text and a link L<crossref>

=cut

Place that file in a subdirectory called t/.
Run with explicit outfile.

$ pod2html --infile=t/feature.pod --outfile=t/4feature.html

Run with outfile specified as command-line option.

$ pod2html --infile=t/feature.pod > t/5feature.html
$ diff t/4feature.html t/5feature.html
$ [no output]

I will close this ticket within 7 days unless someone can demonstrate why it should be kept open.

Thank you very much.
Jim Keenan

[snip]

Taking another look at this bug report I filed back in my (P5P) youth, I find that I cannot reproduce the original problem, so I infer it must have gotten fixed somehow in the intervening 8-1/2 years.

Dummy copy file:

$ cat t/feature.pod
=head1 Head 1

A paragraph

=for html some html

=begin image

|--|
|  |
|--|

=end image

Another paragraph

=head1 Another Head 1

some text and a link L<crossref>

=cut

Place that file in a subdirectory called t/.
Run with explicit outfile.

$ pod2html --infile=t/feature.pod --outfile=t/4feature.html

Run with outfile specified as command-line option.

$ pod2html --infile=t/feature.pod > t/5feature.html
$ diff t/4feature.html t/5feature.html
$ [no output]

I will close this ticket within 7 days unless someone can demonstrate why it should be kept open.

No one has argued for keeping this ticket open. Accordingly, closing.

Thank you very much.
Jim Keenan