[doc] All man pages' SEE ALSO sections should have standard section numbers added

[jidanni]

Just the other day we were having an argument about if e.g.,

$ man perldoc

SEE ALSO
perlpod, Pod::Perldoc

should instead say

SEE ALSO
perlpod(1), Pod::Perldoc(3perl)

I.e., all perl man pages' SEE ALSO sections should have standard numbers attached to them,
like
$ man cat
has.

[Grinnz]

No, because these are meant to link to other perldocs, whereas links to manpage-style sections are handled differently.

[Leont]

No, because these are meant to link to other perldocs, whereas links to manpage-style sections are handled differently.

Yeah, the system isn't designed for this, sadly

[eserte]

A possible change would be the addition of manpage section identifications to all of the L<...> links. However this would change the type of such links, and some Pod renderers (like Tk::Pod) would do different things then.

But I think it should be possible to write a pod2man variant which does some heuristics to add manpage sections to links e.g. everything which "looks" like a perl module or can be found in @INC gets the (3) suffix (or on some systems (3pm) or so), otherwise a (1) suffix.

[Grinnz]

But I think it should be possible to write a pod2man variant which does some heuristics to add manpage sections to links e.g. everything which "looks" like a perl module or can be found in @INC gets the (3) suffix (or on some systems (3pm) or so), otherwise a (1) suffix.

Such would be possible but it could only be an imperfect heuristic, because of modules that look like "lib" or documentation like "perl".

[jidanni]

All I know is on Debian $ dlocate perldoc. perl-doc: /usr/share/man/man1/perldoc.1.gz perl-doc: /usr/share/perl/5.30.0/pod/perldoc.pod Maybe just the /usr/share/man/man*/*.gz files could have the standard section numbers added to them.

[Leont]

Maybe just the
/usr/share/man/man*/*.gz
files could have the standard section numbers added to them.

That sort of os/distribution specific logic sounds like a nightmare to maintain.

[Grinnz]

Maybe just the
/usr/share/man/man*/*.gz
files could have the standard section numbers added to them.

That sort of os/distribution specific logic sounds like a nightmare to maintain.

I would add, this would be something an OS distribution could patch in their packages if desired, and that would be the level at which you'd know the pertinent information of what section any particular link will be in.

[jidanni]

I would add, this would be something an OS distribution could patch in their packages if desired

Great. However please tell them for me. I think I sent too much stuff to them. https://bugs.debian.org/cgi-bin/pkgreport.cgi?ordering=raw;package=perl-doc;submitter=jidanni%40jidanni.org

[Leont]

All I know is on Debian
$ dlocate perldoc.
perl-doc: /usr/share/man/man1/perldoc.1.gz
perl-doc: /usr/share/perl/5.30.0/pod/perldoc.pod

A major problem with this logic, is that it assumes the module/script that is referred to is installed on the machine that builds the package. This is not a safe assumption.