Re: Docbook tools

[Mark Galassi <rosalia@lanl.gov>]

Dear Eric,

Others on this list have already answered some of your points, but let
me also mention a couple of things.  First some specific answers, and
some general comments at the bottom.

    Eric> I am participating to the KDE project as documentation
    Eric> coordinator. [...]

    Eric> We at KDE are in the process of changing our documentation
    Eric> file format from LinuxDoc-SGML to DocBook-SGML.

I am delighted that KDE will also be using DocBook.

    Eric> In order to make it easy for our many translators and
    Eric> documentation writers to use DocBook tools such as James
    Eric> Clark's Jade, the OASIS DocBook DTD and Norman Walsh
    Eric> Stylesheet, I was planning to package all this stuff all
    Eric> together - exactly what you have done at Cygnus.

    Eric> So it is very likely that such an effort should not be
    Eric> duplicate, and that we should use Cygnus tools here at KDE,
    Eric> maybe with some extensions and/or parametrization for the
    Eric> specific needs of the KDE project.

That is good thinking.

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

    Eric> I had not the time to examine the details of Cygnus
    Eric> packaging, this will be done in the next days. But a few
    Eric> questions I would love to ask have already arisen :

    Eric> - You have packaged nearly exactly the same tools I was
    Eric> planning to, with the same version numbers. There is one
    Eric> main exception, Norman Walsh's stylesheet. I may be wrong,
    Eric> but it looks like you have packaged version 0.10, whereas
    Eric> version 1.42 is the current one. Is there a reason for that
    Eric> ?

The version numbering is because I used to ship three alternative
DocBook stylesheets, of which Norm's was just one.  Nowadays I still
ship them, but I doubt they would work without a lot of work, so I
should eventually make the version number match Norm's.  My 0.10
tracks Norm's version 1.44.

    Eric> - Why not putting everything in a single tarball / RPM /
    Eric> SRPM ? There could be a single ./configure / make / make
    Eric> install sequence.

The packages are maintained separately, and they use different
approaches to building and installing.  Maintaining a proper GNU
build/install system for each of them would be hard.

The SGMLTools team tries to do this, and in my opinion they have not
pulled it off well: people have a terrible time installing SGMLTools
from source, although I think the blame is partly in their clever (but
maybe too clever) configuration system.

I do think this can be done, but it will take some real work:

1. coordinate with *all* the individual maintainers so that when they
   are ready to put a new version out, we provide them with the
   automake/autoconf stuff for GNU users.

2. work out exactly how a good automake/autoconf system works for
   emacs lisp (both emacs and xemacs) and TeX

3. clean up the underlying sgml-common module, and have a clear
   concept of how the various DTDs and catalog entries accumulate as
   you do a "make install" for each.

I would still maintain them as separate packages, but I would then
feel better about releasing tarballs too (not just RPMs).  The
packages are all very different, and they can work with other goals,
so I do not see any reason to combine them.

    Eric> - It is indeed a very good idea to use RPM packages for
    Eric> those using RedHat-based systems (I am one, I am using
    Eric> LinuxPPC for Macintosh ;-) ). What is the reason for putting
    Eric> both the 3.0 version and the 3.1 version of the DocBook DTD
    Eric> in the RPM archive? It makes the file bigger.

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.

    Eric> - Have you encountered the same problems we have encountered
    Eric> with non-English languages and the TeX backend ? [...]

Dave Mason has already answered this point.  I will add that CKVJ (or
whatever the order was) probably stands for Chinese, Korean,
Vietnamese, Japanese.

    Eric> - I don't know what the hyperref package is and why it may
    Eric> be part of DocBook tools. Maybe I should try harder to
    Eric> understand that. Any help ?

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

    Eric> I hope that all these questions are interesting this
    Eric> discussion list, I apologize in advance for not having read
    Eric> all the archive of this mailing list, I was short in time.

The questions are certainly quite intersting.  Thanks for
participating!

Let me now make a couple of suggestions:

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

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

* 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.  And then we can also teach the
  Russians and the Chinese to live happily together.