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

[Peter Karman <karman@cray.com>]

Michael Smith scribbled on 7/22/05 9:15 AM:

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

I use them too.[1] But at you point out, they seem a little out of place in man 
pages.[2]


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


I have to amend what I said about support in docbook-to-man; the content of a 
footnote tag is simply output inline where it appears. So it's "supported" in 
the sense that the text is output, but not cleverly supported.[3]


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

I guess it depends on what you mean by embed. We have a macro definition file, 
similar to the -man and -mandoc sheets. I just use that instead of one of the 
man macro sheets, and use the Cray macros instead of the man macros in the roff 
output from docbook-to-man. They're very similar (man macros and Cray macros), 
except for tables and lists.

Example of Cray table macros. You can probably grok that CD is a cell, CT is a 
header cell, etc. Each cell is assigned to a column and can be aligned left, 
right, center, etc.

.TT
\fB\fB-h pragma\fP Directive Processing\fR
.TS 0
.CW 1.34 1.55 2.25
.CT 1 l
\fIname\fP
.CT 2 l
Group
.CT 3 l
Directives affected
.CD 1 l
\fBall\fP
.CD 2 l
All
.CD 3 l
All directives
.CD 1 l
\fBallinline\fP
.CD 2 l
Inlining
.CD 3 l
\fBinline\fP, \fBnoinline\fP
.CD 1 l
\fBallscalar\fP
.CD 2 l
Scalar optimization
.CD 3 l
\fBconcurrent\fP, \fBnointerchange\fP, \fBnoreduction\fP, \fBsuppress\fP, 
\fBunroll\fP
.CD 1 l
\fBallvector\fP
.CD 2 l
Vectorization
.CD 3 l
\fBivdep\fP, \fBnovector\fP, \fBnovsearch\fP, \fBprefervector\fP, \fBshortloop\fP
.TE


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


Ah, yes. I thought that's what you meant originally, then re-interpreted.

Our set up is simple: one file = one refentry = one man page. We did collect 
groups of man pages into collections (say, all the man8 files) using the 
Reference tagset, but that was for PDF only. We've stopped doing that due to low 
(non-existent) customer demand. Instead we provide "virtual" HTML collections 
via CrayDoc.


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

there is some limited "follow" support in docbook-to-man for resolving things 
like xrefs, etc. It's not nearly as robust as the DOM, but it works well enough.

pek



[1] I was a history major. What can I say?

[2] Perl man pages might be an exception. All the funny bits are in the footnotes.

[3] Cleverness is the real object of programming, isn't it? ;)

-- 

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