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

[Paul DuBois <paul@kitebird.com>]

I've tried the new release a bit, and am pleased to note the changes that
result in much reduced runs of blank lines in the output.  I do note one
problem, which was also present in earlier releases: Sometimes
<refsection><title>... does not result in an .SH macro in the output.  But
this is sporadic and I have not found a pattern, so I do not yet have a good
test case to provide.

My main difficulty with the manpages stylesheet actually stems from the
stylesheet itself but with the DocBook DTD.  I have a long reference manual
that contains some sections that describe programs and how to invoke them.
That is, these sections have content from which I want to produce manpages.
(The source document is dual purpose: I want to generate both the long
manual, and also a set of manpages.)

Unfortunately, several of these program-description sections occur at the
same "level" and in the same chapter as non-manpage sections.  It appears
that the DocBook DTD doesn't allow <section> and <refentry> to occur at the
same level within the same parent.  That means I cannot markup the
program-description sections to use <refentry> rather than <section>.

Some options that occur to me:  1) Restructure the document so that
<refentry> never occurs within the same parent as <section>; 2) At manpage
generation time, extract the relevant program-description <section> elements
and map them onto <refentry> markup before processing with the manpage
stylesheet.

I'm not so keen on 1) because everyone who works on this document would have
to know about the constraint against mixing <section> and <refentry> and be
careful to respect it.  On the other hand, 2) is not so attractive, either,
because <section> and <refentry> are different enough that it's not obvious
(to me, anyway) how to use <section> markup to represent the info I'd need
to pull out for the <refmeta>, <refnamediv>, and <refsynopsisdiv> elements.

I'm curious whether anyone else has faced a similar situation and how you
approached it.


On 7/19/05 5:33, "Michael Smith" <smith@xml-doc.org> wrote:

> 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_MA>
N
> 
> 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