OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

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, 

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:


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.



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]