Pod-Html output differs between explicit outfile and redirection from STDOUT

p5pRT commented 12 years ago

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

Searchable as RT114022$

p5pRT commented 12 years ago

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.

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

some text and a link \crossref\\

---

\
some text and a link \crossref\\
#####

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.

Perl Info

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

p5pRT commented 12 years ago

From @jkeenan

feature.pl

p5pRT commented 12 years ago

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\

=cut

p5pRT commented 12 years ago

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

some text and a link \crossref\\

\
some text and a link \crossref\\
#####

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

p5pRT commented 12 years ago

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

p5pRT commented 12 years ago

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 \< \
some text and a link \crossref\\
---

\
some text and a link \crossref\\
#####

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

jkeenan commented 3 years ago

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

jkeenan commented 3 years ago

[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

Perl / perl5