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

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. 


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: