[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: 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: