Debian Bug report logs - #483834
debian-policy: contradiction how to name man pages in perl-policy

version graph

Package: debian-policy; Maintainer for debian-policy is Debian Policy List <debian-policy@lists.debian.org>; Source for debian-policy is src:debian-policy.

Reported by: Ansgar Burchardt <ansgar@2008.43-1.org>

Date: Sat, 31 May 2008 14:06:22 UTC

Severity: minor

Found in version debian-policy/3.7.3.0

Done: Russ Allbery <rra@debian.org>

Bug is archived. No further changes may be made.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#483834; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Ansgar Burchardt <ansgar@2008.43-1.org>:
New Bug report received and forwarded. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Ansgar Burchardt <ansgar@2008.43-1.org>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: debian-policy: contradiction how to name man pages in perl-policy
Date: Sat, 31 May 2008 15:26:28 +0200
Package: debian-policy
Version: 3.7.3.0
Severity: normal

Hi,

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.

A quick survey for the packages installed on my system shows that .3pm
and .1 seem to be more popular:

    *.3perl       -  495
    *.3pm         - 1697
    *.1p          -   33
    perl programs -  270

Regards,
Ansgar




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#483834; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #10 received at 483834@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Ansgar Burchardt <ansgar@2008.43-1.org>
Cc: 483834@bugs.debian.org, debian-perl@lists.debian.org
Subject: Re: debian-policy: contradiction how to name man pages in perl-policy
Date: Mon, 02 Jun 2008 13:22:24 -0700
Ansgar Burchardt <ansgar@2008.43-1.org> writes:

> Package: debian-policy
> Version: 3.7.3.0
> Severity: normal
>
> 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?

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.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Severity set to `minor' from `normal' Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Mon, 02 Jun 2008 20:24:04 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#483834; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to "Martín Ferrari" <martin.ferrari@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #17 received at 483834@bugs.debian.org (full text, mbox):

From: "Martín Ferrari" <martin.ferrari@gmail.com>
To: "Russ Allbery" <rra@debian.org>
Cc: "Ansgar Burchardt" <ansgar@2008.43-1.org>, 483834@bugs.debian.org, debian-perl@lists.debian.org
Subject: Re: debian-policy: contradiction how to name man pages in perl-policy
Date: Tue, 3 Jun 2008 06:27:30 -0300
On Mon, Jun 2, 2008 at 5:22 PM, Russ Allbery <rra@debian.org> wrote:

> 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?

It seems that we're almost OK there, sorry for the ugly oneliner:

$ zgrep usr/share/man/man1
/var/cache/apt/apt-file/ftp.ccc.uba.ar_pub_linux_debian_debian_dists_sid_Contents-i386.gz
| perl -e 'while(<>) { m#^(\S+)\s+[^/]*/(\S+)# or next; ($file, $pkg)
= ($1, $2); next if($file =~ /\.1p(\.gz)?$/); $files{$pkg} ||= [];
push @{$files{$pkg}}, $file } @pkgs = `grep-aptavail -P -r lib.*perl
-o -FMaintainer,Uploader perl -sPackage -n`; chomp @pkgs;
foreach(@pkgs) { next unless($files{$_}); foreach $file
(@{$files{$_}}) { print "$_: $file\n" } } '
dh-make-perl: usr/share/man/man1/dh-make-perl.1.gz
gpodder: usr/share/man/man1/gpodder.1.gz
libarchive-zip-perl: usr/share/man/man1/crc32.1.gz
libcarp-datum-perl: usr/share/man/man1/datum_strip.1.gz
libcddb-get-perl: usr/share/man/man1/cddbget.1.gz
libfile-scan-perl: usr/share/man/man1/update-libfile-scan-perl.1.gz
libpod-spell-perl: usr/share/man/man1/podspell.1.gz
libppi-html-perl: usr/share/man/man1/ppi2html.1.gz
libprima-perl: usr/share/man/man1/prima-VB.1.gz
libprima-perl: usr/share/man/man1/prima-cfgmaint.1.gz
libprima-perl: usr/share/man/man1/prima-gencls.1.gz
libprima-perl: usr/share/man/man1/prima-tmlink.1.gz
libqt-perl: usr/share/man/man1/pqtapi.1.gz
libqt-perl: usr/share/man/man1/pqtsh.1.gz
libqt-perl: usr/share/man/man1/puic.1.gz
libsyntax-highlight-perl-improved-perl: usr/share/man/man1/viewperl.1.gz
libtheschwartz-perl: usr/share/man/man1/schwartzmon.1.gz
libvcs-lite-perl: usr/share/man/man1/vldiff.1.gz
libvcs-lite-perl: usr/share/man/man1/vlmerge.1.gz
libvcs-lite-perl: usr/share/man/man1/vlpatch.1.gz
weblint-perl: usr/share/man/man1/weblint.1.gz



-- 
Martín Ferrari




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#483834; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #22 received at 483834@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Martín Ferrari <martin.ferrari@gmail.com>
Cc: 483834@bugs.debian.org, "Ansgar Burchardt" <ansgar@2008.43-1.org>, debian-perl@lists.debian.org
Subject: Re: Bug#483834: debian-policy: contradiction how to name man pages in perl-policy
Date: Tue, 03 Jun 2008 10:05:20 -0700
"\"Martín" Ferrari" <martin.ferrari@gmail.com> writes:
> On Mon, Jun 2, 2008 at 5:22 PM, Russ Allbery <rra@debian.org> wrote:

>> 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?

> It seems that we're almost OK there, sorry for the ugly oneliner:

Do people feel like that policy is correct and the programs that aren't
following it are just bugs?  (Except for dh-make-perl and other things
that aren't modules.)

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#483834; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to "Martín Ferrari" <martin.ferrari@gmail.com>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #27 received at 483834@bugs.debian.org (full text, mbox):

From: "Martín Ferrari" <martin.ferrari@gmail.com>
To: "Russ Allbery" <rra@debian.org>
Cc: 483834@bugs.debian.org, "Ansgar Burchardt" <ansgar@2008.43-1.org>, debian-perl@lists.debian.org
Subject: Re: Bug#483834: debian-policy: contradiction how to name man pages in perl-policy
Date: Tue, 3 Jun 2008 14:07:20 -0300
On Tue, Jun 3, 2008 at 2:05 PM, Russ Allbery <rra@debian.org> wrote:

> Do people feel like that policy is correct and the programs that aren't
> following it are just bugs?  (Except for dh-make-perl and other things
> that aren't modules.)

Seems so, although doesn't seem like very important bugs.


-- 
Martín Ferrari




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#483834; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to "Brendan O'Dea" <bod@c47.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #32 received at 483834@bugs.debian.org (full text, mbox):

From: "Brendan O'Dea" <bod@c47.org>
To: "Russ Allbery" <rra@debian.org>
Cc: "Ansgar Burchardt" <ansgar@2008.43-1.org>, 483834@bugs.debian.org, debian-perl@lists.debian.org
Subject: Re: debian-policy: contradiction how to name man pages in perl-policy
Date: Wed, 4 Jun 2008 22:06:10 +1000
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 sent to Russ Allbery <rra@debian.org>:
You have taken responsibility. Full text and rfc822 format available.

Notification sent to Ansgar Burchardt <ansgar@2008.43-1.org>:
Bug acknowledged by developer. Full text and rfc822 format available.

Message #37 received at 483834-done@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: 483834-done@bugs.debian.org, "Ansgar Burchardt" <ansgar@2008.43-1.org>, debian-perl@lists.debian.org
Subject: Re: Bug#483834: debian-policy: contradiction how to name man pages in perl-policy
Date: Wed, 04 Jun 2008 09:53:51 -0700
"Brendan O'Dea" <bod@c47.org> writes:
> On Tue, Jun 3, 2008 at 6:22 AM, Russ Allbery <rra@debian.org> wrote:

>> 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.

Okay, I think we've all decided what Policy says is correct.  If anyone
wants to propose a different way of wording it, it's probably better to
file a new bug with a specific wording proposal so that we can hash out if
it's clearer.  In the meantime, I'm going to go ahead and close this one.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Thu, 03 Jul 2008 07:31:09 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Sun Apr 20 21:32:43 2014; Machine Name: buxtehude.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.