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

[Meg McRoberts]

Does loom handle the \n problem in code as well?
Perhaps that is only an issue for the -mm macros,
but I spent years writing developer documentation
in the -mm macros and variants thereof and \n was
the bane of my existence!  It turned into \0 on
output unless I modified the actual line of code.

meg

--- Jon Snader <address@hidden> wrote:

> 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
> 
> 
> _______________________________________________
> Groff mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/groff
>