Re: DOCBOOK-APPS: which DocBook in DOCTYPE?

[Bob Stayton <bobs@sco.COM>]

> From: Jon Willeke <willeke@intersys.com>
> 
> This is kind of a trivial question, I suppose.  I'm using DocBook XML 
> 4.1.2.  The XSL processor and psgml look for the DTD.  As I understand it, 
> 4.1.2 contains no semantic changes to 4.0.  Should I put 4.0 or 4.1.2 in 
> the DOCTYPE?
> 
> If I put 4.0 in the DOCTYPE, should I use the old copy of DocBook or map it 
> to a newer version in the catalog file?

This is not a trivial question at all.  Consider a
collection of hundreds or thousands of XML files
documenting a big operating system.  These files have a
lifetime of several years, and many files don't change for
long periods.  During those years the Docbook DTD changes,
and you change your processing tools to match.  If each
file's DOCTYPE has the DTD version number in the PUBLIC or
SYSTEM id, then you have to choose your poison:

1) Maintain all the DTD versions on your system and make
sure your tools support them.  This is no fun.
When someone asks a question, make sure you find out
which DTD version the file is using before you answer.

2) Use your catalog to map all the PUBLIC id versions to
the latest DTD version and hope it works.  This can create
great confusion, since a file's DOCTYPE refers to one DTD and the
actual processing uses another.  Not recommended to lie to
your own system.

3) Check out every file and update the DOCTYPE to the latest
version, and repeat with each new DTD version.  Fortunately,
the PUBLIC ID only includes the first and second version digits
(4.1), not the third (4.1.2).

4) Make your DOCTYPE a constant, use the catalog to map
it to the latest DTD, and fix any files that break when
you update the DTD.

I've chosen #4 and use a simple DOCTYPE in my files:

<!DOCTYPE book SYSTEM "docbook.dtd">

I let the catalog map SYSTEM "docbook.dtd" to the location
of latest version of the DTD.  This relies on catalog
processing, and I no longer tolerate tools that cannot use
a catalog.  Well, I do if I can wrap a shell script around
it to reset the file's SYSTEM id to the current DTD
location.  If a DTD update causes a file to no longer
parse, I go back and update the file to match the new DTD.

This way I only have to maintain the latest DTD, I don't
have to lie to my system, and I don't have to update
DOCTYPES in all those files that are not otherwise
changing.  I do have to keep my files up to date with the
DTD, but I've chosen to do that anyway.  Docbook is stable
enough now that this is generally not a significant
burden.

I'm curious as to how other people handle this problem.

bobs
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The Santa Cruz Operation, Inc.              fax:   (831) 429-1887
                                            email: bobs@sco.com