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

diff --git a/policy.sgml b/policy.sgml
index a8afd4188e635c9ffe98ca863f0c6b4121302a40..d8e6efe5b6ea5327375c1ea99050e11677bbd4e1 100644 (file)
--- 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>