[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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

package debian-policy
retitle 106073 recommend to install additional documentation into /usr/share/doc/<package>/
tags 106073 + patch

On 27-Sep-2003, Josip Rodin wrote:
> Some proposed mandating that -doc package contents is placed into
> /usr/share/doc/<package>/, and that the administrivia such as
> copyright and changelog stays in /usr/share/doc/<package>-doc/. This
> sounds good to me because it has a sort of an internal logic, the
> -doc suffix only exists because of packaging, it's actually the docs
> for <package>. Plus, it's shorter, less to type.

There seems to be consensus on doing this, so I've made a patch
(attached to this message) which implements that recommendation.

 \      “We are stuck with technology when what we really want is just |
  `\                                 stuff that works.” —Douglas Adams |
_o__)                                                                  |
Ben Finney <ben@benfinney.id.au>
=== modified file 'debian/changelog'
--- debian/changelog	2010-08-18 20:55:34 +0000
+++ debian/changelog	2010-08-25 03:28:19 +0000
@@ -16,7 +16,12 @@
     paragraph discussing non-interactivity, and explicitly mark all rules
     as either required or optional.  (Closes: #536790)
- -- Russ Allbery <rra@debian.org>  Thu, 12 Aug 2010 10:47:47 -0700
+  [ Ben Finney ]
+  * Be explicit about where additional documentation should be installed.
+    (Closes: Bug#106073)
+ --
 debian-policy ( unstable; urgency=low

=== modified file 'policy.sgml'
--- policy.sgml	2010-08-18 20:55:34 +0000
+++ policy.sgml	2010-08-25 03:23:50 +0000
@@ -9444,16 +9444,17 @@
-      <sect>
+      <sect id="docs-additional">
 	<heading>Additional documentation</heading>
 	  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.
@@ -9464,6 +9465,25 @@
 	  or want it installed.</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
 	  the source package in <file>/usr/share/doc/<var>package</var></file>
@@ -9524,16 +9544,16 @@
 	  via HTML.</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.
+	  The documentation must be installed as specified in
+	  <ref id="docs-additional">.

Attachment: signature.asc
Description: Digital signature

Reply to: