(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/>
