Lines in a program's comment block usually start with one or more special characters, like:
line 1 of the comment#
line 2 of the comment#
line 3 of the comment...
It can be a hassle to add more text to one of the comment lines in a block because the line can get too long, which requires you to fold that line onto the next line, which means you have to work around the leading comment character(s).
Theprogram neatens lines of a text file. But the standard fmt won't help you "neaten" blocks of comments in a program: it mixes the comment characters from the starts of lines with the words. (If your fmt has the -p option, it handles this problem; there's an example below.) The recomment script is fmt for comment blocks. It's for people who write shell, awk, C, or almost any other kind of program with comment blocks several lines long.
recomment reads the lines that you feed its standard input.
It looks at the first line and figures out what characters you're using
to comment the line (see the |
I usually use recomment from inside vi, withcommands like:
!}recomment reformat to the next blank line 5!!recomment reformat this line and the next 4
Normally, recomment lets fmt choose the width of the comment block (72 characters, typically). To get another width, you can either:
Give the width on the command line, like this:
Set an environment variable named CBLKWID. Give the maximum width, in characters, for the comment text. For example, in the C shell, use:
setenv CBLKWID 50
recomment isn't perfect, but it's usually much better than nothing! Here's the part of the script that does the work. The first two commands get the comment character(s) and count their length. The next three commands strip the comment characters, clean up the remaining comment text, and add the same comment characters to the start of all reformatted lines:
# GET COMMENT CHARACTERS USED ON FIRST LINE; STORE IN $comment: comment="`sed -n \"1s/^\([$cchars]*\).*/\1/p\" $temp`" # GET NUMBER OF CHARACTERS IN COMMENT CHARACTER STRING: cwidth=`expr "$comment" : '.*'` # RE-FORMAT THE COMMENT BLOCK. IF $widopt SET, USE IT: colrm 1 $cwidth < $temp | # STRIP OFF COMMENT LEADER FROM LINES fmt $widopt | # RE-FORMAT THE TEXT, AND sed "s/^/$comment/" # PUT THE COMMENT CHARACTERS BACK
cut -c`expr $cwidth + 1`- < $temp | # STRIP OFF COMMENT LEADER
That makes a command like
cut -c4- instead of
colrm 1 3.
Some versions of fmt (like the one on the CD-ROM) have
a -p option that does the same thing.
Unlike the automatic system in recomment, you have to tell
fmt -p what the prefix characters are.
For example, here's the start of a C program.
The prefix character is
cat prog.c/* * This file, load.cc, reads an input * data file. * Each input line is added to a new node * of type struct Node. */ %
fmt -p '*' prog.c/* * This file, load.cc, reads an input data file. Each input line is * added to a new node of type struct Node. */