12.3. Additional documentation

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!

Plain text documentation should be compressed with gzip -9 unless it is small.

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 (Development files) 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).

If package is a build tool, development tool, command-line tool, or library development package, package (or package-dev in the case of a library development package) already provides documentation in man, info, or plain text format, and package-doc provides HTML or other formats, package should declare at most a Suggests on package-doc. Otherwise, package should declare at most a Recommends on package-doc.

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, Copyright information and Changelog files and release notes.

Packages must not require the existence of any files in /usr/share/doc/ in order to function. 6 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.

/usr/share/doc/package may be a symbolic link to another directory in /usr/share/doc only if the two packages both come from the same source and the first package Depends on the second. 7