Open p5pRT opened 7 years ago
Hello\, world!
When pod2html is given relative paths\, especially for --podroot\, it produces incorrect links to other modules. For example:
$ mkdir /tmp/qq $ cd /tmp/qq $ mkdir lib out $ echo >lib/A.pm -e "=pod\n\nL\" $ echo >lib/B.pm -e "=pod\n\nTEST" $ pod2html --htmldir=out --infile lib/A.pm --outfile out/A.html --podroot lib --podpath . $ grep B.html out/A.html \
\B\\
When I switch to absolute paths\, it helps:
$ pod2html --htmldir=out --infile lib/A.pm --outfile out/A.html --podroot `pwd`/lib --podpath . $ grep B.html out/A.html \
\B\\
However\, if the current working directory contains a symlink\, it again fails:
$ ln -s qq /tmp/pp $ cd /tmp/pp $ pod2html --htmldir=out --infile lib/A.pm --outfile out/A.html --podroot `pwd`/lib --podpath . $ grep B.html out/A.html- \
\B\\
It obviously mixes up paths with symlinks resolved and those without.
When I replace `pwd` by $(readlink -f `pwd`)\, it works again.
Checked with Perl 5.24 on Debian Stretch and the behavior is identical.
From @gollux
When pod2html is given relative paths, especially for --podroot, it produces incorrect links to other modules. For example:
$ mkdir /tmp/qq $ cd /tmp/qq $ mkdir lib out $ echo >lib/A.pm -e "=pod\n\nL
" $ echo >lib/C.pm -e "=pod\n\nTEST" $ pod2html --htmldir=out --infile lib/A.pm --outfile out/A.html --podroot lib --podpath . $ grep C.html out/A.html When I switch to absolute paths, it helps:
$ pod2html --htmldir=out --infile lib/A.pm --outfile out/A.html --podroot
pwd
/lib --podpath . $ grep C.html out/A.htmlHowever, if the current working directory contains a symlink, it again fails:
$ ln -s qq /tmp/pp $ cd /tmp/pp $ pod2html --htmldir=out --infile lib/A.pm --outfile out/A.html --podroot
pwd
/lib --podpath . $ grep C.html out/A.html-It obviously mixes up paths with symlinks resolved and those without.
When I replace
pwd
by $(readlink -fpwd
), it works again.Checked with Perl 5.24 on Debian Stretch and the behavior is identical. Perl Info
[In quoting the Original Poster above, I changed 'B' to 'C' to avoid a Markdown problem.]
What I think this bug report indicates is a limitation in our test suite for Pod-Html.
The documentation for Pod::Html clearly states:
=item podroot
--podroot=name
Specify the base directory for finding library pods. Default is the
current working directory.
That suggests that there should be some unit tests in ext/Pod-Html/t
which do not provide a value for --podroot
, thereby causing a particular unit test to 'use the default'. However, most (perhaps all) of the tests in Pod-Html's test suite use a function exported from pod2html-lib.pl
, convert_n_test()
, which calculates a string which is an absolute path and then provides that string as an explicit (i.e., a non-default) argument to the relevant function:
my $cwd = Pod::Html::_unixify( Cwd::cwd() );
... # snip
Pod::Html::pod2html(
"--infile=$infile",
"--outfile=$outfile",
"--podpath=t",
"--htmlroot=/",
"--podroot=$cwd",
@p2h_args,
);
So we really haven't tested the case where the value provided to --podroot
is a relative path -- the case the OP is reporting as problematic.
Now, this is a case where, if we changed the documentation, the problem would simply go away. We could say that any value provided to --podroot
must be an absolute path (and not one where one of the path components is a symlink). We could then write additional tests where we do not provide a value for --podroot
in the test code, thereby 'falling back to the default'. Given that Pod-Html is blead-upstream and does not get a separate CPAN release, we don't have to meet expectations of backwards compatibility. That would reduce ambiguity and improve maintainability in 5.34 and going forward.
An additional note: , the value representing the "current working directory" changes depending on how you seek it.
$ cd /tmp
$ perl -MCwd -E 'say cwd();'
/tmp
$ perl -MCwd -E 'say Cwd::cwd();'
/tmp
$ perl -MFile::Spec -E 'say File::Spec->curdir();'
.
In its code and test suite, Pod-Html use all three variants.
Thank you very much. Jim Keenan
Migrated from rt.perl.org#132057 (status was 'new')
Searchable as RT132057$