Perl policy vs. the search order for .1{,p} manpages

[Niko Tyni <ntyni@debian.org>]

Hi debian-perl and Colin (the man-db maintainer),

while looking at how to handle /usr/bin/corelist, which is shipped in both
libmodule-corelist-perl and the perl package starting at 5.10.0 (#471516),
I noticed a problem in the Perl policy wrt. man page search order.

While manpages for separately packaged modules (.3pm) are preferred
over those bundled with the Perl core (.3perl), this is not the case
for separately packaged scripts (.1p) vs. bundled ones (.1).

This is a real problem with libmodule-corelist-perl and perl 5.10.0:
with both installed, 'man corelist' gives the older manual which
doesn't document the new '-d' option. Explicitly asking for the newer
one with eg. 'man -S 1p corelist' works fine, of course.

The order is apparently determined in man-db debian/rules:

 ./configure --with-sections='1 n l 8 3 2 3posix 3pm 3perl 5 4 9 6 7'

Indeed, if I prepend 1p to the section list in /etc/manpath.config, I
get the desired behaviour.

I see three ways to fix this: 

- put 1p first in the man-db configuration, which seems a bit invasive

- make libmodule-corelist-perl divert /usr/share/man/man1/corelist.1.gz,
  violating the Perl policy

- change the policy and the perl packaging to put the program manuals 
  in eg. section 1perl, and add '1p 1perl' in the man-db configuration

Why was section 1 chosen in the Perl policy in the first place?
Is there a reason why '1perl' wouldn't work?

Cheers,
-- 
Niko Tyni   ntyni@debian.org