Subject: Documentation formats

From: [email-masked] (Ian Jackson)
Date: Fri, 9 Aug 96 15:41 BST

I've just added the subsection below to the draft policy manual.

Bruce, tell me if you want me to say something different.

I'd like to come up with some rather more formal way of distributing
our different documentation formats.  Perhaps we should create a new
subdirectory of the FTP site for packages' PostScript documentation
and upload it separately.

Alternatively we could recommend that if a package can produce
documentation in n formats it should put the HTML in with the package
itself (if it doesn't warrant a separate package) but put the other
n-1 together in a separate package which uses some canonical naming
scheme.  Eg,
 dpkg           - contains the programs and the HTML documentation
 dpkg-docxf     - contains the documentation in ps, plain text &c
or
 texinfo        - contains the Texinfo formatter itself
 texinfo-doc    - contains the documentation run through texi2html
 texinfo-docxf  - contains the docs in /usr/info, and as dvi
If we do this we should probably say that if a package produces dvi as
its native format we should ship dvi and not ps.

Ian.

<sect1>Preferred documentation formats

The unification of Debian documentation is being carried out via HTML.
<p>

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
<tt>/usr/doc/<var/package/</> or its subdirectories.
<p>

Other formats such as PostScript may be provided at your option.