Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

pod2html: link (L<...>) formatting code

by kcott (Archbishop)
on Dec 14, 2021 at 00:14 UTC ( #11139597=perlquestion: print w/replies, xml ) Need Help??

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

When I run:

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

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>

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

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

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'); ...

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'; ...

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 (Priest) 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.

      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.

      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

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

    (No possibility to test right now)

      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; ... }

      — Ken

Re: pod2html: link (L<...>) formatting code (timeloop)
by Anonymous Monk on Dec 14, 2021 at 12:55 UTC

      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

        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

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlquestion [id://11139597]
Approved by Athanasius
Front-paged by Corion
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others chilling in the Monastery: (2)
As of 2022-12-03 05:30 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?