Re: DocBook instead of debiandoc-sgml?
Christian Leutloff <leutloff@sundancer.oche.de> writes:
> 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.
Adding them to debiandoc-sgml is also very easy.
> > 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.
Just one more package we would be dependent upon. Further, do we want
to let a browser "decide" how things should look? I don't think so.
> > 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.
This still does not cover all the needs we have for our proposed cross
reference system, though.
> > 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, ...)
Well, why don't we start working on these then? Can I see some
proposal if you've ideas for them?
> 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.
What's wrong with the current output? I think the manuals look good.
> > 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.
Just my $0.02.
Thanks,
Ardo
--
Ardo van Rangelrooij
home email: ardo.van.rangelrooij@tip.nl, ardo@debian.org
home page: http://www.tip.nl/users/ardo.van.rangelrooij
PGP fp: 3B 1F 21 72 00 5C 3A 73 7F 72 DF D9 90 78 47 F9
--
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: