You should install manual pages in nroff source form, in
appropriate places under /usr/share/man. You should only use
sections 1 to 9 (see the FHS for more details). You must not install a
preformatted `cat page'.
Each program, utility, and function should have an associated manpage included in the same package. It is suggested that all configuration files also have a manual page included as well.
If no manual page is available for a particular program, utility, function or
configuration file and this is reported as a bug to the Debian Bug Tracking
System, a symbolic link from the requested manual page to the
undocumented(7) manual page may be provided. This symbolic link
can be created from debian/rules like this:
ln -s ../man7/undocumented.7.gz \
debian/tmp/usr/share/man/man[1-9]/requested_manpage.[1-9].gz
This manpage claims that the lack of a manpage has been reported as a bug, so you may only do this if it really has (you can report it yourself, if you like). Do not close the bug report until a proper manpage is available.
You may forward a complaint about a missing manpage to the upstream authors, and mark the bug as forwarded in the Debian bug tracking system. Even though the GNU Project do not in general consider the lack of a manpage to be a bug, we do; if they tell you that they don't consider it a bug you should leave the bug in our bug tracking system open anyway.
Manual pages should be installed compressed using gzip -9.
If one manpage needs to be accessible via several names it is better to use a
symbolic link than the .so feature, but there is no need to fiddle
with the relevant parts of the upstream source to change from .so
to symlinks: don't do it unless it's easy. You should not create hard links in
the manual page directories, nor put absolute filenames in .so
directives. The filename in a .so in a manpage should be relative
to the base of the manpage tree (usually /usr/share/man). If you
do not create any links (whether symlinks, hard links, or .so
directives) in the filesystem to the alternate names of the manpage, then you
should not rely on man finding your manpage under those names
based solely on the information in the manpage's header.[56]
Info documents should be installed in /usr/share/info. They should be compressed with gzip -9.
Your package should call install-info to update the Info
dir file in its postinst script when called with a
configure argument, for example:
install-info --quiet --section Development Development \
/usr/share/info/foobar.info
It is a good idea to specify a section for the location of your program; this is done with the --section switch. To determine which section to use, you should look at /usr/share/info/dir on your system and choose the most relevant (or create a new section if none of the current sections are relevant). Note that the --section flag takes two arguments; the first is a regular expression to match (case-insensitively) against an existing section, the second is used when creating a new one.
You should remove the entries in the prerm script when called with
a remove argument:
install-info --quiet --remove /usr/share/info/foobar.info
If install-info cannot find a description entry in the Info file
you must supply one. See install-info(8) for details.
Any additional documentation that comes with the package may be installed at the discretion of the package maintainer. 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.
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.
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!
Files in /usr/share/doc should not be referenced by any program, and the system administrator should be able to delete them without causing any programs to break. Any files that are referenced by programs but are also useful as standalone documentation should be installed under /usr/share/package/ with symbolic links from /usr/share/doc/package/.
Former Debian releases placed all additional documentation in
/usr/doc/package. To realize a smooth migration to
/usr/share/doc/package, each package must maintain a
symlink /usr/doc/package that points to the new
location of its documentation in
/usr/share/doc/package[57]. The symlink must be created when the package is
installed; it cannot be contained in the package itself due to problems with
dpkg. One reasonable way to accomplish this is to put the
following in the package's postinst[58]:
if [ "$1" = "configure" ]; then
if [ -d /usr/doc -a ! -e /usr/doc/package \
-a -d /usr/share/doc/package ]; then
ln -sf ../share/doc/package /usr/doc/package
fi
fi
and the following in the package's prerm:
if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
-a -L /usr/doc/package ]; then
rm -f /usr/doc/package
fi
The unification of Debian documentation is being carried out via HTML.
If your package comes with extensive documentation in a markup format that can be converted to various other formats you should if possible ship HTML versions in a binary package, in the directory /usr/share/doc/appropriate-package or its subdirectories.[59]
Other formats such as PostScript may be provided at the package maintainer's discretion.
Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file /usr/share/doc/package/copyright. This file must neither be compressed nor be a symbolic link.
In addition, the copyright file must say where the upstream sources (if any) were obtained, and should explain briefly what modifications were made in the Debian version of the package compared to the upstream one. It should name the original authors of the package and the Debian maintainer(s) who were involved with its creation.
A copy of the file which will be installed in /usr/share/doc/package/copyright should be in debian/copyright in the source 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. These rules are important because copyrights must be extractable by mechanical means.
Packages distributed under the UCB BSD license, the Artistic license, the GNU GPL, and the GNU LGPL should refer to the files /usr/share/common-licenses/BSD, /usr/share/common-licenses/Artistic, /usr/share/common-licenses/GPL, and /usr/share/common-licenses/LGPL respectively, rather than quoting them in the copyright file.
You should not use the copyright file as a general README file. If your package has such a file it should be installed in /usr/share/doc/package/README or README.Debian or some other appropriate place.
Any examples (configurations, source files, whatever), should be installed in a directory /usr/share/doc/package/examples. These files should not be referenced by any program: they're there for the benefit of the system administrator and users as documentation only. Architecture-specific example files should be installed in a directory /usr/lib/package/examples with symbolic links to them from /usr/share/doc/package/examples, or the latter directory itself may be a symbolic link to the former.
Packages that are not Debian-native must contain a compressed copy of the debian/changelog file from the Debian source tree in /usr/share/doc/package with the name changelog.Debian.gz. If an upstream changelog is available, it should be accessible as /usr/share/doc/package/changelog.gz in plain text. If the upstream changelog is distributed in HTML, it should be made available in that form as /usr/share/doc/package/changelog.html.gz and a plain text changelog.gz should be generated from it using, for example, lynx -dump -nolist. If the upstream changelog files do not already conform to this naming convention, then this may be achieved either by renaming the files, or by adding a symbolic link, at the maintainer's discretion.[60]
All of these files should be installed compressed using gzip -9, as they will become large with time even if they start out small.
If the package has only one changelog which is used both as the Debian changelog and the upstream one because there is no separate upstream maintainer then that changelog should usually be installed as /usr/share/doc/package/changelog.gz; if there is a separate upstream maintainer, but no upstream changelog, then the Debian changelog should still be called changelog.Debian.gz.
Debian Policy Manual
version 3.5.6.1, 2002-03-14ijackson@gnu.ai.mit.eduschwarz@debian.orgbweaver@debian.orgdebian-policy@lists.debian.org