Is there a "standard" way to link to other modules in POD for a CPAN module?

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

Earlier this week, I was looking for information on a module on search.cpan.org. While reading through the module's documentation, there were several related modules mentioned, but the links referred to the module on metacpan.org.

Curious, I viewed the module's POD, and found they had used L<text|url> POD linking syntax. When I later viewed the POD of a few other modules that referred (linked) to other modules in a way I expected, I found those modules using the L<module> / L<module/section> / L<text|module> / L<text|module/section> syntax.

To me, this violated the Principle of Least Astonishment (Surprise), but I can see a scenario where the author may not have noticed the issue, such as if (for instance) they use metacpan.org as their preferred interface for finding modules on CPAN. I considered contacting the module's author regarding the linking, but before I potentially made (more of) a fool of myself (than normal) by doing so (and because I am still (at best) a novice with respect to POD), I wanted a "second opinion" (as it were). So, my question is:

Is there a "standard" manner for linking to other modules within CPAN I should recommend, or should I just ignore it as being my issue, not an actual problem worthy of disturbing the author?

My thanks in advance for your shared wisdom and consideration.

Comment on Is there a "standard" way to link to other modules in POD for a CPAN module?

Replies are listed 'Best First'.

Re: Is there a "standard" way to link to other modules in POD for a CPAN module?
by tobyink (Canon) on May 27, 2017 at 19:00 UTC

Use L<Module::Name> and don't link to a specific website. The pod interpreter can then choose whichever is the best source of that module's documentation (maybe a local resource, maybe metacpan.org, whatever).

[reply]
[d/l]

Re^2: Is there a "standard" way to link to other modules in POD for a CPAN module?

by haukex (Archbishop) on May 28, 2017 at 16:58 UTC

I agree with this and just wanted to add a note: One of the POD to HTML converters (I forget which one) always turned a link like L<File::Spec> into something that looked like this: "the File::Spec manpage" (or something to that effect), which of course wasn't very helpful when inserted into various sentences, so I had to take to writing things like "the L<File::Spec|File::Spec> documentation". A little annoying but I guess it's better to be explicit.

[reply]
[d/l]
[select]

Re: Is there a "standard" way to link to other modules in POD for a CPAN module?
by kcott (Archbishop) on May 28, 2017 at 05:48 UTC

G'day atcroft,

I agree with you: absolute URLs should not be used to link to the POD of related modules.

When I'm viewing a "See Also" section, and find a link to Some::Module, my expectations are that it's resolved something like the following (non-exhaustive list).

Source Site	Resolved Page
`http://perldoc.perl.org/`	`http://perldoc.perl.org/Some/Module.html`
`http://search.cpan.org/`	`http://search.cpan.org/perldoc?Some::Module`
`https://metacpan.org/`	`https://metacpan.org/pod/Some::Module`

A continuity of flow, from one piece of documentation to the next, is preferable to jumping from one site (and its format) to another site (with a different format). Apart from the actual site format, I also may have settings with personal preferences which could be lost (typically not any sort of major problem; just a nuisance I could do without).

The reasons are very to similar to why absolute URLs on this site are frowned upon. If I'm reading, for instance, a http://www.perlmonks.com/ node, and follow a hard-coded link to a http://perlmonks.net/ node, I'll probably find I'm no longer logged in and I've lost all of my personal preferences (settings).

The only time that I'd use an absolute URL in POD, would be for links to additional (non-POD) discussion of the topic, information about a non-Perl dependency, and the like.

— Ken

[reply]
[d/l]
[select]

Re: Is there a "standard" way to link to other modules in POD for a CPAN module?
by choroba (Cardinal) on May 28, 2017 at 07:32 UTC

Linking from POD

($q=q:Sq=~/;[c](.)(.)/;chr(-||-|5+lengthSq)`"S|oS2"`map{chr |+ord
}map{substrSq`S_+|`|}3E|-|`7**2-3:)=~y+S|`+$1,++print+eval$q,q,a,
[download]

[reply]
[d/l]

Re: Is there a "standard" way to link to other modules in POD for a CPAN module?
by LanX (Saint) on May 28, 2017 at 00:01 UTC

I don't remember the details but L<...> has some limitations. (Was it about including pictures? )

But I agree with Tobyink that this should always be avoided if possible.

Cheers Rolf
_{(addicted to the Perl Programming Language and ☆☆☆☆ :)

Je suis Charlie!}

[reply]
[d/l]