[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: documentation types

On Fri, Feb 10, 2006 at 02:54:09PM +0200, Lars Wirzenius wrote:
> Thus the thing to do is to provide HTML.

I disagree, the thing to do is to provide HTML *and* an easy to print
format, that is PS or PDF.

> 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.

It is much better if the binary package provides a ready to use PS/PDF
version than force the user to do it since there have been known issues in
which the PDF generation (specially for some languages) is not as robust as
it should be. If the package generates a PS/PDF (and the maintainer reviews
that it is correct) it saves the user from having to struggle through the
generation of a PS/PDF version if he encounters an issue when generating it
(which might be due to a local issue, a bug in the sgml toolchain, a font
issue or whatever). That saves the maintainer bug reports and saves the users
the hassle of handling (obscure) documentation formats.

Providing the SGML source is (IMHO) akin to saying that packages should provide
source code and compile it on the user's systems (think Gentoo). It is *much*
more flexible, but much more open to bugs.

Moreover, I know of *no* -doc packages that provide SGML format so there
is not that much experience (or tools) on how to automatically do what others
suggest (dwww integratin). Check out the documents from the DDP (that is, the
FAQ, the d-i manual, the Debian reference, the Securing Debian Manual) and
the formats provided in their binary packages, they are, usually, three
formats: text, HTML and PDF.

Best regards


Attachment: signature.asc
Description: Digital signature

Reply to: