In Perl POD, what is the proper way to link to an internal function?

Question

The perlpod documentation says you can L<link to something> but it does not indicate the proper way to reference a Perl-core function (or if it does, it wasn't obvious to me).

Specifically, I want to link to what is shown by perldoc -f wantarray. What is the proper way to L<...> link to it so it will take you to the wantarray documentation when you click on the link from MetaCPAN and other POD viewers that follow links?

(Note that wantarray is just a built-in Perl function like print or open.)

Answer 1

The best I find is to bring up the manual pages (perldoc) on CPAN

L<perlfunc/wantarray>

L<File::Find>

L<perlop>

L<perlsyn/"For Loops">

These bring up pages on CPAN: wantarray, File::Find, perlop, and "For Loops" in perlsyn. They are linked on their perldoc pages and seem to be exactly the same (except for the handy table of contents that perldoc pages may have). Or use L<wantarray|perlfunc/wantarray>, but try it as it stands first with its inferred link text.

Find the syntax for (possible) other kinds of pages by finding them on perldoc and using the link "CPAN" on top of their page.

These are tested and processed as described using CPAN's POD renderer (pod2html) since the question is about CPAN content.

If these CPAN hosted pages don't cut it then all I can see is to use the URL for perldoc pages.

---

Btw, UNIX man pages work right out of docs:

L<crontab(5)>

This brings up http://man.he.net/man5/crontab

Answer 2

One way is to use the full URL to the wantarray function:

L<wantarray|https://perldoc.perl.org/functions/wantarray>

---

The above works and you can easily try it out on the metacpan POD Renderer

Answer 3

It's in perlpod as the L<name/sec> form. perlpodspec has some more details.

For example, wantarray is the section in the perlfunc page name. You'd write L<perlfunc/wantarray>. If you want a Perl special variable $^V, you'd write L<perlvar/$^V>. You have to know where things are in the docs (and that's not always obvious).

Realize that the particular Pod processor will output some phrase, and you should account for that in your expected sentence. This is the phrase that comes out of Pod::Text:

"wantarray" in perlfunc

You want to take into account that extra "in perlfunc" that shows up.

There are other ways to link, though, as you've seen in the other answers.