Re: documentation types
Am Donnerstag, 16. Februar 2006 10:04 schrieb Javier Fernández-Sanguino Peña:
> 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.
Ok, then you choose HTML and PDF. And the next user asks why he cannot get it
in the format provided by docbook2xyz (substitute xyz with any possible
value).
If Debian may have problem with the SGML toolchain, then fix the toolchain
instead of needlessly shipping hundreds files that all contain the same text
and only differ in the format.
Policy says to ship HTML, else I wouldn't.
It would be great to have a new debhelper package that creates the previously
chosen documentation formats from the provided SGML file on installation.
This would save MUCH more in download size than any of the previously
discussed compression formats (may it be bzip2, 7zip or whatever).
And if the administrators choice is to not want any automatically created
formats, he may use a docbook program that displays it from the SGML or XML
source. Why not, such a tool may exist at one time or maybe does already.
HS
Reply to: