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