Bug#587991: perl-policy: /etc/perl missing from Module Path

[Russ Allbery <rra@debian.org>]

Dominic Hargreaves <dom@earth.li> writes:

> There are a couple of other things which use /etc/perl, from only a
> brief look at the perl debian/changelog (/etc/perl/CPAN and
> /etc/perl/CPANPLUS). Those files are created by a local administrator
> (using the tools shipped).

Here's what I currently have, which hopefully also addresses Bill's
concerns.  Does this look correct?

diff --git a/perl-policy.sgml b/perl-policy.sgml
index 626c514..0ef56f0 100644
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -128,17 +128,27 @@
       <sect id="paths">
 	<heading>Module Path</heading>
 	<p>
-	  Perl searches three different locations for modules, referred
-	  to in this document as <var>core</var> in which modules
-	  distributed with Perl are installed, <var>vendor</var> for
-	  packaged modules and <var>site</var> for modules installed by
-	  the local administrator.
+	  Perl searches four different locations for modules, referred to
+	  in this document as <var>config</var> for system configuration
+	  modules, <var>core</var> in which modules distributed with Perl
+	  are installed, <var>vendor</var> for packaged modules,
+	  and <var>site</var> for modules installed by the local
+	  administrator.
 	</p>
 	<p>
 	  The module search path (<tt>@INC</tt>) in the Debian packages
 	  has been ordered to include these locations in the following
 	  order:
 	  <taglist>
+	    <tag><var>config</var></tag>
+	    <item>
+	      <p>
+		Configuration modules (see <ref id="config_modules">).
+		<example>
+/etc/perl
+		</example>
+	      </p>
+	    </item>
 	    <tag><var>site</var> (current)</tag>
 	    <item>
 	      <p>
@@ -395,6 +405,43 @@ $(MAKE) install DESTDIR=$(CURDIR)/debian/&lt;tmp&gt;
 	  </p>
 	</sect1>
       </sect>
+
+      <sect id="config_files">
+	<heading>Configuration Files for Modules</heading>
+	<p>
+	  Debian Perl module packages that include configuration files are
+	  allowed (but not required) to put those configuration files
+	  under <file>/etc/perl</file>.  If this path is used for
+	  configuration files, the configuration file must be installed
+	  into a directory under <file>/etc/perl</file> named after the
+	  module, with <tt>::</tt> changed to <tt>/</tt> following the
+	  normal Perl rules for transforming Perl module names into paths.
+	</p>
+	<p>
+	  For example, a configuration file for the XML::SAX module would
+	  be installed in the directory <file>/etc/perl/XML/SAX</file>,
+	  and a configuration file used by multiple Net::* modules would
+	  be installed in the directory <file>/etc/perl/Net</file>.
+	</p>
+      </sect>
+
+      <sect id="config_modules">
+	<heading>Configuration Modules</heading>
+	<p>
+	  Some Perl packages load system-wide configuration from a
+	  dedicated Perl module whose purpose is solely to contain
+	  configuration settings.  The module often contains only variable
+	  settings.  Such modules should be treated as configuration files
+	  and installed under <file>/etc/perl</file>.
+	</p>
+	<p>
+	  Debian packages must not install regular modules in this path.
+	  It is reserved for configuration modules that follow the
+	  semantics of configuration files as defined by Debian Policy, or
+	  for configuration files for Perl modules as described
+	  in <ref id="config_files">.
+	</p>
+      </sect>
     </chapt>
 
     <chapt id="programs">

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