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

Re: DocBook instead of debiandoc-sgml?

On 26 Feb 1998, Christian Leutloff wrote:

> 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.

It does hurt IMO: there are way to many tags to choose from which we'll
never need and a few tags we could need aren't available. For example,
there is no tag <package>foo</package> which displays a package name in a
typewriter or bold font. 

With so many tags to choose from (where no tag really fits), people will
end up looking at the output and decide then, which tag to use for certain
terms. With that, it would be much easier to have only one <em>foo</em>
and one <strong>foo</strong> tag.

> >  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).

I can't comment on this one since I don't know DSSSL. But the main point
is: do we have someone that would want to update the DSSSL macros for us?

> >  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. 

Could you give me a hint how I could generate a single HTML file for this 

> > 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.

No, these tags don't have the requested functionality. 

Also note, that we wanted our hyperlinks to use the URN format and support
hyperlinks to Debian packages, manual pages, etc., all in a common format.

> > 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, ...) 

I don't believe (anymore) that the lack of functionality of debiandoc-sgml
is the reason why we have so few manuals (but so many ideas and opinions
in these discussions).

Really: I'd say everyone can use the DTD of his/her choice. I've we have a
consensus about this, I'll remove the reference to debiandoc-sgml from the
DDP home page. What currently is important, is that we get manuals, not in
which DTD these manuals are written. 

> 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.

I guess you are referring to the `Diplomarbeit' you're writing for your
studies. Note, that this discussion is just about which SGML system we
want to use for the DDP documents. (I didn't suggest that O'Reilly
switches over to debiandoc-sgml because it's *better* ;-)

> > 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.

I don't remember about the `skeleton' tags, but wouldn't it suffice to
have someone set up the `Table of Contents' and then everyone writes a
section? I really don't think that the functionality of any SGML systems
available is an excuse here.

(But please don't get this wrong: I don't have any problems if people here
don't have time or simply don't want to write manuals for us! The problem
I have is that so many people want to discuss the same topics all over
again, but don't want to actually work on improving Debian's
documentation. The fact that dpkg still doesn't have uptodate manual pages
is unacceptable to me.) 

Ok, does everyone agree that we remove the `policy' statement from the DDP
pages that we use debiandoc-sgml? I'd suggest to change this policy aspect
to allow DDP authors to use the SGML system of their choice, provided that
the SGML system is part of the Debian main system and does not require
non-free components for processing the documents. 



--                 Christian Schwarz
                    schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
Don't know Perl?     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.perl.com     http://fatman.mathematik.tu-muenchen.de/~schwarz/

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: