RE: [Groff] Newbie help for documenting code snippets

[Ted Harding]

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.
> 
> He usually has a numbered block of code demarcated by two lines.
> Following this is a para with the relevent line numbers set off in the
> left margin.
> 
> I have not been able to create this "effect".
> 
> Could someone please guide me.
> Specific help would be very helpful, considering my limited
> backgrounding in groff.
> 
> PS: I am reading the UTP document; but it is very slow progress.
> 
> - mahesh

Hi Mahesh,
Clarke Echols suggests using 'nl' which is a UNIX utility to
prepend line numbers when a file is read out to standard output.
You could use this to create a file of code segments with
line-numbers which can then be read into groff. However, you
would have to be careful, in using 'nl', to ensure that it
prepended the line numbers you wanted.

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

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

.nr ln 1
.de code
.ft CR
.sp 1n
.br
.nf
.in +1c
.nm +0 1 1 -5
..
.de /code
.br
.sp 1n
.nm
.fi
.ft
.in
..
.LP
This is a sample of line-numbered C code.
.code
#include <stdio.h>
main()
{ fprintf(stdout,"%s","Good morning, World") }
./code
.LP
That was a sample of line-numbered C code.
This is another sample of line-numbered C code.
.code
#include <stdio.h>
main()
{ fprintf(stdout,"%s","Goodnight World") }
./code
.LP
The above were samples of line-numbered C code.

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

This gives each successive block of code line numbers
which follow on incrementally from the line numbers of
the preceding block. If you want to start the numbering
in each block from 1 every time, then all you need to do
is move the line ".nr ln 1" so that it follows the line
".de code" instead of preceding it.

Hoping this helps,
Ted.


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