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

[Jon Snader]

On Wed, Jan 12, 2005 at 11:31:05AM -0000, mahesh wrote:
>   
> 
> 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.
> 

I've never had any problems with loom.  Just compile it, add the
headers in the source code and it just runs.  Where are you
having a problem?

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

Sort of.  What happens is loom is run first and its output is piped
into groff.  Here's the relevant line from the makefile for my
latest book:

%.ps: %.t
    @$(LOOM) $(MACS) $< | $(PS) > $@

LOOM contains the path to loom, MAC a list of macro files to
include (picture macros, my own non-ms macros, etc), and PS
contains a call to groff along the lines of

PS = groff -U -pRset

The line numbers in the source code file are generated with the
.nm command.

Here's the actual markup that includes a file called sslecho.c

.Ls sslecho.c 50
%include src/sslecho.c echo | bin/reformat
.Le "An SSL-aware Echo Server (\fCecho\fP)" ssl-sslecho-echo

The .Ls and .Le macros begin and end the code block as I
described in my last post.

Here are the Ls and Le macros:

.de Ls          \" Code begin
.L1 0 \\$1
.ie \\n(.$>1 .nm \\$2
.el .nm 1
..
.de Le          \"Code end
.nm
.L2
.sp .75v
.Fg \\$@
..

The L1 and L2 macros draw the lines.  The Fg macro adds the
figure caption.

You're correct that the C code is imported directly into the
troff document--that's what loom does.  The advantage of this is
that the documentation and code *always* match.  You don't have
to worry about typos or the like.

jcs