[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, > 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]