Bug#483834: debian-policy: contradiction how to name man pages in perl-policy
On Tue, Jun 3, 2008 at 6:22 AM, Russ Allbery <rra@debian.org> wrote:
> Ansgar Burchardt <ansgar@2008.43-1.org> writes:
>> there is a contradiction how to name man pages for perl modules.
>> Section 4.1 states
>>
>> Module packages must install manual pages into the standard
>> directories (see Documentation, Section 2.4) using the extensions
>> .1p and .3pm to ensure that no conflict arises where a packaged
>> module duplicates a core module.
>>
>> while section 2.4 states
>>
>> Manual pages distributed with Perl packages must be installed into
>> the standard directories:
>> Programs
>> Manual pages for programs and scripts are installed into
>> /usr/share/man/man1 with the extension .1.
>> Modules
>> Manual pages for modules are installed into /usr/share/man/man3
>> with the extension .3perl.
>
> This is consistent. I think you just missed that section 2.4 is talking
> about the behavior of the Perl packages themselves (in other words, perl,
> perl-base, and perl-modules), whereas section 4.1 is talking about other
> packages of Perl modules. The man pages that ship with the core Perl
> packages use .3perl and the man pages that ship with other packages use
> .3pm, following this standard.
>
> I'm not sure, however, that the .1p recommendation is followed. Perl
> folks, could you check? Is that really current policy and are we
> following it?
The rationale for this requirement is that since both packaged modules
and the core perl packages install manual pages to /usr/share/man,
using different extensions removes unnecessary conflicts which would
otherwise prevent modules being installed.
@Config{qw/man1ext man3ext/} are set appropriately for packaged
modules on Debian systems, and both ExtUtils::MakeMaker (perl-modules)
and Module::Build (libmodule-build-perl) use these values. As a
result, I'd be surprised if there were very many packages in violation
of this requirement.
> Assuming that we are, I think there isn't a bug here, although if other
> people find this section confusing, maybe we should find a way to
> rephrase to make it clearer which packages are being talked about in each
> section.
I believe that the wording is sufficiently clear.
Reply to: