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] | [List Home]

Subject: Need recommendations for the best modern Linux backend tools forDocBook

The PLplot project has been using DocBook XML for years, but our
choice of backend tools was made a decade ago so presumably some of
those backend tools have been superseded by better choices now.  Thus,
I would appreciate your recommendations concerning the best such tools
(for a Linux platform).

Here is what we currently use:

1.  man pages.

Our man pages are generated with a home-brew perl script. That script
uses XML::DOM::Parser to parse the combination of plplotdoc.xml (The
core file where our entities are defined) and api.xml (the subset of
our DocBook source files which describes our core library's API) to
obtain the information used to generate the man pages.

2. info pages.

Our info pages are generated by a combination of

info-clean.pl --> db2x_xsltproc --> db2x_texixml --> makeinfo

where info-clean.pl is a home-brew perl script required (as far as I
can tell from reading comments in it) to work around some of the
db2x_xsltproc limitations. db2x_xsltproc and db2x_texixml are from the
docbook2x package.  I am not sure whether some/all of those perl
script workarounds are necessary for the most recent release of
docbook2x (which occurred in 2007).

3. web pages.

Our web pages are generated with openjade.

4. dvi file

Our dvi documentation file is generated by

openjade --> jadetex

5. PostScript file

Our PostScript documentation file is generated from the above dvi file
using dvips.

6. pdf file

openjade --> pdfjadetex

I have not paid much attention to these backend tools and certainly do
not have much expertise in them or the perl scripts (the choice of
backend and the perl scripting was done by somebody else who has since
retired from the PLplot project), but I do want to be sure we are
using the best Linux DocBook backend tools to generate the various
forms of PLplot documentation.

For the man pages (1.) I have already found via a google search a 
discussion of xslproc + docbook-xsl/manpages/docbook.xsl which sounded
promising.  Is there a way using that technique to exclude large parts
of our documentation that is in chapter form rather than a description
of our API (the only part of our DocBook documentation we want to
appear in manpage form)?  Or does that exclusion happen automatically?

From the above list of backend tools, openjade is used to help
generate html, dvi, PostScript, and PDF documentation results. I have
recently noticed that openjade (for our particular command-line
arguments at least) chokes on UTF-8 in the DocBook source. Before
investigating that issue further, I want to be sure that openjade
(whose last release was in 2003) is the definitive choice for all the
use cases above so I hope especially that somebody will comment on

Alan W. Irwin

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the FreeEOS equation-of-state implementation
for stellar interiors (freeeos.sf.net); PLplot scientific plotting software
package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of
Linux Links project (loll.sf.net); and the Linux Brochure Project

Linux-powered Science

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