nroff
source
form, in appropriate places under /usr/man. You
should only use sections 1 to 9 (see the FSSTND 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/man/man[1-9]/the_requested_manpage.[1-9].gzThis 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/man).
Your package must call install-info
to update the Info
dir
file, in its post-installation script:
install-info --quiet --section Development Development \ /usr/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/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/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.
, 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/doc/package
in the binary package. However, you don't need to install
the instructions for building and installing the package, of
course!
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/doc/appropriate package or its
subdirectories.
[1]
Other formats such as PostScript may be provided at your option.
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/doc/<package-name> may be a symbolic link to a directory in /usr/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/doc/copyright/BSD, /usr/doc/copyright/Artistic, /usr/doc/copyright/GPL, and /usr/doc/copyright/LGPL.
Do not use the copyright file as a general README
file. If your package has such a file it should be
installed in /usr/doc/package/README
or
README.Debian or some other appropriate place.
/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.
as
changelog.Debian.gz. If the upstream changelog
file is text formatted, it must be accessable as
/usr/doc/package/changelog.gz
. If the
upstream changelog file is HTML formatted, it must be
accessable as /usr/doc/package/changelog.html.gz
.
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/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.