You must 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'.
If no manual page is available for a particular program, utility or function
and this is reported as a bug on debian-bugs, a symbolic link from the
requested manual page to the undocumented(7)
manual page should 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]/the_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. Do not create hard links in the manual page directories, and do not 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).
Info documents should be installed in /usr/share/info. They should be compressed with gzip -9.
Your package must call install-info
to update the Info
dir file, in its post-installation script:
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 must remove the entries in the pre-removal script:
install-info --quiet --remove /usr/share/info/foobar.info
If install-info
cannot find a description entry in the Info file
you will have to supply one. See install-info(8)
for details.
Any additional documentation that comes with the package can be installed at the discretion of the package maintainer. Text documentation should be installed in a 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!
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[6]. 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
:
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 mark up 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. [7]
Other formats such as PostScript may be provided at your option.
Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file /usr/share/doc/<package-name>/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 explain briefly what modifications were made in the Debian version of the package compared to the upstream one. It must name the original authors of the package and the Debian maintainer(s) who were involved with its creation.
/usr/share/doc/<package-name> may be a symbolic link to a directory in /usr/share/doc only if two packages both come from the same source and the first package has a "Depends" relationship 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. [8]
Do 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, and files in /usr/share/doc/package/examples symlink to files in it. Or the latter directory may be a symlink to the former.
This installed file must contain a copy of the debian/changelog file from your Debian source tree, and a copy of the upstream changelog file if there is one. The debian/changelog file should be installed in /usr/share/doc/package as changelog.Debian.gz. If the upstream changelog file is text formatted, it must be accessible as /usr/share/doc/package/changelog.gz. If the upstream changelog file is HTML formatted, it must be accessible as /usr/share/doc/package/changelog.html.gz. A plain text version of the changelog must be accessible as /usr/doc/package/changelog.gz (this can be created by lynx -dump -nolist). If the upstream changelog files do not already conform to this naming convention, then this may be achieved by either renaming the files or adding a symbolic link at the packaging developer's discretion.
Both 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.
ijackson@gnu.ai.mit.edu
schwarz@debian.org
bweaver@debian.org
debian-policy@lists.debian.org