develooper Front page | perl.perl5.porters | Postings from July 2012

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

From:
James E Keenan via RT
Date:
July 22, 2012 19:03
Subject:
[perl #114028] Pod-Html tests contradict instructions in documentation
Message ID:
rt-3.6.HEAD-11172-1343009019-1705.114028-15-0@perl.org
It turns out that it is not just these tests in 'ext/Pod-Html/t/' which
violate the documentation in Pod::Html.  The Perl 5 core distribution
program 'installhtml' also assigns to *both* 'htmlroot' and 'htmldir'.

Here is the relevant code from that program in blead:

##########
    548 # runpod2html - invokes pod2html to convert a .pod or .pm file
to a .html
    549 #  file.
    550 #
    551 sub runpod2html {
    552     my($pod, $doindex) = @_;
...
    569     # invoke pod2html
    570     print "$podroot/$pod => $htmldir/$html\n" if $verbose;
    571     Pod::Html::pod2html(
    572         "--htmldir=$htmldir",
    573     "--htmlroot=$htmlroot",
    574     "--podpath=".join(":", @podpath),
    575     "--podroot=$podroot",
    576     "--header",
    577     ($doindex ? "--index" : "--noindex"),
    578     "--" . ($recurse ? "" : "no") . "recurse",
    579     "--infile=$podroot/$pod", "--outfile=$htmldir/$html");
##########

I would guess that 'installhtml' is the real-world program most likely
to use Pod::Html::pod2html().  If that program is using Pod::Html in
contradiction to that function's own documentation, then it is not
surprising that people experience problems installing HTML versions of POD.

Thank you very much.
Jim Keenan


---
via perlbug:  queue: perl5 status: new
https://rt.perl.org:443/rt3/Ticket/Display.html?id=114028



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About