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

["Alan W. Irwin" <irwin@beluga.phys.uvic.ca>]

On 2010-11-23 19:34+0100 Mauritz Jeanson wrote:

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

We don't use refentry at the moment, but thanks for pointing me to that
possibility that sounds promising.

> But if you're happy with the Perl script, then it seems fine to just
> continue using it IMHO.

No current developer in our project understands that perl script so we
are looking for alternatives.  I have just had a closer look at
docbook2x (which we currently use to create our info pages). There is
also a mode for it that creates man pages.  So I will try that as an
alternative as well.  (The docbook2x FAQ recommends refentry for man
page generation as well.)

>
>
> |  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 :-).

Our reference was to the DocBook definitive guide.  It does have a
short Chapter on XSL which I am just starting to read, but thanks for
giving me that additional XSL reference which I was unaware of. I feel
a bit like Rip Van Winkle since it has been years since I have even
looked at the DocBook (DSSL) backends, and I currently have little or
no knowledge of XSL.  Thus, I would very much appreciate you expanding
a bit more on this XSL subject.  :-)

A quick skim seems to indicate the above reference only deals with the
html and pdf case.  What about dvi and PostScript? Do we have to
give those up if we switch to XSL?

Also, the above reference (published in 2007) mentions three
open-source possibilities for the XSL-FO processor (FOP, PassiveTeX,
and xmlroff) and seemed to lean toward FOP in terms of the example he
used later.  Is FOP the open-source XSL-FO processor you would
recommend now?

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

Thanks very much for remarks concerning DSSL. Our current DSSL system
works fairly well but has some nagging issues.  It appears those
issues will not get fixed, and I am sure this situation will get worse
as our documentation needs evolve.  So I think it is inevitable we
switch to XSL sometime fairly soon at least for our documentation
backend needs that cannot be handled by docbook2x.

Alan
__________________________
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
(lbproject.sf.net).
__________________________

Linux-powered Science
__________________________