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.
[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

(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;
    ...
}
[download]

— Ken

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