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