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

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

Peter Karman <karman@cray.com> writes:

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

That is great to hear too.

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

I use footnotes a lot myself, so I wouldn't much like being told
to find another way :-) But I have to admit, I'm not sure I've
ever seen a man page that actually had footnotes of any kind.

That said, requiring that a DocBook document not contain Footnotes
also limits it to not containing footnotes in any other output
format as well (HTML, PDF, HTML Help, or whatever). I don't think
the content of a document ought to be hobbled to work around
current limitations in any particular output format. So I plan to
try to make the manpages stylesheet support any valid content that
the HTML and FO stylesheets support.

> You're right though: there's no support for it in
> docbook-to-man.

Yeah, as I mentioned, if it is doing stream-based processing of
documents, I'm not sure it could be made to handle Footnote.

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

That has been one of misgivings about going ahead with
implementing tables (using the tbl macros). It is doable, but I
have seen recommendations to avoid using tables at all in man
pages, because some programs, such as xman(1) may not be able to
handle them correctly. (But I am inclined to say, too bad for
those programs, because the tbl macros have been around for a long
time and any decent man-page renderer should be able to handle them.)

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

I see. So does that mean that you need to embed those macros in
each man page?

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

I think what you're referring to there is actually handling of an
individual Refentry that contains more that one Refname. Right?
That's the case in which stubs get generated. But I meant
something different, which is that if a document has the following:

  <reference>
    <refentry>
      ...foo
      <manvolnum>2</manvolnum>
    <refentry>
      ...bar
      <manvolnum>7</manvolnum>


Then, in that case, separate foo.2 and bar.7 files will be
generated. They will both have actual content (not just stubs).

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

OK, I hadn't tried it so wasn't sure. That makes me think it might
actually be able to handle Footnote as well.

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

Yeah, it's very annoying to me -- especially for pages that
contain a lot of links. For example, Sam Steingold's clisp(1) man
page contains more than 130 links. IMHO, it looks horrible if
those are all rendered inline.

> >    - 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. I will take a look.

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

And thank you for taking time to check out the 1.69.0 version and
comment on it.

  --Mike

smime.p7s