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