docbook-tools, the next generation

[Mark Galassi <rosalia at lanl dot gov>]

[I finally have some time to dedicate to this; sorry for my silence so
far.]

    Eric> What I need now is some approval by docbook-tools
    Eric> maintainer, Mark Galassi, and somewhere to build a
    Eric> docbook-utils homepage (docbook-utils being the set of db2*
    Eric> scripts, plus the install-catalog script, which I suggest to
    Eric> be separate from the modular stylesheets package now).

Eric, Jorge, and others,

I appreciate the effort and the deference to me :-)

Let me make some comments and then let us all start working on the
next generation of DocBook tools.

The DocBook tools had a limited goal (being easy to install and run
was pretty much all there was to it).  They do that very well.

On the other hand, DocBook is now the de-facto standard format of the
free software community, and people frequently want to do more than
simply print an English language document or conver it to HTML.

So we should go further.

Eric's goals are good ones, but I would like to offer some warnings
and inject a few more requirements into the new docbook-tools design.

I would also like to offer that we use the full extent of the
Sourceware site to coordinate our work.

Warning: if you are going to be ambitious, make sure you do not make
the terrible mistakes made in the SGML-tools project:

1. A very fancy approach to installing which required more than the
   GNU standards allow (python and so forth for end-users installing
   from source) and which never worked.  The traffic on the sgml-tools
   list was largely due to installation problems.

2. A certain arrogance in treating installation complaints.  If there
   is every a problem in installing, the maintainer should whip
   himself every night until it is resolved, rather than saying "this
   is open source software, so you fix it".

3. The use of the name "sgml tools" for something which was not
   general-purpose SGML.  As a consequence, the top level executable
   program "sgmltools" with a vast list of options was confusing.  The
   db2* scripts are clearer, even though not flexible at all.  We
   should have those scripts, with defaults that handle almost all
   needs, and offer options for the less common stuff.

4. Catalogs never worked well for all users: they needed environment
   variables set correctly, without which things would not work...

Note, though, that Cees de Groot's energy helped the whole DocBook
movement a lot: he put a ton of work into making jade work with gcc
and autoconf, without which jade might today only work on Windows.

Having warned against being too ambitious, let me suggest a few things
*in addition* to what others are saying (although

* We should provide "packaging for what other people writte", but in a
  more profound manner.  We should offer patches to openjade, the
  modular stylesheets and jadetex so that those packages end up being
  distributed as GNU-compliant tarballs that can be converted into
  RPMs or Debian packages with the simplicity of the

    rpm -ta prog-version.tar.gz

  command, with the .spec file being quite trivial.

  The best way to do this might be to automake-ify what is not yet
  using automake.

  Some maintainers, like Norman, probably, will not feel a need to
  have Makefile.am files in their master distribution, so we can just
  offer to put out the extra bit every time he makes a release.

* Installation will (as a consequence of using automake/autoconf) be
  very simple, requiring nothing other than a boure shell.

* All major packaging formats should be supported, which will also
  come easy.

* We must decide if we want to support old LinuxDoc stuff.  I would
  suggest we deprecate that whole DTD and simply offer the SGML-tools
  tool to convert those to DocBook, and then focus on DocBook.

* We must decide on proper nomenclature.  If our tools are general
  enough for other DTDs (like TEI), then we can call things
  /usr/share/sgml.  Otherwise it should be /usr/share/docbook-tools.
  Also, it's /usr/share and not /usr/lib according to the GNU
  standards (/usr/lib is for architecture-dependent stuff, like .a
  files).

* Someone should do a careful reading of the filesystem hierarchy
  standard to see how to lay things out and what to put in /etc versus
  /usr/share.

* I like the install-catalog approach, and at the time it was the best
  one, but nowadays the "environment variable/catalog path" approach
  can work robustly and is probably better.  We need a clean design
  for where to put catalogs.  Should it be /usr/share/sgml/CATALOG
  (for basic ISO entities and stuff) and /usr/share/jade/CATALOG.jade
  (for what Jade introduces), /usr/share/docbook-tools/CATALOG.nwalsh
  (for Norm's stylesheets), and so forth?  Or do we bunch them all up?
  Or do they go in /etc?

I'm sure there's more.  Who wants to work on doing all this?  If I get
people who want to do it in a disciplined and coordinated manner, I
will start taking care of the setup details.