docbook-tools, the next generation

docbook-tools, the next generation

[Mark Galassi]

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

Re: docbook-tools, the next generation

[Norman Walsh]

/ Mark Galassi <rosalia@lanl.gov> was heard to say:
|   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.

I'd be happy to coordinate distributions to include appropriate
automake stuff. I'll even add it as an RFE for the main DocBook
distribution.

What would be particularly helpful is if someone would show me
what I need to add.

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

I've switched to /share/doctypes on my system. Doctypes being
slightly more general than sgml, since many of the DTDs I use
are now xml. (But I'm on NT so I'm still not using automake and
the like.)

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

Where is that standard?

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

I'm certainly interested. I have a real problem with this
mailing list though. It turns out that the ISP I use when I
travel, and I travel too much ;-), has been blacklisted by
whatever service this mailing list uses to avoid spammers. So I
can't post here when I'm on the road.

I'm so pissed about this that I'm "this close" to unsubscribing.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | If all mankind were to disappear,
http://nwalsh.com/                 | the world would regenerate back to
                                   | the rich state of equilibrium that
                                   | existed ten thousand years ago. If
                                   | insects were to vanish, the
                                   | environment would collapse into
                                   | chaos.--Edward O. Wilson

Re: docbook-tools, the next generation

[Mark Galassi]

    Norman> I'd be happy to coordinate distributions to include
    Norman> appropriate automake stuff. I'll even add it as an RFE for
    Norman> the main DocBook distribution.

OK, I took your bait and added automake to your stylesheets.  The GNU
style tarball is at

ftp://sourceware.cygnus.com/docbook-tools/docbook-stylesheets-1.52.tar.gz

There's a lot to say about what I did, so I'll start:

1. I arbitrarily chose the package name docbook-stylesheets, but can
   change it.  I don't find a claer choice of a package name in what
   you do.

2. The files I added were the top level configure.in, autogen.sh and
   docbook-stylesheets.spec.  Then the Makefile.am files in all
   directories.  The GNU automake/autoconf process adds a bunch of
   other stuff to the tarball so that end users only need a working
   Bourne shell to do the installation, but that stuff should not be
   CVS-controlled since automake adds it itself.

3. Developers should have recent versions of automake and autoconf on
   their system.  Their pattern is that they "cvs .... checkout ..."
   and then run "./autogen.sh" the first timime around.  After that
   they can just install with "make install" for the rest of their
   lives.

4. I noticed that your zip file keeps all the files in the "installed"
   locations and you don't have a program which installs them.  So I
   made the Makefile.am files keep the same exact hierarchy (under)
   $(prefix)/share/docbook-stylesheets.  The only thing I don't put
   there is collateindex.pl which goes into $(prefix)/bin

   This should make things work reasonably well since you can invoke
   jade in the same way, but I have not yet actually tried it.

5. I have built (for kicks; not yet serriously) RPMs with the simple
   "rpm -ta docbook-stylesheets-1.52.tar.gz" and they work.

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

    Norman> Where is that standard?

You can find it at http://www.pathname.com/fhs/

How it applies to DocBook tools was discussed in Jan. 1999 on the
sgml-tools list, but no real progress was made.

    Norman> I'm certainly interested. I have a real problem with this
    Norman> mailing list though. It turns out that the ISP I use when
    Norman> I travel, and I travel too much ;-), has been blacklisted
    Norman> by whatever service this mailing list uses to avoid
    Norman> spammers. So I can't post here when I'm on the road.

    Norman> I'm so pissed about this that I'm "this close" to
    Norman> unsubscribing.

I've asked the sourceware sysadmins to turn that blacklist feature off
on this list and some otherse that I maintain.  Can you give it a bit
more of a chance?

Re: docbook-tools, the next generation

[Jochem Huhmann]

Hi Mark,

* Mark Galassi <rosalia@lanl.gov> wrote:
> 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.

Have you subscribed to the list at conectiva and/or browsed through its
archives? There has quite a lot of work being done.

We should work on a set of recommondations for such scripts, so
different scripts can work together and use the same settings. IMHO
every new tool for SGML/DocBook will be nothing else than just another
tool if we don't do that.


        Jochem

-- 
Hi! I'm a .signature virus! Copy me into your ~/.signature to help me spread!