From 62e9a6ad9814d0493e9306c0095fec338cea0075 Mon Sep 17 00:00:00 2001
From: Russ Allbery
Date: Fri, 6 Jan 2012 09:12:20 -0800
Subject: [PATCH] Further overhaul of the additional documentation section
Building on top of Ben's patch, this includes the following changes:
* 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.
---
policy.sgml | 100 ++++++++++++++++++++++++++--------------------------
1 file changed, 50 insertions(+), 50 deletions(-)
diff --git a/policy.sgml b/policy.sgml
index d8e6efe..7afd0fa 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -10666,61 +10666,73 @@ END-INFO-DIR-ENTRY
Additional documentation
- Any additional documentation that comes with the package may
- be installed at the discretion of the package maintainer.
+ 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
+ (READMEs, TODOs, 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!
Plain text documentation should be compressed with gzip
- -9 unless it is small.
-
-
-
- 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.
+ -9 unless it is small.
+
- Additional documentation for package, whether the
- documentation is packaged separately or not, should be
- installed to the directory
- /usr/share/doc/package or its
- subdirectories.
- 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.
-
+ 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 ([)
+ 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 package is conventionally
+ named package-doc
+ (or package-doc-language-code if there are
+ separate documentation packages for multiple languages).
]
- Any separate package providing documentation must still
- install files as specified in the rest of this policy; for
- example, [ and ][.
+ Additional documentation included in the package must be
+ installed under /usr/share/doc/package.
+ If the documentation is packaged separately,
+ as package-doc for example, it may be installed under
+ either that path or into the documentation directory for the
+ separate documentation package
+ (/usr/share/doc/package-doc 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.
]
- It is often a good idea to put text information files
- (READMEs, changelogs, and so forth) that come with
- the source package in /usr/share/doc/package
- in the binary package. However, you don't need to install
- the instructions for building and installing the package, of
- course!
+ Any separate package providing documentation must still install
+ standard documentation files in its
+ own /usr/share/doc directory as specified in the
+ rest of this policy. See, for example, [
+ and ][.
+
]
Packages must not require the existence of any files in
/usr/share/doc/ in order to function
- The system administrator should be able to
- delete files in /usr/share/doc/ without causing
- any programs to break.
- .
- Any files that are referenced by programs but are also
- useful as stand alone documentation should be installed under
- /usr/share/package/ with symbolic links from
- /usr/share/doc/package.
+ The system administrator should be able to delete files
+ in /usr/share/doc/ without causing any programs
+ to break.
+ . Any files that are referenced by programs but are
+ also useful as stand alone documentation should be installed
+ elsewhere, normally
+ under /usr/share/package/, and then
+ included via symbolic links
+ in /usr/share/doc/package.
@@ -10740,18 +10752,6 @@ END-INFO-DIR-ENTRY
-
-
- Former Debian releases placed all additional documentation
- in /usr/doc/package. This has been
- changed to /usr/share/doc/package,
- and packages must not put documentation in the directory
- /usr/doc/package.
- At this phase of the transition, we no longer require a
- symbolic link in /usr/doc/. At a later point,
- policy shall change to make the symbolic links a bug.
-
-
--
2.39.2