Re: DocBook instead of debiandoc-sgml? (was Re: Planning an Italian manual)
I had a detailed look at docbook yesterday and have mixed feelings about
it. Here is a list of advantages and disadvantages of docbook that I
discovered. It might be good to hear some comments on the list below.
(the lists don't have a particular order)
Advantages of docbook:
1. DTD is much more complete than debiandoc's DTD
2. actively maintained
3. de-facto industry standard (I was told)
4. IMHO much nicer HTML/PS output
Disadvantages:
1. DTD contains lots of stuff we'll probably never need
2. what I've seen so far, the jade* tools seem to be slower than the
debiandoc2foo scripts
3. one needs a lot more tools to compile docbook .sgml files than to
compile debiandoc files
4. it's probably much harder for us to extend it if we need special
commands
5. there is no "text" output
(ok, I'll stop here for now)
I want to stress that the disadvantages #2 and #3 are extremely important:
according to the current plans for the new "doc policy" we want to ship
only .sgml and .html files in future. Then, the user can recompile any
other formats (.text, .PS, etc.) using `doc-base'.
#5: I think a lot of people will complain if we don't have text versions
of our documents anymore. (Though, I don't need these text versions
myself--I prefer HTML--a lot of people have requested that I ship text
versions of the policy manual, etc. We should not ignore these people.)
Disadvantage #4 is also important: Recall, that we have good plans for
implemented `dynamical hyperlinks'. The idea was to adjust hyperlinks
between our documents dynamically, depending in whether a local version of
the referenced document exists or not (in which case the link would point
to the nearest Internet server which carries the document).
(Note, that we had plans to support special link tags for packages, manual
pages, etc. I'm sure, docbook will never implement these tags.)
In summary: We did had good reasons to stick to debiandoc-sgml instead of
switching over to linuxdoc-sgml/sgml-tools, and I think the same arguments
still hold for the debiandoc-sgml vs. docbook discussion.
debiandoc-sgml does nearly everything we need and the few missing features
(internationalization, cross references, href's, etc.) could easily be
implemented. If debiandoc-sgml would be enhanced at these points, I think
we would get advantages #1, #2, and #4 for debiandoc-sgml too, while we
wouldn't been faced with the disadvantages listed above.
(cf. http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-doc/dtd.html )
Bottom line: What's worrying me most is why we have so much energy for
these discussions but only very few people are writing documents. We have
been discussing these issues now several times and we did had a lot of
good ideas. I'd prefer having manuals written in a sub-optimal DTD (no
matter which one this is), than to have no manuals but a perfect
documentation policy.
I think it would be possible to allow everyone use the DTD he/she prefers
(provided that the DTD can be compiled with tools available in the Debian
main distribution) in order to get more people writing manuals!
We really don't have a problem with the DTD. Our problem is that too few
people are working on the documentation!
After we have more manuals, we could start this discussion again and see
which advantages we would get by switching to a common DTD. Since all DTD
are in fact very similar, it shouldn't be too much work to switch from one
DTD to another afterwards.
(I hope this doesn't start a flame war now. I know that a few people are
working on different manuals and doing documentation is not always fun.
However, we still don't have up-to-date manual pages for dpkg &c, we still
don't have a users manual uploaded, ...)
Comments are welcome!
Thanks,
Chris
-- _,, Christian Schwarz
/ o \__ schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
! ___; schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
\ /
\\\______/ ! PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
\ / http://fatman.mathematik.tu-muenchen.de/~schwarz/
-.-.,---,-,-..---,-,-.,----.-.-
"DIE ENTE BLEIBT DRAUSSEN!"
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-doc-request@lists.debian.org .
Trouble? e-mail to templin@bucknell.edu .
Reply to: