(debian-policy.info)Additional documentation

---

Next: Preferred documentation formats Prev: Info documents Up: Documentation

---

Enter node , (file) or (file)node

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 (‘README’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!

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

Packages must not require the existence of any files in
‘/usr/share/doc/’ in order to function.  (1) 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.  (2)

   ---------- Footnotes ----------

   (1) The system administrator should be able to delete files in
‘/usr/share/doc/’ without causing any programs to break.

   (2) Please note that this does not override the section on changelog
files below, so the file ‘/usr/share/doc/package/changelog.Debian.gz’
must refer to the changelog for the current version of package in
question.  In practice, this means that the sources of the target and
the destination of the symlink must be the same (same source package and
version).