policy/ch-docs.rst

   1 Documentation
   2 =============
   3
   4 .. _s12.1:
   5
   6 Manual pages
   7 ------------
   8
   9 You should install manual pages in ``nroff`` source form, in appropriate
  10 places under ``/usr/share/man``. You should only use sections 1 to 9
  11 (see the FHS for more details). You must not install a pre-formatted
  12 "cat page".
  13
  14 Each program, utility, and function should have an associated manual
  15 page included in the same package. It is suggested that all
  16 configuration files also have a manual page included as well. Manual
  17 pages for protocols and other auxiliary things are optional.
  18
  19 If no manual page is available, this is considered as a bug and should
  20 be reported to the Debian Bug Tracking System (the maintainer of the
  21 package is allowed to write this bug report themselves, if they so
  22 desire). Do not close the bug report until a proper man page is
  23 available.  [#]_
  24
  25 You may forward a complaint about a missing man page to the upstream
  26 authors, and mark the bug as forwarded in the Debian bug tracking
  27 system. Even though the GNU Project do not in general consider the lack
  28 of a man page to be a bug, we do; if they tell you that they don't
  29 consider it a bug you should leave the bug in our bug tracking system
  30 open anyway.
  31
  32 Manual pages should be installed compressed using ``gzip -9``.
  33
  34 If one man page needs to be accessible via several names it is better to
  35 use a symbolic link than the ``.so`` feature, but there is no need to
  36 fiddle with the relevant parts of the upstream source to change from
  37 ``.so`` to symlinks: don't do it unless it's easy. You should not create
  38 hard links in the manual page directories, nor put absolute filenames in
  39 ``.so`` directives. The filename in a ``.so`` in a man page should be
  40 relative to the base of the man page tree (usually ``/usr/share/man``).
  41 If you do not create any links (whether symlinks, hard links, or ``.so``
  42 directives) in the file system to the alternate names of the man page,
  43 then you should not rely on ``man`` finding your man page under those
  44 names based solely on the information in the man page's header.  [#]_
  45
  46 Manual pages in locale-specific subdirectories of ``/usr/share/man``
  47 should use either UTF-8 or the usual legacy encoding for that language
  48 (normally the one corresponding to the shortest relevant locale name in
  49 ``/usr/share/i18n/SUPPORTED``). For example, pages under
  50 ``/usr/share/man/fr`` should use either UTF-8 or ISO-8859-1.  [#]_
  51
  52 A country name (the ``DE`` in ``de_DE``) should not be included in the
  53 subdirectory name unless it indicates a significant difference in the
  54 language, as this excludes speakers of the language in other countries.
  55 [#]_
  56
  57 If a localized version of a manual page is provided, it should either be
  58 up-to-date or it should be obvious to the reader that it is outdated and
  59 the original manual page should be used instead. This can be done either
  60 by a note at the beginning of the manual page or by showing the missing
  61 or changed portions in the original language instead of the target
  62 language.
  63
  64 .. _s12.2:
  65
  66 Info documents
  67 --------------
  68
  69 Info documents should be installed in ``/usr/share/info``. They should
  70 be compressed with ``gzip -9``.
  71
  72 The ``install-info`` program maintains a directory of installed info
  73 documents in ``/usr/share/info/dir`` for the use of info readers. This
  74 file must not be included in packages other than install-info.
  75
  76 ``install-info`` is automatically invoked when appropriate using dpkg
  77 triggers. Packages other than install-info *should not* invoke
  78 ``install-info`` directly and *should not* depend on, recommend, or
  79 suggest install-info for this purpose.
  80
  81 Info readers requiring the ``/usr/share/info/dir`` file should depend on
  82 install-info.
  83
  84 Info documents should contain section and directory entry information in
  85 the document for the use of ``install-info``. The section should be
  86 specified via a line starting with ``INFO-DIR-SECTION`` followed by a
  87 space and the section of this info page. The directory entry or entries
  88 should be included between a ``START-INFO-DIR-ENTRY`` line and an
  89 ``END-INFO-DIR-ENTRY`` line. For example:
  90
  91 ::
  92
  93     INFO-DIR-SECTION Individual utilities
  94     START-INFO-DIR-ENTRY
  95     * example: (example).               An example info directory entry.
  96     END-INFO-DIR-ENTRY
  97
  98 To determine which section to use, you should look at
  99 ``/usr/share/info/dir`` on your system and choose the most relevant (or
 100 create a new section if none of the current sections are relevant).
 101 [#]_
 102
 103 .. _s-docs-additional:
 104
 105 Additional documentation
 106 ------------------------
 107
 108 Any additional documentation that comes with the package may be
 109 installed at the discretion of the package maintainer. It is often a
 110 good idea to include text information files (``README``\ s, FAQs, and so
 111 forth) that come with the source package in the binary package. However,
 112 you don't need to install the instructions for building and installing
 113 the package, of course!
 114
 115 Plain text documentation should be compressed with ``gzip -9`` unless it is small.
 116
 117 If a package comes with large amounts of documentation that many users
 118 of the package will not require, you should create a separate binary
 119 package to contain it so that it does not take up disk space on the
 120 machines of users who do not need or want it installed. As a special
 121 case of this rule, shared library documentation of any appreciable size
 122 should always be packaged with the library development package
 123 (:ref:`s-sharedlibs-dev`) or in a separate documentation
 124 package, since shared libraries are frequently installed as dependencies
 125 of other packages by users who have little interest in documentation of
 126 the library itself. The documentation package for the package package is
 127 conventionally named package-doc (or package-doc-language-code if there
 128 are separate documentation packages for multiple languages).
 129
 130 If package is a build tool, development tool, command-line tool, or
 131 library development package, package (or package-dev in the case of a
 132 library development package) already provides documentation in man,
 133 info, or plain text format, and package-doc provides HTML or other
 134 formats, package should declare at most a ``Suggests`` on package-doc.
 135 Otherwise, package should declare at most a ``Recommends`` on
 136 package-doc.
 137
 138 Additional documentation included in the package should be installed
 139 under ``/usr/share/doc/package``. If the documentation is packaged
 140 separately, as package-doc for example, it may be installed under either
 141 that path or into the documentation directory for the separate
 142 documentation package (``/usr/share/doc/package-doc`` in this example).
 143 However, installing the documentation into the documentation directory
 144 of the main package is preferred since it is independent of the
 145 packaging method and will be easier for users to find.
 146
 147 Any separate package providing documentation must still install standard
 148 documentation files in its own ``/usr/share/doc`` directory as specified
 149 in the rest of this policy. See, for example,
 150 :ref:`s-copyrightfile` and
 151 :ref:`s-changelogs`.
 152
 153 Packages must not require the existence of any files in
 154 ``/usr/share/doc/`` in order to function.  [#]_ Any files that are
 155 used or read by programs but are also useful as stand alone
 156 documentation should be installed elsewhere, such as under
 157 ``/usr/share/package/``, and then included via symbolic links in
 158 ``/usr/share/doc/package``.
 159
 160 ``/usr/share/doc/package`` may be a symbolic link to another directory
 161 in ``/usr/share/doc`` only if the two packages both come from the same
 162 source and the first package Depends on the second.  [#]_
 163
 164 .. _s12.4:
 165
 166 Preferred documentation formats
 167 -------------------------------
 168
 169 The unification of Debian documentation is being carried out via HTML.
 170
 171 If the package comes with extensive documentation in a markup format
 172 that can be converted to various other formats you should if possible
 173 ship HTML versions in a binary package.  [#]_ The documentation must
 174 be installed as specified in :ref:`s-docs-additional`.
 175
 176 Other formats such as PostScript may be provided at the package
 177 maintainer's discretion.
 178
 179 .. _s-copyrightfile:
 180
 181 Copyright information
 182 ---------------------
 183
 184 Every package must be accompanied by a verbatim copy of its copyright
 185 information and distribution license in the file
 186 ``/usr/share/doc/package/copyright``. This file must neither be
 187 compressed nor be a symbolic link.
 188
 189 In addition, the copyright file must say where the upstream sources (if
 190 any) were obtained, and should include a name or contact address for the
 191 upstream authors. This can be the name of an individual or an
 192 organization, an email address, a web forum or bugtracker, or any other
 193 means to unambiguously identify who to contact to participate in the
 194 development of the upstream source code.
 195
 196 Packages in the *contrib* or *non-free* archive areas should state in
 197 the copyright file that the package is not part of the Debian
 198 distribution and briefly explain why.
 199
 200 A copy of the file which will be installed in
 201 ``/usr/share/doc/package/copyright`` should be in ``debian/copyright``
 202 in the source package.
 203
 204 ``/usr/share/doc/package`` may be a symbolic link to another directory
 205 in ``/usr/share/doc`` only if the two packages both come from the same
 206 source and the first package Depends on the second. These rules are
 207 important because ``copyright`` files must be extractable by mechanical
 208 means.
 209
 210 Packages distributed under the Apache license (version 2.0), the
 211 Artistic license, the GNU GPL (versions 1, 2, or 3), the GNU LGPL
 212 (versions 2, 2.1, or 3), the GNU FDL (versions 1.2 or 1.3), and the
 213 Mozilla Public License (version 1.1 or 2.0) should refer to the
 214 corresponding files under ``/usr/share/common-licenses``,  [#]_ rather
 215 than quoting them in the copyright file.
 216
 217 You should not use the copyright file as a general ``README`` file. If
 218 your package has such a file it should be installed in
 219 ``/usr/share/doc/package/README`` or ``README.Debian`` or some other
 220 appropriate place.
 221
 222 All copyright files must be encoded in UTF-8.
 223
 224 .. _s-copyrightformat:
 225
 226 Machine-readable copyright information
 227 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 228
 229 A specification for a standard, machine-readable format for
 230 ``debian/copyright`` files is maintained as part of the debian-policy
 231 package. This document may be found in the ``copyright-format`` files in
 232 the debian-policy package. It is also available from the Debian web
 233 mirrors at
 234 https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/.
 235
 236 Use of this format is optional.
 237
 238 .. _s12.6:
 239
 240 Examples
 241 --------
 242
 243 Any examples (configurations, source files, whatever), should be
 244 installed in a directory ``/usr/share/doc/package/examples``. These
 245 files should not be referenced by any program: they're there for the
 246 benefit of the system administrator and users as documentation only.
 247 Architecture-specific example files should be installed in a directory
 248 ``/usr/lib/package/examples`` with symbolic links to them from
 249 ``/usr/share/doc/package/examples``, or the latter directory itself may
 250 be a symbolic link to the former.
 251
 252 If the purpose of a package is to provide examples, then the example
 253 files may be installed into ``/usr/share/doc/package``.
 254
 255 .. _s-changelogs:
 256
 257 Changelog files
 258 ---------------
 259
 260 Packages that are not Debian-native must contain a compressed copy of
 261 the ``debian/changelog`` file from the Debian source tree in
 262 ``/usr/share/doc/package`` with the name ``changelog.Debian.gz``.
 263
 264 If an upstream changelog is available, it should be accessible as
 265 ``/usr/share/doc/package/changelog.gz`` in plain text. If the upstream
 266 changelog is distributed in HTML, it should be made available in that
 267 form as ``/usr/share/doc/package/changelog.html.gz`` and a plain text
 268 ``changelog.gz`` should be generated from it using, for example,
 269 ``lynx -dump -nolist``. If the upstream changelog files do not already
 270 conform to this naming convention, then this may be achieved either by
 271 renaming the files, or by adding a symbolic link, at the maintainer's
 272 discretion.  [#]_
 273
 274 All of these files should be installed compressed using ``gzip -9``, as
 275 they will become large with time even if they start out small.
 276
 277 If the package has only one changelog which is used both as the Debian
 278 changelog and the upstream one because there is no separate upstream
 279 maintainer then that changelog should usually be installed as
 280 ``/usr/share/doc/package/changelog.gz``; if there is a separate upstream
 281 maintainer, but no upstream changelog, then the Debian changelog should
 282 still be called ``changelog.Debian.gz``.
 283
 284 For details about the format and contents of the Debian changelog file,
 285 please see :ref:`s-dpkgchangelog`.
 286
 287 .. [#]
 288    It is not very hard to write a man page. See the
 289    `Man-Page-HOWTO <http://www.schweikhardt.net/man_page_howto.html>`_,
 290    man7, the examples created by ``dh_make``, the helper program
 291    ``help2man``, or the directory ``/usr/share/doc/man-db/examples``.
 292
 293 .. [#]
 294    Supporting this in ``man`` often requires unreasonable processing
 295    time to find a manual page or to report that none exists, and moves
 296    knowledge into man's database that would be better left in the file
 297    system. This support is therefore deprecated and will cease to be
 298    present in the future.
 299
 300 .. [#]
 301    ``man`` will automatically detect whether UTF-8 is in use. In future,
 302    all manual pages will be required to use UTF-8.
 303
 304 .. [#]
 305    At the time of writing, Chinese and Portuguese are the main languages
 306    with such differences, so ``pt_BR``, ``zh_CN``, and ``zh_TW`` are all
 307    allowed.
 308
 309 .. [#]
 310    Normally, info documents are generated from Texinfo source. To
 311    include this information in the generated info document, if it is
 312    absent, add commands like:
 313
 314    ::
 315
 316        @dircategory Individual utilities
 317        @direntry
 318        * example: (example).  An example info directory entry.
 319        @end direntry
 320
 321    to the Texinfo source of the document and ensure that the info
 322    documents are rebuilt from source during the package build.
 323
 324 .. [#]
 325    The system administrator should be able to delete files in
 326    ``/usr/share/doc/`` without causing any programs to break.
 327
 328 .. [#]
 329    Please note that this does not override the section on changelog
 330    files below, so the file
 331    ``/usr/share/doc/package/changelog.Debian.gz`` must refer to the
 332    changelog for the current version of package in question. In
 333    practice, this means that the sources of the target and the
 334    destination of the symlink must be the same (same source package and
 335    version).
 336
 337 .. [#]
 338    Rationale: The important thing here is that HTML documentation should
 339    be available from *some* binary package.
 340
 341 .. [#]
 342    In particular, ``/usr/share/common-licenses/Apache-2.0``,
 343    ``/usr/share/common-licenses/Artistic``,
 344    ``/usr/share/common-licenses/GPL-1``,
 345    ``/usr/share/common-licenses/GPL-2``,
 346    ``/usr/share/common-licenses/GPL-3``,
 347    ``/usr/share/common-licenses/LGPL-2``,
 348    ``/usr/share/common-licenses/LGPL-2.1``,
 349    ``/usr/share/common-licenses/LGPL-3``,
 350    ``/usr/share/common-licenses/GFDL-1.2``,
 351    ``/usr/share/common-licenses/GFDL-1.3``,
 352    ``/usr/share/common-licenses/MPL-1.1``, and
 353    ``/usr/share/common-licenses/MPL-2.0`` respectively. The University
 354    of California BSD license is also included in base-files as
 355    ``/usr/share/common-licenses/BSD``, but given the brevity of this
 356    license, its specificity to code whose copyright is held by the
 357    Regents of the University of California, and the frequency of minor
 358    wording changes, its text should be included in the copyright file
 359    rather than referencing this file.
 360
 361 .. [#]
 362    Rationale: People should not have to look in places for upstream
 363    changelogs merely because they are given different names or are
 364    distributed in HTML format.