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

[Michael Smith <smith@xml-doc.org>]

Hi Peter,

You wrote:

> Thanks for alerting me to this update. We have been authoring
> our man pages in DocBook XML here at Cray for over 4 years

Great to hear that. I've added a note to the WhoUsesDocBook page
at the DocBook Wiki -

  http://wiki.docbook.org/topic/WhoUsesDocBook

(I hope that's not a problem. If it is, please let me know and I
will remove it or edit it in any way you want.)

[...]

> 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 have not used docbook-to-man much. I know it's way faster than
the docbook-xsl manpages stylesheet. (I'll reply about the speed
issue in another message.) But I'd question whether it provides
the same functionality. There are a great many things that the
manpages stylesheet does[1] that docbook-to-man doesn't, or even
can't do (at least based on what I know about it).

And I would guess that in order to get usable output from
docbook-to-man, you might be constraining yourself and your
authors to a subset of elements, not the complete set of elements
that DocBook says are valid in Refentry. For example, can your
authors use Xref and Ulink in documents destined for man-page
output? Can they use Footnote? Are there any elements that your
authoring guidelines are telling them to specifically avoid
because they cannot be processed by docbook-to-man?

  --Mike

[1]I think that docbook-to-man supports conversion of DocBook
   tables, which the manpages XSL stylesheet does not yet. But
   there are a few other things that the manpages stylesheet does
   that, as far as I know, docbook-to-man does not.

     - Synopsis handling. Below is an example of a synopsis in a man
       page generated using the manpages stylesheet.

       clisp [[-h] [--help]] [--version] [--license] [-B lisp-lib-dir]
             [-K linking-set] [-M mem-file] [-m mem-size] [-t temp-dir]
             [-L language] [-N locale-dir] [-Edomain encoding] [[-q] [--quiet]
             [--silent] [-v] [--verbose]] [-on-error action] [-repl] [-w] [-I]
             [[-ansi] [-traditional]] [-modern] [-p package] [-C] [-norc]
             [-i init-file...] [-c [-l] lisp-file [-o output-file]...]
             [-x expressions...] [lisp-file [argument...]]

       And below is the synopsis in the same man page when I set my
       MANWIDTH to 65.

       clisp [[-h] [--help]] [--version] [--license]
             [-B lisp-lib-dir] [-K linking-set] [-M mem-file]
             [-m mem-size] [-t temp-dir] [-L language]
             [-N locale-dir] [-Edomain encoding] [[-q]
             [--quiet] [--silent] [-v] [--verbose]]
             [-on-error action] [-repl] [-w] [-I] [[-ansi]
             [-traditional]] [-modern] [-p package] [-C]
             [-norc] [-i init-file...]
             [-c [-l] lisp-file [-o output-file]...]
             [-x expressions...] [lisp-file [argument...]]

       The manpages stylesheet automatically creates a hanging indent
       of the correct width and keeps the arguments together in such
       a way that they are not broken across lines. As far as I know,
       docbook-to-man can't do that, and no other Refentry-to-man
       system can either.

     - Handling of documents containing multiple Refentry instances.
       docbook-to-man is a filter that writes its output to standard
       out. The manpages stylesheet automatically generates files,
       with extensions based on the Manvolnum it finds for each
       Refentry. And if a document contains multiple Refentry
       instances, it automatically generates a separate man-page
       output file for each.

   I think a lot of users would consider those two features to be
   fundamental requirements of a usable Refentry-to-man system. (And
   for the record, they were features in the manpages stylesheet
   since long before I ever touched or even looked at the code
   myself, so I can't take credit for them).

   I have also recently added support for, or am planning to add
   support for,  some things that weren't supported correctly before:

    - Xref. Display of contents of Xref is now handled in exactly
      the same way as the HTML stylesheets handle it, except no
      hyperlink is generated. That is, if you put in an Xref to
      another Section in a document, the title of that Section is
      picked up and used as the output for the Xref.

    - Links. Because there is no way in man-page output to
      generated real hyperlinks, I added a mechanism for listing
      URLs for all links at the end of the man page, and
      optionally numbering each link and generating a matching
      number in the link list.

    - Footnotes. I am planning to handle Footnote similar to the
      way that links are handled. Currently the manpages
      stylesheet correctly generates a Footnote number, but does
      nothing with the actual Footnote content.

    - Tables. This one will be some work, but it is not such a big
      technical challenge. I just need to time to get it done.

smime.p7s