Re: future development of doc-base
On 9 Apr 1998, Adam P. Harris wrote:
[snip]
> Christian, with respect to your considerations for redesign, there's a
> lot to think about. The big issue I guess is whether we want to keep
> the split between content registration and conversion handling
> (doc-base) and content presentation (dhelp, dwww). Some of the things
> Jim proposes go far beyond content presentation. Maybe that split is
> not going to work for us; maybe it will.
First of all, I'm really happy that you took ovr doc-base! Thanks for your
work on this!
I don't have any problems with discussion the design of doc-base now, but
please let include the results from the last discussion.
Some time ago there was a _long_ discussion about chapter 5 of the policy
manual (starting with bug report#7890): policy says that large amounts of
documentation should be split off into a separate package and non-HTML
formats should be converted into HTML if possible. (Please check out the
bug report and the policy manual for more details.)
The discussion has shown clearly, that we can't please everyone by simply
packaging up a few selected formats: different people prefer different
formats, like HTML, HTML.gz, HTML.gz with fixed links, TEXT, PS, INFO,
DVI, etc.
We did some research and found out that some conversions (like TEXI->info)
are simple (i.e., run fast, don't require a lot of programs, aren't error
prone, etc.) while others (like TEXI->HTML) can be a hard work (i.e., lots
of tools required, compilation takes some time, etc.).
We also agreed that most people will use HTML (so it will stay `preferred
documentation format').
The discussion finally ended with a consensus like this:
1. We ship HTML _and_ the documentation's source format (whether this
is).
2. We set up the `doc-base' package to which all documentation files will
be registered. Doc-base can do the HTML->HTML.gz (opt., fix links)
conversion if the user wants this, and doc-base could also do other
conversions like TEXI->info (only if selected).
For example, the debian-policy package would ship HTML files and the SGML
debiandoc source. Most users could read the manual with the HTML files,
and if someone wants PS files, she can install debiandoc-sgml and tell
doc-base to generate this file for her.
Other packages, like bash, would ship a HTML and a TEXI (texinfo source)
version of all GNU info documents. (Note, that the TEXI->info conversion
is simple to do and could easily done by doc-base, but the TEXI->HTML
conversion is quite slow.)
This was the one story.
The other story is about our online menu systems: We currently have to
systems, dhelp and dwww (with dwww having two ways of registering
documents, namely via menu and with .dwww-index files). Both systems have
different designs (dhelp uses `static' HTML index files, while dwww works
as a CGI script) and therefore quite different advantages and
disadvantages.
Because of this, all efforts of my part to get at least the document
registry code of both tools to support a common registry file format
failed! But in order to make these systems useful for the users, all
packages have to support these. This would only be done, if policy would
mandate their use. However, policy will never mandate each maintainer to
support two (totally different) only menu systems!
Since all documentation files will eventually be registered to doc-base
anyways (since doc-base will do the format conversion), it's obviously the
best solution (from the maintainer's point of few) if doc-base registers
documents to the online menu systems.
In summary, I still think that doc-base is highly needed for conversion
_and_ for registry. Comments are appreciated, and but please keep the
above arguments in mind. It doesn't make sense to start the discussion all
over again.
Thanks,
Chris
-- Christian Schwarz
Do you know schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
Debian GNU/Linux? schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
Visit PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
http://www.debian.org http://fatman.mathematik.tu-muenchen.de/~schwarz/
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: