Re: DocBook instead of debiandoc-sgml?
Christian Schwarz <schwarz@monet.m.isar.de> writes:
> 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.
>
> Ok.
>
> > > 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
> purpose?
>
> > > 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.)
I completely agree with all points made by Christian S.
> 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.
No, I don't think this is a good idea. If everybody just uses what
pleases her we would get a mess with all kinds of formats, layouts,
looks, etc. This is in my opinion definitely not the way to go.
Just take a look at how all the Debian binary packages behave: If a
package has any business in e.g. /etc/init.d it uses the corresponding
(un)installer and not something of its own. Since I started following
the development of Debian I've only seen more and more of these. The
result of all these (un)installers, including dhelp, dwww, etc., is a
robust, clean, well-behaving system with less surprises for the
"users" than most Unix system. All packages follow the same policy
and all related discussions go in the same direction: how can we make
Debian the best free system there is!
Now take a look at the other documentation in Debian: All manual pages
are written in troff, all Info manuals are written in Texinfo. These
"documentation languages" may not be the most perfect in the world,
but they get the job done and the result is again a consistent look
and feel with only few surprises for the "users". Do you hear anyone
actually complaining about them? No, they're simply used.
Now wouldn't it be nice to get the same effect with the various
Debian manuals? I guess the "users" would at least appreciate this.
Using a single DTD has all kinds of advantages in terms of
maintenance, shuffling sections around, keeping the look and feel
consistent, incorporating the manuals in dwwwm, dhelp, etc.
At least the LDP uses one and the same DTD for ALL their stuff.
Why can't we simply do the same? If the current functionality of
debiandoc-sgml is lacking a useful feature we simply have to add it
(without messing things up as in sgml-tools, of course). That's how
things go with the binary packages (which by the way we are supposed
to document!!!), and look at the results.
Of course, if someone wants to write some documentation for some
package, she free to use whatever DTD pleases her, as long as it gets
the job done for her. But writing a complete set of manuals which are
also planned to be interlinked simply requires using a single DTD.
So, I propose to keep the policy to use debiandoc-sgml for the manuals
as they are currently planned and listed on the DDP home page.
Now back to maintaining debiandoc-sgml (for me :-), writing Debian
manuals (for all of us), and other more interesting Debian things
(also for all of us)!
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: