[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]


Ubuntu Policy Manual
Chapter 12 - Documentation


12.1 Manual pages

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 pre-formatted "cat page".

Each program, utility, and function should have an associated manual page included in the same package. It is suggested that all configuration files also have a manual page included as well. Manual pages for protocols and other auxiliary things are optional.

If no manual page is available, this is considered as a bug and should be reported to the Ubuntu Bug Tracking System (the maintainer of the package is allowed to write this bug report themselves, if they so desire). Do not close the bug report until a proper man page is available.[90]

You may forward a complaint about a missing man page to the upstream authors, and mark the bug as forwarded in the Ubuntu bug tracking system. Even though the GNU Project do not in general consider the lack of a man page 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 man page 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 man page should be relative to the base of the man page tree (usually /usr/share/man). If you do not create any links (whether symlinks, hard links, or .so directives) in the file system to the alternate names of the man page, then you should not rely on man finding your man page under those names based solely on the information in the man page's header.[91]

Manual pages in locale-specific subdirectories of /usr/share/man should use either UTF-8 or the usual legacy encoding for that language (normally the one corresponding to the shortest relevant locale name in /usr/share/i18n/SUPPORTED). For example, pages under /usr/share/man/fr should use either UTF-8 or ISO-8859-1.[92]

A country name (the DE in de_DE) should not be included in the subdirectory name unless it indicates a significant difference in the language, as this excludes speakers of the language in other countries.[93]

Due to limitations in current implementations, all characters in the manual page source should be representable in the usual legacy encoding for that language, even if the file is actually encoded in UTF-8. Safe alternative ways to write many characters outside that range may be found in groff_char(7).


12.2 Info documents

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.


12.3 Additional documentation

Any additional documentation that comes with the package may be installed at the discretion of the package maintainer. Plain 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!

Packages must not require the existence of any files in /usr/share/doc/ in order to function [94]. Any files that are referenced by programs but are also useful as stand alone documentation should be installed under /usr/share/package/ with symbolic links from /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.[95]

Former Debian releases placed all additional documentation in /usr/doc/package. This has been changed to /usr/share/doc/package, and packages must not put documentation in the directory /usr/doc/package. [96]


12.4 Preferred documentation formats

The unification of Ubuntu 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.[97]

Other formats such as PostScript may be provided at the package maintainer's discretion.


12.5 Copyright information

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. It should name the original authors of the package and the Ubuntu 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 Apache license (version 2.0), the Artistic license, the GNU GPL (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and the GNU FDL (versions 1.2 or 1.3) should refer to the corresponding files under /usr/share/common-licenses,[98] 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.


12.6 Examples

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.

If the purpose of a package is to provide examples, then the example files may be installed into /usr/share/doc/package.


12.7 Changelog files

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.[99]

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.

For details about the format and contents of the Debian changelog file, please see Ubuntu changelog: debian/changelog, Section 4.4.


[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]


Ubuntu Policy Manual

version 3.8.2.0ubuntu1, 2009-06-19

The Debian Policy Mailing List
The Ubuntu Developers Mailing List