kcott has asked for the wisdom of the Perl Monks concerning the following question:

I have pod_link_test.pod: 


=encoding utf8

L<perlpod>

L<strict>

L<Getopt::Long>

L<Text::CSV>

L<man(1)>

=cut

[download]

When I run: 

$ pod2html --infile pod_link_test.pod --outfile pod_link_test.html

[download]

The HTML code, with the links, in pod_link_test.html, looks like: 

<p><a>perlpod</a></p>

<p><a>strict</a></p>

<p><a>Getopt::Long</a></p>

<p><a>Text::CSV</a></p>

<p><a href="http://man.he.net/man1/man">man(1)</a></p>

[download]

I was hoping the links (except man(1)) would actually look like: 

<p><a href="https://metacpan.org/pod/name>name</a></p>

[download]

I feel like I'm missing something obvious, but have no idea what that might be.

I did a fairly extensive search (both Super Search and general Internet) but came up with little of help. I did find "POD: embedding/linking/displaying html and images on metacpan and github" which provided a link to "MetaCPAN Pod Renderer". When I pasted the same pod_link_test.pod code into this, I did get actual links with the https://metacpan.org/pod/ prefix.

I did a search of my system for man.he.net: I only found two files where it occurs.

In .../Pod/Simple/XHTML.pm, I found: 

...
  $new->perldoc_url_prefix('https://metacpan.org/pod/');
  $new->man_url_prefix('http://man.he.net/man');
...

[download]

In .../Pod/Simple/HTML.pm, I found: 

...
$Perldoc_URL_Prefix  = 'https://metacpan.org/pod/'
 unless defined $Perldoc_URL_Prefix;
...
$Man_URL_Prefix  = 'http://man.he.net/man';
...

[download]

I can't see $Perldoc_URL_Prefix being defined anywhere.

I'm using Perl 5.34.0; pod2html is a core utility in that version.

Any guidance on this would be very much appreciated.

— Ken

Replies are listed 'Best First'.
Re: pod2html: link (L<...>) formatting code
by haj (Vicar) on Dec 14, 2021 at 14:07 UTC

    Unfortunately, pod2html does not work like this. You only get links for stuff where pod2html is able to locate a POD source, where it assumes that the POD sources and the resulting HTML tree have the same directory layout. Only when pod2html is able to locate a source, it will prepend htmlroot (after stripping podroot).

    You can add --verbose to see pod2html complain that it left the links unresolved.

    I guess that the MetaCPAN POD renderer has its own Pod-to-HTML converter. Probably the place to hook into is sub resolve_pod_page_link in Pod::HTML.

[reply]

      G'day haj,

      ++ Many thanks for your reply.

      "Unfortunately, pod2html does not work like this. ..."

      I think that explains my earlier statement: "I feel like I'm missing something obvious, but have no idea what that might be."

      I didn't realise that I needed --verbose to display warning messages. I did try it and sure enough: 

      ...
Cannot find file "perlpod.*" directly under podpath, cannot find suita
+ble replacement: link remains unresolved.
Cannot find file "strict.*" directly under podpath, cannot find suitab
+le replacement: link remains unresolved.
Cannot find file "Getopt/Long.*" directly under podpath, cannot find s
+uitable replacement: link remains unresolved.
Cannot find file "Text/CSV.*" directly under podpath, cannot find suit
+able replacement: link remains unresolved.

      [download]

      Based on that, I tried adding '--podpath=`perl -e 'print join ":", @INC'` --recurse'. This did produce links with href= values like "/path/to/name.html"; however, none of those name.html files existed — there were equivalent name.pod or name.pm files at the /path/to/ locations.

      That may be worth pursuing, or perhaps your suggestion of "hook into sub resolve_pod_page_link" would be a better option. Anyway, that's got me further along than I was before, so thanks again.

      — Ken

[reply]
[d/l]
[select]
Re: pod2html: link (L<...>) formatting code
by LanX (Saint) on Dec 14, 2021 at 10:03 UTC
    Did you try --podroot and/or --htmlroot see pod2html

    (No possibility to test right now)

[reply]

      G'day Rolf,

      Thanks for the suggestion. I did try those; unfortunately, to no avail.

      I also noted that pod2html was a wrapper around Pod::Html, whose ENVIRONMENT section has "Uses $Config{pod2html} to setup default options.". I checked the source (https://metacpan.org/dist/perl/source/ext/Pod-Html/lib/Pod/Html.pm) but that doesn't provide any additional options to the published ones. At line 522: 

      sub parse_command_line {
    my ($opt_backlink,...,$opt_verbose);
 
    unshift @ARGV, split ' ', $Config{pod2html} if $Config{pod2html};
    my $result = GetOptions(
                       'backlink!'  => \$opt_backlink,
                       ...,
                       'verbose!'   => \$opt_verbose,
    );
    usage("-", "invalid parameters") if not $result;
    ...
}

      [download]

      — Ken

[reply]
[d/l]
[select]
Re: pod2html: link (L<...>) formatting code (timeloop)
by Anonymous Monk on Dec 14, 2021 at 12:55 UTC
[reply]

      Thanks for the feedback; I checked all of the links you provided.

      App::Pod2CpanHtml seemed promising but, being around nine years old, looked like it might need a few tweaks for my purposes (e.g. changing http://search.cpan.org/ to https://metacpan.org/pod/ and probably the hard-coded CSS URL). When I attempted to install this, I got a checksum warning: I decided not to proceed.

      — Ken

[reply]
[d/l]
[select]
        Um checksum? Simply try again, likely an incomplete download

        Also its just one of many that call Pod::Simple..., like the aformentioned Xhtml or Pod::Simple::HTMLBatch

[reply]

Back to Seekers of Perl Wisdom