Re: Evolution of the DocBook tools

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

Jorge Godoy wrote:
> 
> IMHO, if we want not interfere with the stylesheets used and want tro
> allow a generic use of these tools, there are few alternatives:
> 
> - Using the CATALOG directive
> - Using the DELEGATE directive
> - Merging CATALOG files (would require that we _change_ the specified
>   paths!)

- plus a fourth one, letting db2* scripts determine where are the
catalogs (my solution)

Among the first three ones, only the first one is really good, IMHO.

The third one was chosen by the current DocBook-tools and implied a
dirty directory layout if you don't want to re-work the paths. And this
had bad consequences if you wanted to use alternate stylesheets.

> Which programs don't recognize the CATALOG keyword? Jade and OpenJade
> work with no problems. Programs that don't work aren't in accordance
> with the specifications. Should we support them or "brake" them and
> make the author improve their programs?

Now I remember Epic does not recognize this keyword.

> > Same idea for what I did. What are your directory names ? I chose :
> >
> > docbook-dtd  docbook-stylesheets  iso-entities-8879.1986  jade  kde
> >
> > Let's all take the same names, if you accept. I also suggest "gnome" for
> > Gnome project customizations  and "ldp" for Linux Documentation Project
> > customizations.
> >
> > And I think it is becoming urgent that Mark should give us his blessing,
> > so those evolutions become "official" ;-)
> 
> Ok... I'm using a slightly different notation:
> 
> /usr/lib/sgml
>  - docbook-3.1
>  - docbook-3.0
>  - docbook-4.0beta
>  - docbook-2.4
>  - docbook-2.4.1
>  - docbook-version (generalization! I don't have this directory)
>  - jade
>  - iso-entities-8879.1986 (this is from sgmltools 1.09, not DocBook related)
>  - gnome (as you suggested)
>  - ldp (they don't have a stylesheet for DocBook yet...)
>  - kde (they have it?)

Yes, kde customization is available in package "kdesdk", subdirectory
"ksgmltools/customization"

Why don't you put the stylesheets at the same level as the dtd ? it
allows to change the stylesheets version, without changing the dtd, in a
simpler way (there are more stylesheet versions than dtd ones).

Docbook DTD and stylesheets numbering is a really good idea, indeed. It
looks like you went even further in the reflexion than I did ;-). What
about making a symbolic link from the generic name to the numbered name
? Like : docbook-dtd -> docbook-dtd-4.0beta.

Iso-entities are not only needed by sgmltools 1.09, but by jade as well.
Maybe you have them duplicate, just check.

So I suggest :

/usr/lib/sgml
  docbook-dtd-2.4
  docbook-dtd-2.4.1
  docbook-dtd-3.1
  docbook-dtd-3.0
  docbook-dtd-4.0beta
  docbook-dtd -> docbook-dtd-3.1
  docbook-sylesheets-1.49
  docbook-sylesheets-1.50
  docbook-sylesheets-1.51
  docbook-sylesheets-1.52
  docbook-stylesheets -> docbook-stylesheets-1.52
  jade
  iso-entities-8879.1986
  gnome
  ldp
  kde

> The problem with "iso-entities" is that some stylesheets refer to them
> on it's catalog. Making a patch in a packaged distribution (RPM, deb,
> etc.) is easy, but I don't know if it's good in a plain .tar.gz
> distribution (of course, a note saying that files were modified and
> the like would be enough).

I have been adding a catalog for them in iso-entities-8879.1986, the one
that was in sgml-tools-1.09 ;-) I searched a lot, even on ISO web
servere, but I was unable to find something that looked "official". So I
just did like the others and took what was available...

> BTW, there's another problem regarding iso-entities: sgmltools use
> them with upper case (ISOamsa) and Norm's stylesheets use it with
> lower case and an extension (isoamsa.gml). It's another
> standardization issue.

I was about to say it. I took :

ISOamsa  ISOamsc  ISOamso  ISObox   ISOcyr2  ISOgrk1  ISOgrk3  ISOlat1 
ISOnum  ISOtech
ISOamsb  ISOamsn  ISOamsr  ISOcyr1  ISOdia   ISOgrk2  ISOgrk4  ISOlat2 
ISOpub  iso-entities.cat

I had to remove the DTD catalog entries to have them shared between
sgml-tools and the modular stylesheets. Maybe it's not the right
solution, but it works (and anyway, this catalog had to be patched,
because it uses the DTDDECL keyword which is not supported by Jade).
Tell me if you have found a better solution.

All of this discussion, according to me, shows that it was necessary to
embetter the docbook-tools distribution, and to normalize the choices.
-- 
Eric Bischoff  -  Documentation and Localization
Caldera (Deutschland) GmbH - Linux for Business!
Tel: +49 9131 7192 300 -  Fax: +49 9131 7192 399
http://www.caldera.de/