Bug#106073: recommend to install <package> documentation into /usr/share/doc/<package>/

[Russ Allbery <rra@debian.org>]

As always, once I start seriously poking at an area of Policy, I see other
little things that need to be fixed as well.  Here is a general overhaul
of the additional documentation section, which should both address this
bug as well as a few other things.

The changes here are:

* Shared library documentation is called out as a special case of the
  general rule that documentation should be packaged separately if it's
  large, recommending installing documentation of any appreciable size in
  the development package or a separate documentation package rather than
  the shared library package.

* The naming convention for documentation packages (package-doc or
  package-doc-language) is explicitly stated (but is not a requirement).

* package-doc is allowed to put documentation in either
  /usr/share/doc/package or /usr/share/doc/package-doc, but the former is
  preferred.  package-doc still has to install its own mandatory
  documentation files (changelog, copyright) in
  /usr/share/doc/package-doc.

* The paragraph about /usr/doc is removed.

* Some reorganization and wording tweaks to hopefully make things clearer.

Discussion, objections, seconds?

diff --git a/policy.sgml b/policy.sgml
index c1ff4b4..0b034c8 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -9702,45 +9702,77 @@ 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>
+	  Any additional documentation that comes with the package may be
+	  installed at the discretion of the package maintainer.  It is
+	  often a good idea to include text information files
+	  (<file>README</file>s, <file>TODO</file>s, and so forth) that
+	  come with the source package in the binary package.  However,
+	  you don't need to install the instructions for building and
+	  installing the package, of course!
+	</p>
 
 	<p>
-	  If a package comes with large amounts of documentation which
-	  many users of the package will not require you should create
-	  a separate binary package to contain it, so that it does not
-	  take up disk space on the machines of users who do not need
-	  or want it installed.</p>
+	  Plain text documentation should be compressed with <tt>gzip
+	  -9</tt> unless it is small.
+	</p>
 
 	<p>
-	  It is often a good idea to put text information files
-	  (<file>README</file>s, changelogs, and so forth) that come with
-	  the source package in <file>/usr/share/doc/<var>package</var></file>
-	  in the binary package.  However, you don't need to install
-	  the instructions for building and installing the package, of
-	  course!</p>
+	  If a package comes with large amounts of documentation that many
+	  users of the package will not require, you should create a
+	  separate binary package to contain it so that it does not take
+	  up disk space on the machines of users who do not need or want
+	  it installed.  As a special case of this rule, shared library
+	  documentation of any appreciable size should always be packaged
+	  with the library development package (<ref id="sharedlibs-dev">)
+	  or in a separate documentation package, since shared libraries
+	  are frequently installed as dependencies of other packages by
+	  users who have little interest in documentation of the library
+	  itself.  The documentation package for the
+	  package <var>package</var> is conventionally
+	  named <var>package</var>-doc
+	  (or <var>package</var>-doc-<var>language-code</var> if there are
+	  separate documentation packages for multiple languages).
+	</p>
+
+	<p>
+	  Additional documentation included in the package must be
+	  installed under <file>/usr/share/doc/<var>package</var></file>.
+	  If the documentation is packaged separately,
+	  as <var>package</var>-doc for example, it may be installed under
+	  either that path or into the documentation directory for the
+	  separate documentation package
+	  (<file>/usr/share/doc/<var>package</var>-doc</file> in this
+	  example).  However, installing the documentation into the
+	  documentation directory of the main package is preferred since
+	  it is independent of the packaging method and will be easier for
+	  users to find.
+	</p>
+
+	<p>
+	  Any separate package providing documentation must still install
+	  standard documentation files in its
+	  own <file>/usr/share/doc</file> directory as specified in the
+	  rest of this policy.  See, for example, <ref id="copyrightfile">
+	  and <ref id="changelogs">.
+	</p>
 
 	<p>
 	  Packages must not require the existence of any files in
 	  <file>/usr/share/doc/</file> in order to function
 	  <footnote>
-	      The system administrator should be able to
-	      delete files in <file>/usr/share/doc/</file> without causing
-	      any programs to break.
-	  </footnote>.
-	  Any files that are referenced by programs but are also
-	  useful as stand alone documentation should be installed under
-	  <file>/usr/share/<var>package</var>/</file> with symbolic links from
-	  <file>/usr/share/doc/<var>package</var></file>.
+	    The system administrator should be able to delete files
+	    in <file>/usr/share/doc/</file> without causing any programs
+	    to break.
+	  </footnote>.  Any files that are referenced by programs but are
+	  also useful as stand alone documentation should be installed
+	  elsewhere, normally
+	  under <file>/usr/share/<var>package</var>/</file>, and then
+	  included via symbolic links
+	  in <file>/usr/share/doc/<var>package</var></file>.
 	</p>
 
 	<p>
@@ -9760,18 +9792,6 @@ END-INFO-DIR-ENTRY
             </p>
           </footnote>
 	</p>
-
-	<p>
-	  Former Debian releases placed all additional documentation
-	  in <file>/usr/doc/<var>package</var></file>.  This has been
-	  changed to <file>/usr/share/doc/<var>package</var></file>,
-	  and packages must not put documentation in the directory
-	  <file>/usr/doc/<var>package</var></file>. <footnote>
-	    At this phase of the transition, we no longer require a
-	    symbolic link in <file>/usr/doc/</file>. At a later point,
-	    policy shall change to make the symbolic links a bug.
-	  </footnote>
-	</p>
       </sect>
 
       <sect>
@@ -9782,16 +9802,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>

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