Additional documentation
- 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
- /usr/share/doc/package, where
- package is the name of the package, and
- compressed with gzip -9 unless it is small.
-
+ 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, 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!
+
- 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.
+ Plain text documentation should be compressed with gzip
+ -9 unless it is small.
+
- 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!
+ 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).
+
+
+ ]
+ Additional documentation included in the package should 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.
+
+
+
+ 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 used or read by programs but
+ are also useful as stand alone documentation should be installed
+ elsewhere, such as
+ under /usr/share/package/, and then
+ included via symbolic links
+ in /usr/share/doc/package.
@@ -10720,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.
-
-