Christian Schwarz <schwarz@monet.m.isar.de> writes:
> Disadvantages:
>
> 1. DTD contains lots of stuff we'll probably never need
but it doesn't hurt - but there are different tags for, i.e. filename
and command. With this information we will be able to generate very
easily an index with all the filenames and another with the commands.
> 2. what I've seen so far, the jade* tools seem to be slower than the
> debiandoc2foo scripts
but it's IMHO harder to extend/customize the debiandoc2foo scripts
than the style sheets that are used with jade. I try to modify
both. The modular style sheets that are used with jade can be
customized very easily. But the perl scripts that are used with
debiandoc were much harder for me, even if I could better program with
perl than DSSSL (scheme).
> 4. it's probably much harder for us to extend it if we need special
> commands
no, it's very easy. There comes even a customization guide with the
DocBook documentation.
> 5. there is no "text" output
As a workaround: you can make one HTML file from your SGML document
and then dump the file with lynx into a .txt file.
> 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).
Please have a look a the different link types in DocBook (that I've
found so far): xref, link, ulink, olink.
> 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 )
we are missing two very important things: images and tables, (plus set of
books, glossary, ...)
With debiandocsgml it's impossible to process an article on it's
own. The DocBook DTD is written very well, even a table can be
processed on it's own.
It was very difficult (= time consuming) for me to use debiandocsgml
for a printable output (to make a book). I don't understand lout and
my debiandoc2latex needs much (unnecessary) fine tuning by hand.
> 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.
The problem is IMHO that we are not able to discuss *small* portions of
the manual. Nobody is able to write 100 pages in a reasonable time. We
should split each document in small peaces so that everybody only
needs to write 5 pages. Therefor I propose my skeleton tags. I'm going
to implement them in April (hopefully). If somebody wants to start
working now, please send me a small notice.
Bye
Christian
--
Christian Leutloff, Aachen, Germany leutloff@sundancer.oche.de
http://www.oche.de/~leutloff/ leutloff@debian.org
Debian GNU/Linux - http://www.de.debian.org/
Attachment:
pgpDRUyOpes_7.pgp
Description: PGP signature