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

[mahesh]

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

Ah Good !

I was infact intending to write to you.
I am glad you are here on this list.

Yes. I was able to use your macros.
But i think there are pieces missing in the puzzle.
And am only a beginner. Hence the difficulty.

Reg. loom, I didn't understand how to use it (even after reading the man page).
Now my understanding is, i should place comments like the foll. in the .C file (say a.c)
    /* include mark1 */
    some code
    ...
    /* end mark1 */

and write this in the .t file
    %include a.c mark1

and loom will pull a copy of mark1 section into the .t


I seek a couple of clarifications,
1) .Ls sslecho.c 50
  Do i have to key in the '50'. Can loom help ?
  I mean if line 50 today were to become 51 tomorrow, then
  we go out of sync.

2) Could you help me with the .CP macro also.

One request.
Can this package/technique be made available through kohala please.
It is so very neat and useful.

- mahesh