Re: [docbook-apps] Refentry, man pages, and DocBook XSL 1.69.0

[Peter Karman <karman@cray.com>]

Mike-

Thanks for alerting me to this update. We have been authoring our man pages in 
DocBook XML here at Cray for over 4 years, and I have experimented with the XSL 
driver before as way of generating *roff output.

I just tried the 1.69 version, and it is a nice improvement over previous 
versions. I'm glad to see it getting attention; the more the industry changes to 
XML man pages, the better, imho.

That said, for now we'll continue to use the docbook-to-man package for *roff 
conversion, though I'll be using XSL for HTML conversion. docbook-to-man 
(originally by Fred Dalrymple and now under the Debian umbrella) is 3-4x faster 
than the XSL, and provides the same functionality. I've modified the Debian 
version to work with XML (originally it was SGML only).

I'd be interested in any ideas about the speed difference; I assume it's because 
docbook-to-man doesn't use the DOM and just streams (using OpenSP and a 
stylesheet transformer called Instant).

Thanks again for your work.

pek

Michael Smith wrote on 07/19/2005 05:33 AM:
> A personal request: If you have time and interest, please download
> and try the "manpages" stylesheet in the DocBook XSL 1.69.0
> release, within the next two weeks (before 2005-08-02).
> 
> The manpages stylesheet supports transformation of the contents of
> the Refentry element to traditional Unix man pages (groff/nroff).
> 
> You can try it by using the manpages/docbook.xsl driver instead of
> the HTML or PDF driver; like this
> 
>   xsltproc manpages/docbook.xsl myfile.xml
>     or
>   java com.icl.saxon.StyleSheet myfile.xml manpages/docbook.xsl
> 
> There are a few more details in Bob Stayton's book -
> 
>   http://www.sagehill.net/docbookxsl/RefentryToMan.html
> 
> If you have already been using the manpages stylesheet prior to
> this release, I'd like to ask that you try the 1.69.0 version as
> soon as possible, and report back on any problems you find.
> 
> I'd also like to ask you to consider trying it if you meet any of
> the following descriptions:
> 
>   - you have Refentry content for which you are currently
>     generating HTML and/or PDF output, but have never tried
>     to generate man-page output
> 
>   - you have tried the manpages stylesheet in the past but found
>     the output from it did not meet your needs or expectations
> 
>   - you are currently maintaining manpages that you've created or
>     generated using a non-DocBook-XSL mechanism; for example,
>     docbook2X or some older docbook-to-man system
> 
> Major improvements and changes were made for the 1.69.0 release.
> The changes are detailed in the 1.69.0 release notes:
> 
>   http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html#V1690_MAN
> 
> It closes out 44 bug reports and feature requests and adds more
> than 35 new configuration parameters (for controlling hyphenation
> and justification, handling of links, conversion of Unicode
> characters, and "tuning" contents of man-page headers and footers).
> 
> The documentation for the new parameters is here:
> 
>   http://docbook.sourceforge.net/release/xsl/current/doc/manpages/
> 
> If you have already been using the manpages stylesheet, it is
> quite possible that this release breaks some of the behavior you
> are currently expecting. I have tried to be very thorough about
> documenting the rationale for all changes; so, for details, please
> see the parameter documentation above, as well as the
> manpages/ChangeLog file:
> 
>   http://docbook.sourceforge.net/release/xsl/current/manpages/ChangeLog
> 
> If find problems in the 1.69.0 release, please report them as soon
> as possible. I would like to get them all fixed within the next
> two weeks so that they can be included in the stable 1.69.1
> release targeted for 2005-08-02.
> 
> Thanks,
> 
>   --Mike

-- 

Peter Karman  .  http://docs.cray.com/  .  karman@cray.com

"I love deadlines.
  I love the whooshing sound they make as they go by."
         - Douglas Adams