On Sat, Jan 07, 2012 at 08:51:58AM -0800, Russ Allbery wrote: > Russ Allbery <rra@debian.org> writes: > > > 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. > > [...] > > Here is an updated version of the patch with feedback to date taken into > account. > > diff --git a/policy.sgml b/policy.sgml > index c1ff4b4..4dce37c 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, FAQs, 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 should 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 used or read by programs but > + are also useful as stand alone documentation should be installed > + elsewhere, such as > + 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> Seconded. I suggest we move forward with this and that I apply it to master next week, if Russ is still OK with this. Cheers, -- Bill. <ballombe@debian.org> Imagine a large red swirl here.
Attachment:
signature.asc
Description: Digital signature