RE: [docbook-apps] Need recommendations for the best modern Linux backend tools for DocBook

["Mauritz Jeanson" <mj@johanneberg.com>]

|  -----Original Message-----
|  From: Alan W. Irwin 
|  
|  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.

|  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?


Is the documentation that you want output as manpages written using
<refentry>? Then it will be amenable to processing by manpages/docbook.xsl.
But if you're happy with the Perl script, then it seems fine to just
continue using it IMHO.


|  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 that.


There's nothing wrong with DSSSL, but it is not a popular technology these
days. OpenJade is no longer maintained. The same holds for the DocBook DSSSL
stylesheets. 

I think you should look into XSL. And you already know about
http://www.sagehill.net/docbookxsl/index.html, judging by the link on
http://plplot.sourceforge.net/documentation.php, so there is no need for me
to expand on the subject :-). 

But then again, if your current documentation process works, then you might
want to avoid "fixing something that isn't broken" after all.

Mauritz