1

Consider this module App::TimeTracker. If you click on the tracker link in the SYNOPSIS section you end up here whereas you should have ended up here. The Pod source code responsible for the behavior is given here, which shows that the following Pod formatting code was used:

L<tracker>

I can fix the problem by providing an absolute link instead:

L<tracker|https://metacpan.org/pod/release/DOMM/App-TimeTracker-3.000/bin/tracker>

but this fixes the link to version 3.000 which may change in the future.

So how should this be done in general?

Jonas
  • 121,568
  • 97
  • 310
  • 388
Håkon Hægland
  • 39,012
  • 21
  • 81
  • 174
  • `https://metacpan.org/release/App-TimeTracker/source/bin/tracker` maybe? – choroba Nov 01 '19 at 14:25
  • Hi @choroba, thanks for the suggestion, but it [shows](https://metacpan.org/release/App-TimeTracker/source/bin/tracker) the source code of the script not the Pod documentation – Håkon Hægland Nov 01 '19 at 14:31
  • 1
    So https://metacpan.org/pod/distribution/App-TimeTracker/bin/tracker ? – choroba Nov 01 '19 at 14:38
  • @choroba Yes this works I think :) – Håkon Hægland Nov 01 '19 at 14:52
  • 1
    1) If you're linking within a distribution, you *should* be linking to a specific version. It makes no sense for the local documentation to be for a different version than the one installed. 2) This is an XY problem. The real problem is the creation of two pods with the same name. Fix that, and continue using `L`. – ikegami Nov 01 '19 at 18:03
  • @ikegami Thanks for the comment. I am not sure I understand: *"The real problem is the creation of two pods with the same name"* which two pods did you mean? – Håkon Hægland Nov 01 '19 at 18:14
  • 1
    https://i.stack.imgur.com/u6iT6.png If only the second doc existed, surely it would link to it? – ikegami Nov 01 '19 at 18:22
  • @ikegami Yes, but why did the two files get the same pod name? These two files: [tracker](https://metacpan.org/source/DOMM/App-TimeTracker-3.001/bin/tracker) and [tracker_bash_autocomplete](https://metacpan.org/source/DOMM/App-TimeTracker-3.001/bin/tracker_bash_autocomplete). Is it a bug in metacpan.org or in the source distribution? – Håkon Hægland Nov 01 '19 at 18:44
  • I"m not sure why there are two. I looked a little bit earlier, but nothing jumped out at me. – ikegami Nov 01 '19 at 19:46

2 Answers2

3

Use the full path without the version number: https://metacpan.org/pod/distribution/App-TimeTracker/bin/tracker.

choroba
  • 231,213
  • 25
  • 204
  • 289
  • 1
    This makes no sense! Don't make the local documentation point to something other than the local version. It's bad enough that you require switching from `man`/`perldoc` to a web browser; at least link to the right version. – ikegami Nov 01 '19 at 18:05
  • @ikegami: Links don't work in my local version of `man` / `perldoc`. – choroba Nov 01 '19 at 19:10
  • I have to agree with @ikegami - MetaCPAN has logic to link within the same release of the distribution, but using the full "versionless" link bypasses this ability and will cause the reader to unexpectedly jump versions. – Grinnz Nov 01 '19 at 21:30
  • @choroba, Which brings up an even bigger problem: `man tracker` and `perldoc tracker` bring up the wrong page. This is particularly bad because you see a link named "tracker". – ikegami Nov 01 '19 at 21:37
2

The problem is that tracker_bash_autocomplete is not being indexed correctly as documentation by MetaCPAN. The NAME section has a very specific format based on manpages which must be adhered to for MetaCPAN to know how to link to your documentation. Putting tracker bash autocomplete before the hyphen makes MetaCPAN index it as tracker.

=head1 NAME

tracker_bash_autocomplete - whatever
Grinnz
  • 9,093
  • 11
  • 18
  • So spaces are not allowed in the string before the hyphen? – Håkon Hægland Nov 01 '19 at 21:35
  • 1
    It's not specifically documented by perlpodstyle or man(7) but I believe this is the case (for each single program). Programs are separated by both a comma and a space. – Grinnz Nov 01 '19 at 21:37