Re: RE: [Groff] Newbie help for documenting code snippets

[Ted Harding]

On 12-Jan-05 mahesh wrote:
>   
> On Wed, 12 Jan 2005 Ted Harding wrote :
>>On 12-Jan-05 mahesh wrote:
>> > Hi all,
>> >
>> > I would like to generate documentation for some C code, along the
>> > lines
>> > of Richard Steven's books.
> ...
>> >
>>
>>Hi Mahesh,
> ...
>>
>>Within troff, you can use the ".nm" request to initiate numbering
>>of formatted lines. Since it can be a bit tricky to get the details
>>right, here is an example (based on "ms" macros since I've used
>>".LP" but it will work if ".LP" is changed for a different macro
>>set):
>>
> 
> That was very useful. Thanks. I spent sometime understanding it. (I
> wish there were more examples like this to guide newbies. )
> 'nl' too is quite OK with me.
> 
> The given macros more-or-less [see next para] takes care of the code
> block/snippet. Now, what do i need to do for the Steven's style
> descriptions. For each range of line numbers in a code snippet, the
> range a-b is left indented in italics, followed by the description with
> what looks like .PP. How is it done ?
> 
> My failed attempt was this:
> .po -0.5i
> .I
> 34-58
> .R
> This is the description for lines 34-58 ...
> 
> 
> Now, in the Preface to his books, Richard Stevens mentions using 'loom'
> and some awk scripts written by Gary Wright. I have got loom with me
> now, but can't get it to work. Could someone help me on this, if its
> not off-topic.
> 
> Moreover, i feel much of it would have been automated, i/e, Stevens
> must have had a 'C' file, in which he places markers (?) and loom
> slurps them into the troff doc. Perhaps the italicized a-b lines were
> also somehow automated. Thus the documentation refers to the *actual*
> code.
> 
> There is no info. on this at kohala.com.
> I hope it isn't a lost art.
> 
> - mahesh

The references to "loom" and "awk scripts" have to do with the
way the text (troff source) is created,, rather than with the
troff formatting techniques as such. I don't have access to
these at the moment, so I cannot comment. However, I will try
to dig deeper around the kohala site and see what I can find.

Regarding the specific troff technique to achieve the effect
you described, I have written a little piece which emulates
the appearance of one of his examples, namely the text at the
bottom of page 311 of the extract

  http://www.kohala.com/start/unpv22e/unpv22e.chap12.pdf

Here it is. It uses two macros: ".cdwds" to print code words
in Courier Bold, and ".cdcmt" to introduce a "code comment"
in the way described (line number range in Courier Italic,
offset to the left, reduced font size, followed by paragraph
indent).

============================================================

.de cdwds
\f[CB]\\$1\fP\\$2
..
.de cdcmt
.PP
\f[CI]\s-2\h'-\\n[PI]u-\w'\\$*\0'u'\\$*\0\s0\fP\h'\\n[PI]u'\c
..
.LP
.cd fork
.cdcmt 20-34
We set standard output unbuffered and call
.cdwds fork .
The parent and child both increment the integer counter
pointed to by
.cdwds ptr .
.PP
Memory-mapped files are handled specially by
.cdwds fork ,
in that memory mappings created by the parent
before calling
.cdwds fork
are shared by the child.
\(el

============================================================

The use of $1 and $2 in ".cdwds" is to ensure that any
punctuation immediately follows the end of the code.
Therefore, to use ".cdwds" with several words, you should
enclose these in "..." to make them into a single argument,
e.g.

.cdwds "main(int argc, char **argv)" ;

Best wishes,
Ted.


--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Fax-to-email: +44 (0)870 094 0861  [NB: New number!]
Date: 12-Jan-05                                       Time: 14:16:01
------------------------------ XFMail ------------------------------