DocBook sample

[Allan Stokes]

Hello all,

I have been working on setting up the DocBook tool chain, learning the psgml
authoring environment, and trying to figure out how different DocBook
constructs are rendered by the various backend options.

I have been working on an experimental document which discusses partitioning
strategies.  This document includes equations and some other things I
haven't mastered yet.  While I was comparing my notes to the Pooma source
code I stumbled upon r2/docs/Layout.html which I hadn't noticed in this
connection before.  I've most accessed the tutorial directly off the Pooma
web site and I had forgotten that there were a couple of other pieces.

Last night I decided it would be a reference point to convert this document
into DocBook format.

I did this process almost entirely on the NT side.  The image conversion
from .gif to .png was done with Gimp under Linux.

There are three main pathways in the Jade backend processing.

With the HTML style sheet, Jade generates HTML directly.
With the PRINT style sheet, Jade generates either RTF or TeX.
>From TeX, one can produce PS or PDF.

The biggest problem in the production process is including appropriate image
formats.  Different backends require different image formats to be supplied
from a single source document.

The idea in DocBook is that you declare multiple image sources and each
backend chooses one from the list it is able to handle.  I haven't yet been
able to get that to work as advertised.  In every case I tried explicitly,
the backend choose the first image from the list, even if the backend was
not capable of processing that format.  It's possible I need to find a
customization layer for the stylesheets to impose selectivity.  Stylesheets
do everything in this world.

My conversion focused exclusively on block-level elements.  There are many
DocBook elements which can be applied inline, but these are not yet present.
I have also left the stylesheets in their stock configuration.  Everything
here is virgin Jade/MikTex.  I converted the .gif images with Gimp without
modification, except for the first image which appears, which was too big to
fit on the page in PDF mode.  There's a scaling factor problem between the
HTML and PRINT outputs which I don't yet understand.

Working with psgml I didn't find the process onerous.  It would be more
difficult to do this kind of conversion without using emacs.  psgml has a
quick internal validator which found 90% of my errors immediately.  A very
small number of errors were reported with the external validator after the
internal validation passed.  A somewhat larger body of complaints was
produced by different backends concerning values accepted in attribute tags.
(The DTD doesn't say much about values.)  Nothing was any worse than a
typical error message from a C compiler.

The biggest hassle concerned the angle brackets.  I was relieved to discover
that I could represent &lt; in my text with "<-" and &gt; with "->" and the
SGML tools don't get all huffy about it.  I think the best approach is to
leave the (decorated) angle brackets in code examples during authorship, and
add an extra sed to the final production step.  Manglations like
Dom&lt;int&gt; are simply impossible to read if you are trying to think
seriously about the code you are quoting.

Included is the DocBook source document, the PDF output file, and all the
HTML fragments as one attachment.  Initially I had very poor results from
RTF.  When I went back and looked at RTF it wasn't as bad as I thought, so
I've included it separately as sample RTF output.

Once again I welcome any comments people might have about the DocBook
process or the suitability of DocBook to the kinds of documentation
processes the Pooma project requires.

Allan



Here is the list of files included in the main attachment.

layout-docbook/
layout-docbook/images/
layout-docbook/images/advection1d.png
layout-docbook/images/bordergraph.png
layout-docbook/images/grid-2bisection.png
layout-docbook/images/grid-2D.png
layout-docbook/images/grid-2gl.png
layout-docbook/images/grid-2stl.png
layout-docbook/images/grid-2ugl.png
layout-docbook/images/grid-2uniform.png
layout-docbook/layout.pdf
layout-docbook/layout.sgml
layout-docbook/t1.htm
layout-docbook/x104.htm
layout-docbook/x109.htm
layout-docbook/x120.htm
layout-docbook/x125.htm
layout-docbook/x150.htm
layout-docbook/x155.htm
layout-docbook/x36.htm
layout-docbook/x39.htm
layout-docbook/x44.htm
layout-docbook/x47.htm
layout-docbook/x55.htm
layout-docbook/x59.htm
layout-docbook/x64.htm
layout-docbook/x79.htm
layout-docbook/x82.htm
layout-docbook/x84.htm

laydb.tgz
Description: application/compressed

layout.rtf
Description: MS-Word document