6.7.3. Documentation

Be sure to follow the Policy on documentation.

If your package contains documentation built from XML or SGML, we recommend you not ship the XML or SGML source in the binary package(s). If users want the source of the documentation, they should retrieve the source package.

Policy specifies that documentation should be shipped in HTML format. We also recommend shipping documentation in PDF and plain text format if convenient and if output of reasonable quality is possible. However, it is generally not appropriate to ship plain text versions of documentation whose source format is HTML.

Major shipped manuals should register themselves with doc-base on installation. See the doc-base package documentation for more information.

Debian policy (section 12.1) directs that manual pages should accompany every program, utility, and function, and suggests them for other objects like configuration files. If the work you are packaging does not have such manual pages, consider writing them for inclusion in your package, and submitting them upstream.

The manpages do not need to be written directly in the troff format. Popular source formats are DocBook, POD and reST, which can be converted using xsltproc, pod2man and rst2man respectively. To a lesser extent, the help2man program can also be used to write a stub.