/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
).
/usr/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/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.
/usr/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 (README
s,
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 the binary package, in the directory
/usr/doc/
package or its subdirectories.
Other formats such as PostScript may be provided at your option.
/var/log/
package.log
.
If you have many log files, or need a separate directory for
permissions reasons (/var/log
is writable only by
root
), you should usually create a directory named
/var/log/
package
.
Make sure that any log files are rotated occasionally so that they
don't grow indefinitely; the best way to do this is to use
savelog program in an /etc/cron.daily
,
/etc/cron.weekly
or /etc/cron.monthly
script. Here is a good
example:
[ -d /var/log/apache/. ] || exit 0 umask 022 cd /var/log/apache if [ -fs access.log ] then savelog -c 7 access.log > /dev/null fi
Make sure that any log files are removed when the package is purged
(but not when it is only removed), by checking the argument to the
postrm
script (see the Debian Packaging Manual for
details).
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.
/usr/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.
debian/changelog
file from your Debian source tree, and a copy of the upstream
changelog file if there is one. They should usually be installed in
/usr/doc/
package
as changelog.Debian.gz
and
changelog.gz
respectively.
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
.