Handling of L<Module> in Pod::Man

(I'm subscribed to pod-people but not perl5-porters.)

Historically, Pod::Man renders L<Module> or L<perlpod> as just "Module" or
"perlpod" in the document (replacing the very historical rendering as "the
Module manpage", which caused various issues).  I've received a request
(CPAN RT #43700) to change that rendering to Module(3) since some man
programs do something useful with the cross-reference.

I'm not entirely sure whether I should do this or not.

The main problem that occurs to me is how to handle L<warnings>,
L<perlrun>, and L<xsubpp>.  L<Some::Module> obviously can be usefully
translated to Some::Module(3), but what to do with L<> content that
contains no :: or capital letters (all of which is probably section 3) is
harder.  I could apply a heuristic saying that anything starting with
/^perl/ and in all lowercase should be section 1, and otherwise use
section 3, which would get L<warnings> and L<perlrun> right, but I would
still fail on L<xsubpp>.

I could also push back on the bug reporter and say that POD authors who
want the man page reference need to include the section number in the L<>
text (L<Some::Module(3)> instead of L<Some::Module>), but that isn't what
perlpod says to do.

I could just bail and keep doing what I'm doing now and not add a section
number.

I could try to maintain a table of Perl programs that should get section 1
references and put everything else in section 3, on the grounds that
perlpod says that L<foo> is a link to a *Perl* man page, so people using
it to reference man pages for other things probably shouldn't.  However,
this doesn't help when referencing programs provided by other modules.

Pod::Man doesn't have any global state or knowledge from which it can
figure out what a particular reference is supposed to be to.

Does anyone have opinions about what I should do?

-- 
Russ Allbery ([email protected])             <http://www.eyrie.org/~eagle/>