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

Re: documentation types

On Thu, Feb 16, 2006 at 04:43:11PM +0100, Hendrik Sattler wrote:
> 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).

The user always has the *source* package available to do as he pleases. Your
solution does not provide a way to generate any format from the SGML sources,
the front-end will still be limited.

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

The problem is that the toolchain might be ok, but having all the tools
properly configured to, for example, compile proper PDF versions for some
languages (like Japanese) is not inmediate. Compiling SGML sources to some
formats require not just a proper toolchain but also proper configuration
which the user might not have done (and cannot be automated)

> Policy says to ship HTML, else I wouldn't.

Policy is somewhat out of date with respect to documentation. There's
actually a (draft) DDP policy which covers this already. I know, I've written

> It would be great to have a new debhelper package that creates the previously 
> chosen documentation formats from the provided SGML file on installation. 

Debhelper? You are aware that debhelper is used on package *building* not
on package installation, right?

> This would save MUCH more in download size than any of the previously 
> discussed compression formats (may it be bzip2, 7zip or whatever).

If you don't want a big package don't install it, go for the source.
Actually, you can just locally compile the documentation packages if you
don't want to download the -doc (binary) packages providing PDF, HTML or
whatever other format.

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

It does not exist, before going into a useless discussion, show me some code.
Without a tool being available to do this all this is wishful thinking. The
current best practice is to provide a grepable/searchable format (txt), an
offline viewing format integrated with dwww (HTML) and a printable format
(PS or PDF, at maintainer's discrection).

As I said, if somebody doesn't like this, write something on the lines of
your suggestions and show it here. I don't believe somebody is going to write
because, you know, we've been doing it like this for *years* and nobody
complained (at least not loud enough) about bulky documentation packages (and
a few years back bandwidth was not as affordable).



Attachment: signature.asc
Description: Digital signature

Reply to: