X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=perl-policy.sgml;h=54e97d36bef4c03ba4b653064f1b5ca482603400;hb=a455d2387d8ef592eca042366eed6247ab0d587d;hp=7c3744647f5dff6dd94e0fefd8040937c33ecf8c;hpb=0d65a4ba82455a61736b541944a081c63ed60b13;p=debian%2Fdebian-policy.git

diff --git a/perl-policy.sgml b/perl-policy.sgml
index 7c37446..54e97d3 100644
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -22,7 +22,7 @@
 
       <abstract>
 	This document describes the packaging of Perl within the Debian
-	GNU/Linux distribution and the policy requirements for packaged
+	distribution and the policy requirements for packaged
 	Perl programs and modules.
       </abstract>
 
@@ -44,7 +44,7 @@
 	</p>
 	<p>
 	  A copy of the GNU General Public License is available as
-	  <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
+	  <tt>/usr/share/common-licenses/GPL</tt> in the Debian
 	  distribution or on the World Wide Web at 
 	  <url id="http://www.gnu.org/copyleft/gpl.html"
 	  name="The GNU Public Licence">.
@@ -96,7 +96,8 @@
 	  <package>perlapi-<var>abiname</var></package> for all released
 	  package versions it is compatible with. The choice of
 	  <var>abiname</var> is arbitrary, but if it differs from
-	  <tt>$Config{version}</tt>, it must be specified in
+	  <tt>$Config{version}</tt><footnote>see the
+	  <tt>Config</tt> module</footnote>, it must be specified in
 	  <tt>$Config{debian_abi}</tt>.
 	</p>
       </sect>
@@ -149,8 +150,7 @@
 /usr/local/share/perl/<var>version</var>
 		</example>
 		Where <var>version</var> indicates the current Perl
-		version (<tt>$Config{version}</tt><footnote>see the
-		<tt>Config</tt> module</footnote>).
+		version (<tt>$Config{version}</tt>).
 	      </p>
 	    </item>
 	    <tag><var>vendor</var></tag>
@@ -168,9 +168,11 @@
 	      <p>
 		Modules included in the core Perl distribution.
 	        <example>
-/usr/lib/perl/<var>version</var>
-/usr/share/perl/<var>version</var>
+/usr/lib/perl/<var>shortversion</var>
+/usr/share/perl/<var>shortversion</var>
 	        </example>
+		Where <var>shortversion</var> indicates the current Perl major
+		version (for example <tt>5.18</tt>).
 	      </p>
 	    </item>
 	    <tag><var>site</var> (old)</tag>
@@ -197,8 +199,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 +219,8 @@
 	      </p>
 	    </item>
 	  </taglist>
+	  The extensions used for manual pages distributed with module
+	  packages are different.  See <ref id="vendor_dirs">.
 	</p>
       </sect>
     </chapt>
@@ -298,10 +302,17 @@ make install
 	<heading>Module Package Names</heading>
 	<p>
 	  Perl module packages should be named for the primary module
-	  provided.  The naming convention for module <tt>Foo::Bar</tt>
-	  is <package>libfoo-bar-perl</package>.  Packages which include
-	  multiple modules may additionally include provides for those
-	  modules using the same convention.
+	  provided.  The naming convention is to lowercase the Perl module
+	  name, prepend, <tt>lib</tt>, change all occurrences
+	  of <tt>::</tt> to <tt>-</tt>, and append <tt>-perl</tt>.  For
+	  example:
+	  <example>
+Foo::Bar        libfoo-bar-perl
+Foo::Bar::Baz   libfoo-bar-baz-perl
+Foo::BarBaz     libfoo-barbaz-perl
+	  </example>
+	  Packages which include multiple modules may additionally include
+	  provides for the additional modules using the same convention.
 	</p>
       </sect>
 
@@ -454,6 +465,26 @@ perl -MExtUtils::Embed -e ldopts
 	  package must depend upon it explicitly.
 	</p>
       </sect>
+
+      <sect id="perl_upgrades">
+        <heading>Perl Package Upgrades</heading>
+        <p>
+          Starting from <package>perl</package> 5.12.3-2, a dpkg trigger
+          named <var>perl-major-upgrade</var> will be triggered by the
+          postinst of the <package>perl</package> package during major
+          upgrades. Some examples of things which constitute a major upgrade
+          are an upgrade which would change the value of versioned
+          directories in <tt>@INC</tt>, or one which changes <tt>abiname</tt>.
+          Any package may declare an interest in the trigger, especially
+          packages including long-running daemons which would stop working
+          until restart.
+        </p>
+        <p>
+          It is suggested that such packages include an appropriate section
+          in their postinst to handle the trigger by restarting relevant
+          daemons or notifying users of further action.
+        </p>
+      </sect>
     </chapt>
 
     <appendix id="perl6">