Bug#643690: perl policy unclear about the section for manpages
Steve Langasek <vorlon@debian.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:
> [...]
> Modules
> 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 (rra@debian.org) <http://www.eyrie.org/~eagle/>
>From f6938d47f9250f672586191cc00988e9e61cea06 Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.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
module packages.
---
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
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -197,8 +197,8 @@
package.
</p>
<p>
- 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:
<taglist>
<tag>Programs</tag>
<item>
@@ -217,6 +217,8 @@
</p>
</item>
</taglist>
+ The extensions used for manual pages distributed with module
+ packages are different. See <ref id="vendor_dirs">.
</p>
</sect>
</chapt>
--
1.7.7.3
Reply to: