Re: Bug#643690: perl policy unclear about the section for manpages
Steve Langasek <firstname.lastname@example.org> writes:
> The perl policy makes confusing statements about the section that manpages
> should be installed in:
> 2.4. Documentation
> Manual pages distributed with Perl packages must be installed into the
> standard directories:
> Manual pages for modules are installed into `/usr/share/man/man3'
> with the extension `.3perl'.
> I apparently misread this long ago and assumed that "manual pages for
> modules" was talking about all modules rather than just those from the
> perl source package. Only a recent lintian warning, showing me that
> MakeMaker has output the manpage with a .TH that doesn't match the
> filename, clued me in.
> I think the language in 2.4 should be clarified to explicitly state this
> only applies to modules from the perl source package.
Yes, this tripped me up too. Here's a proposed patch. Seconds or further
discussion? I'll copy debian-perl as well for further review.
Russ Allbery (email@example.com) <http://www.eyrie.org/~eagle/>
>From f6938d47f9250f672586191cc00988e9e61cea06 Mon Sep 17 00:00:00 2001
From: Russ Allbery <firstname.lastname@example.org>
Date: Sat, 24 Dec 2011 11:03:49 -0800
Subject: [PATCH] Clarify the Perl policy documentation rules
The first section about documentation and manual page extensions
only applies to packages generated from the perl source package.
Make that explicit and add a reference to the section discussing
perl-policy.sgml | 6 ++++--
1 files changed, 4 insertions(+), 2 deletions(-)
diff --git a/perl-policy.sgml b/perl-policy.sgml
index 70c5bfc..626c514 100644
@@ -197,8 +197,8 @@
- Manual pages distributed with Perl packages must be installed
- into the standard directories:
+ Manual pages distributed with packages built from the perl
+ source package must be installed into the standard directories:
@@ -217,6 +217,8 @@
+ The extensions used for manual pages distributed with module
+ packages are different. See <ref id="vendor_dirs">.