package debian-policy retitle 106073 recommend to install additional documentation into /usr/share/doc/<package>/ tags 106073 + patch thanks
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 <b...@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 <r...@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 (3.9.1.0) 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 @@
</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>
@@ -9464,6 +9465,25 @@
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
the source package in <file>/usr/share/doc/<var>package</var></file>
@@ -9524,16 +9544,16 @@
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>
signature.asc
Description: Digital signature
