From 0e58a7e67c225766da50544e54459e39172d18ee Mon Sep 17 00:00:00 2001
From: Ben Finney <ben+debian@benfinney.id.au>
Date: Fri, 6 Jan 2012 08:27:28 -0800
Subject: [PATCH] Recommend <package> documentation go in
 /usr/share/doc/<package>

Recommend that <package> documentation be installed into
/usr/share/doc/<package> even if it's packaged separately.

Closes: #106073
---
 policy.sgml | 44 ++++++++++++++++++++++++++++++++------------
 1 file changed, 32 insertions(+), 12 deletions(-)

diff --git a/policy.sgml b/policy.sgml
index a8afd41..d8e6efe 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -10662,16 +10662,17 @@ END-INFO-DIR-ENTRY
 	</p>
       </sect>
 
-      <sect>
+      <sect id="docs-additional">
 	<heading>Additional documentation</heading>
 
 	<p>
 	  Any additional documentation that comes with the package may
 	  be installed at the discretion of the package maintainer.
-	  Plain text documentation should be installed in the directory
-	  <file>/usr/share/doc/<var>package</var></file>, where
-	  <var>package</var> is the name of the package, and
-          compressed with <tt>gzip -9</tt> unless it is small.
+	</p>
+
+	<p>
+	  Plain text documentation should be compressed with <tt>gzip
+          -9</tt> unless it is small.
         </p>
 
 	<p>
@@ -10681,6 +10682,25 @@ END-INFO-DIR-ENTRY
 	  take up disk space on the machines of users who do not need
 	  or want it installed.</p>
 
+	<p>
+	  Additional documentation for <var>package</var>, whether the
+	  documentation is packaged separately or not, should be
+	  installed to the directory
+	  <file>/usr/share/doc/<var>package</var></file> or its
+	  subdirectories.<footnote>
+	      Rationale: Once installed, the separation of the
+	      documentation packaging should be invisible to the user,
+	      and the documentation should be found in the expected
+	      location for the main binary package.
+	  </footnote>
+	</p>
+
+	<p>
+	  Any separate package providing documentation must still
+	  install files as specified in the rest of this policy; for
+	  example, <ref id="copyrightfile"> and <ref id="changelogs">.
+	</p>
+
 	<p>
 	  It is often a good idea to put text information files
 	  (<file>README</file>s, changelogs, and so forth) that come with
@@ -10742,16 +10762,16 @@ END-INFO-DIR-ENTRY
 	  via HTML.</p>
 
 	<p>
-	  If your package comes with extensive documentation in a
+	  If the package comes with extensive documentation in a
 	  markup format that can be converted to various other formats
 	  you should if possible ship HTML versions in a binary
-	  package, in the directory
-	  <file>/usr/share/doc/<var>appropriate-package</var></file> or
-	  its subdirectories.<footnote>
-	      The rationale: The important thing here is that HTML
-	      docs should be available in <em>some</em> package, not
-	      necessarily in the main binary package.
+	  package.<footnote>
+	      Rationale: The important thing here is that HTML
+	      documentation should be available from <em>some</em>
+	      binary package.
 	  </footnote>
+	  The documentation must be installed as specified in
+	  <ref id="docs-additional">.
 	</p>
 
 	<p>
-- 
2.39.2