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

[Peter Karman <karman@cray.com>]

Michael Smith scribbled on 7/22/05 6:37 AM:


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

No problem at all. We've actually been using SGML DocBook since 1995 to author 
our software manuals, added man pages in XML in 2001, and are right now 
transitioning to doing everything in XML.


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


Thanks for taking the time to pursue these questions.

We use xref and ulink freely in man pages. The catman output just generates 
text; the HTML output (which we publish to CrayDoc at http://docs.cray.com/) 
gives a real href link.

Footnote we have not used. IIRC, I've been asked about it once in 4 years, and I 
think my response was: find another way to write it. You're right though: 
there's no support for it in docbook-to-man.


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

docbook-to-man does do tables, but not very well -- or at least, the version we 
were using (Dalrymple's, not Debian's) did not. I hacked at it for several 
months, but part of the problem was groff's handling of tables, IIRC.

We had a fairly robust set of custom groff macros here that had been developed 
when we were authoring in nroff/troff, so I ended up redefining the transpec 
stylesheet to use Cray's macros, especially those for tables.


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

You're right; that's pretty sweet. The biggest issue for my writers is dealing 
with verbatims of all kinds, since HTML has no right margin but catman does. The 
synopsis in particular is irksome.


> 
>      - 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 actually found that feature to be a hindrance in our setup. It deals with 
multiple refentries by creating stub files, which I know is the standard 
GNU/groff way of dealing with that need. Cray had been doing it differently for 
many years, using symlinks instead of stub files because we do not ship our 
*roff source with our systems, only the catman files.

So you're right; it's a great feature for folks who are setting up a Refentry 
system for the first time. Our particular case was just different.


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

docbook-to-man does this.


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

docbook-to-man outputs the URL inline. That's a little annoying to my taste; I 
like your idea better.


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

That would be a nice option.


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

Tables are a real challenge. Especially nested tables, and tables inside lists 
(the latter we use a lot).

See http://docs.cray.com/man/CCm/54/cat1/CC.1.html as an example.

Thanks for all your work on this, Mike. It's great to see man page support 
coming along.

pek


-- 

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