Re: documentation types

[Lars Wirzenius <liw@liw.iki.fi>]

pe, 2006-02-10 kello 07:36 -0500, Neil Roeth kirjoitti:
> On Feb 10, Hendrik Sattler (post@hendrik-sattler.de) wrote:
>  > I about packaging a library that ships an API reference in docbook SGML and 
>  > provides manual build targets for PDF, PS and HTML.
>  > 
>  > Is there any preference on which type should be included in the -dev package?
>  > I would prefer PDF:
>  >  * one file only
>  >  * easy to print
>  >  * many viewers available
> 
> Could it be a configure option, so that the first time the package is
> installed it would ask which subset of the three to install (defaulting to PDF
> only), and later, when upgrading the package, it would install the same
> subset with no further interaction?

This has been discussed a long time ago and there is a policy decided.
>From the Policy Manual:

        12.4 Preferred documentation formats
        
        The unification of Debian 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.[76]
        
        Other formats such as PostScript may be provided at the package
        maintainer's discretion.

Thus the thing to do is to provide HTML.

It would be nice to be able to ship, say, HTML and SGML, and then have a
quick and easy way to generate other formats (PS/PDF for various paper
sizes, at least) from the SGML, and anyone who creates the tools to do
that will get a lot of goodwill.

-- 
One does not see anything until one sees its beauty. -- O.W.