Re: Docbook tools

[Eric Bischoff <ebisch@cybercable.tm.fr>]

Dear Mark,

Le Tue, 07 Sep 1999, Mark Galassi a écrit :
>     Eric> The DocBook team at KDE has also developped some tools that
>     Eric> could prove of some interest for other users, such as a
>     Eric> crash course to DocBook that people report to be of
>     Eric> quality. Have a look at
>     Eric> http://www.kde.org/documentation/docbook/index.html.
> 
> This seems to overlap a lot with my tutorial, as others have already
> mentioned.  Nik's FreeBSD DocBook tutorial (which started out with
> mine) also overlaps.  Some day...

I talked recently about that with Guy Brand, who is on this list as well and who
is my next block neighbour ;-). Read carefully both tutorials and you will see
that there is very few overlapping in the contents. They overlap in the sense
that they intend to do the same thing : teach docbook to newcomers. But they
take two different approaches :
- Your strategy : explain the concepts (descriptive markup, ...), don't teach
the tags (the reference manual is there for that), go quickly to more advanced
concepts (such as the parts of SGML syntax that may be useful in DocBook, such
as parameter entities)
- David Rugge's Strategy : explain the purpose of DocBook, compare it with
LinuxDoc, give a detailed explaination of more common tags (admonitions, lists,
metainformation, ...), omit the more advanced tags (glossary, index, ...),
remain basic, focus on KDE needs

I don't know FreeBSD tutorial but I'm sure that it also has its own
particularities. We (I and Guy Brand) went to the conclusion that we should
merge everything, and Guy's suggestion was to do a progression in the
level of difficulty of what is teached. I imagine a framework like :
- start with your introduction
- add a detailed section about installation and usage of the docbook-tools
- then go to David's explanation of the basic tags
- then explain more advanced tags
- then switch to your explanations about what may be useful in SGML
- as Guy Brand would like, explain all the parametrization stuff (DTD,
stylesheet).

As Guy Brand said, Linux urgently needs a DocBook-HOWTO. This document could
be based on this merging work (or would the result be too long for an HOWTO???)

> The packages are all very different, and they can work with other goals,
> so I do not see any reason to combine them.

The reason would be : simplify installation. Download ONE thing, and make a
single ./configure, make, make install. But, as you say, there are many problems
linked with that idea.

> The reason is so that you can process both 3.0 and 3.1 DocBook
> documents.  If you look at the mailing list archives, my most recent
> large announcement talked about that in a bit more detail.

I read it just after posting. Sorry. ;-)

> No *immediate* help, except that jadetex uses it, and it used to not
> come with a basic TeX distribution.  It does now, but I'm not sure
> about the version numbers.  Next time I put out a package, I will see
> if I can do without the hyperref stuff :-)

I am using more or less the same versions that you have packaged, and I didn't
need it. But, if I remember well, I needed another TeX package that was not
installed on my system. Was it Babel ? I regret I didn't write that down :-(.

> * I strongly recommend that you use the same RPM distribution of tools
>   that we use (I'm also trying to get the Debian guys to start working
>   from common source).

This is what I am here for ;-)

>  You should participate in the software effort
>   (it's not hard) so that we can come up with a whole collection of
>   customizations for the stylesheets.  Ideally there should be the
>   Cygnus customization (which is rather small), the GNOME one, the KDE
>   one, the FreeBSD one, the "linux documentation project" one, and so
>   forth.

You can already have a look at KDE's customization at
http://www.kde.org/documentation/docbook. There is a DTD and a DSL. Very
short files, because we have tried hard to change as few things that we could.
Be also aware that we have started this docbook stuff very short time ago.

>  I would like them all to be easy switches to "db2html" and
>   the other "db2*" scripts.  I'll talk about this more some other
>   time, when I outline my ideas for future enhancements.

About that point, I'm wondering right now how I could make KDE's scripts
kdb2html and kdb2ps rely on your own scripts, instead of re-writing them from
scratch.

> * I would merge the tutorials together.  Take a look at mine
>   (http://nis-www.lanl.gov/~rosalia/docbook-intro.html) and let me
>   know if we can merge some of your beef with mine, and then maybe
>   make a KDE-specific appendix.

It looks like that everyone had the same idea ;-).

The KDE-specific stuff could go to a separate file.

About this merging project : I'm very interested, but I don't have the time
right now. After KDE's conversion to DocBook, sure.

> * I am delighted about the possibility of KDE/GNOME cooperation in
>   documentation issues.  We should talk about some aspects of this,
>   like directory layout, help-topics locations, common Makefile.am
>   documentaiton target rules, and maybe equivalent help menus.  We'd
>   teach the other parts of the GNOME and KDE teams how well we work
>   together on common standards.

I am no "official KDE representative", so I don't have the right to speak in
name of the KDE project apart from technical issues linked with documentation.
But I think I reveal no state secret if I say that I spoke about that
subject with Matthias Ettrich (KDE project founder) in Strasbourg and in
Kaiserslautern, and that I also heard him interviewed by Linux Magazine France
journalists : he has nothing against both projects taking common approaches, on
the contrary. They already did on several issues (drag'n'drop protocol, etc...).

>  And then we can also teach the
>   Russians and the Chinese to live happily together.

Well, that point makes no problem in the KDE project ;-)

Eric
--
 __________________________________________________
     .~.    "Release of Windows 2000 has been
     /V\      postponed until January 1, 1901"
   //   \\
  /(     )\ 
    ^^-^^
 __________________________________________________
Eric Bischoff - mailto:ebisch@cybercable.tm.fr