OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: Re: Q) Re: DOCBOOK-APPS: Converting from DocBook/SGML to DocBook/XML

Jeffrey_Franks@i-o.com wrote:
> Hi,
> Ian Castle wrote:
> ....snip....
> > But the beauty of the xml stuff is that you can use either XSL or DSSSL
> > stylesheets and tools.
> Being fairly new to this, I have a question:
> Is there an advantage in using DSSSL with DocBook Xml?
> Does DSSSL work better than Xsl for rendering PDF?
> Are DSSSL tools and utilities more mature and have fewer bugs?
> -- Jeff

The choice is yours!

But this is my choice:

We are a small software house - we also deliver training courses. Our
products are mainly cross platform - meaning that we have to build on a
number of platforms. We don't have a lot of budget or time. As you all
know there is the continual problem of keeping documentation
(specifications, release notes, users guides, training materials up to

The key thing with XML/SGML is that 
  - it is cross platform
  - the same tools (editors, make, cvs and so) are used to prepare the
documentation as the rest of the product.

This encourages the developers to keep up to date with the
documentation. In our change control system, changes (ECOs) are stored
in a database. Each completed ECO is assigned to a release. The release
notes are mainly automatically produced - i.e. a script pulls the data
out of the database and writes out the DocBook XML/SGML. This is then
included into the release notes proper.

So when it comes to release time, the documentation is produced
automatically as part of the build process.. "make all" or whatever
(actually, on UNIX platforms we tend to package things with RPM..).

Although the XML/SGML tools are fairly "developer" friendly, I do have
to make sure that everyone can actually use them. Each developer,
potentially, needs access to the tools. Each platform needs access to
the tools. Some people work from home and needs the tools there.

There is no Linux/UNIX distribution which comes with an up-to-date set
of tools, so I have to do some work to get a common toolset across each

We use RPM based linux distributions and have ported RPM to our other
UNIX platforms - so our DocBook tool chain is packaged as a set of RPMS.
I can then give CD to each developer to install on their own
workstations (every one has access to Linux, even if their primary
environment is NT). The RPM system is useful as it allows a system to be
easily upgraded and to have its status interrogated.

So a very important factor in what toolset to use, for me, is the
administrative effort involved. All the UNIX environments have a GNU C
compiler (we hardly do any java - but a lot of C++). To install the
DSSSL (openjade, tex, jadetex) tool chain requires a lot less effort
across the whole range of platforms. The UNIX systems either have no
java or widely different java versions. We don't really use java for any
other purpose so I would have to spend a whole load of time maintaining
java for each platform and making sure that everything was up to date
[this maybe is not such a big issue as I seem to be making... I just
don't know - and don't really want to find out ;-)].

We are more concerned to have good quality paper ready documentation -
so PDF is the main target - the HTML is "a welcome bonus".

So this is what we do:

1) Author new documents in XML (old ones are still SGML).

This means that we can use either DSSSL or XSL stylesheets. I expect to
transition to XSL at some point in the future.

2) Use TeX which is very stable - I've only upgraded hyperref and I'm
not sure that I needed to do that.

3) Avoid java based tools - one day, Java will be stable and ubiquitous
on all platforms, I'm sure (I was hoping that GCC 3.0 (gcj) might make
java tools like saxon less of an issue - but xsltproc has now arrived!).

The DSSSL tool chain (openjade, jadetex) is now "mature" enough to
produce good enough documents - i.e. for the mark up that we are using
there are no really annoying errors. I will probably look at customising
the stylesheet some more. At the moment I am more comfortable with DSSSL
than with XSL ;-).

In short, the DSSSL toolchain gives an environment which works for us,
with a relatively small amount of maintenance etc. The effort of
installing and keeping up to date with the java based tool chain would
be quite considerable.... Really, the current DocBook toolset that we
are using is just a very small set of patches to the Mandrake 8/Redhat 7

I've never managed to find all the bits needed to get FOP working - with
out having to download and install a full java SDK. It took long enough
to work out which "jre" to get - so I've never actually used it.

I expect that I will move towards using xsltproc to produce
HTML/XHTML/htmlhelp before too long.

Maybe somebody will port fop to libxml2, libxsl one day!

Currently, passivetex is probably happier sat on top of the TeXlive
distro. Which I don't have - and isn't RPM based which is important to
me. I've played with passivetex a bit - I had to do a fair bit of
piecemeal TeX upgrading (from a tetex 1.0.7 based RPM) - and the results
weren't as good as good as with jadetex and the DSSSL stylesheets.
Passivetex is perhaps more "arcane" than jadetex - either way, it is
likely that fop will develop quicker as it has a fairly active
development community... does anyone other than Sebastian work on

Anyway, I've rambled on for long enough... I will attempt to summarise:

[assuming you don't want to/can't pay for "better" commercial packages]

- Write documents in DocBook/XML - it is toolchain agnostic

- Use DSSSL stylesheets, openjade, jadetex if you need to get to
"production quality" paper output with a minimum of upgrades to your
existing environment [perhaps "Linux/UNIX environment" rather than
"existing environment"-  Mandrake/Redhat/Debian environment rather than
Windows.]. Also, if you are happy with the stylesheets as is and do not
want to make extensive customisations.

- Use XSL stylesheets if you are interested in primarily
HTML/XHTML/htmlhelp output - and/or if you are already in an established
java environment.

- Use XSL stylesheets if you are operating in a self contained
environment - and are happy to be at the bleeding edge or want to
actively develop the state of the art in document preparation, and want
to play around with stylesheet develoment.

Currently, I consider the DSSSL toolchain to be in "stable, maintenance"
mode, while active development and future leaps in functionality will
come with the continuing development of the XSL toolchain.

Hope that helps - remember, this is just my perspective.



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC