NAME

vgrind − grind nice program listings

SYNOPSIS

vgrind [−f] [−] [−t] [−n] [−x] [−W] [−w] [−sn] [−h header] [−d defs-file] [−llanguage] file ...

DESCRIPTION

Vgrind formats the program sources named by the file arguments in a nice style using troff(1). Comments are placed in italics, keywords in bold face, and as each function is encountered its name is listed on the page margin.

Vgrind runs in two basic modes, filter mode or regular mode.  In filter mode vgrind acts as a filter in a manner similar to tbl(1). The standard input is passed directly to the standard output except for lines bracketed by the troff-like macros:

.vS- starts processing

.vE- ends processing

These lines are formatted as described above.  The output from this filter can be passed to troff for output.  There need be no particular ordering with eqn(1) or tbl.

In regular mode vgrind accepts input files, processes them, and passes them to troff for output. 

In both modes vgrind passes any lines beginning with a decimal point without conversion. 

OPTIONS

Note that arguments to the −l and −s options follow the option names immediately, with no intervening space.  All other arguments and options must be separated with white space. 

−f Force filter mode. 

− Take from standard input (default if −f is specified). 

−t Similar to the same option in troff; that is, formatted text goes to the standard output.

−n Do not make keywords boldface. 

−x Output the index file in a ‘pretty’ format.  The index file itself is produced whenever vgrind is run with a file called index present in the current directory.  The index of function definitions can then be run off by giving vgrind the −x option and the file index as argument. 

−W Force output to the (wide) Versatec printer rather than the (narrow) Varian. 

−w Consider tabs to be spaced four columns apart instead of the usual eight. 

−s Specifies a point size to use on output (exactly the same as the argument of a troff ‘.ps’ point size request). 

−h Specifies a particular header to put on every output page (default is the current file name). 

−d Specifies an alternate language definitions file (default is /usr/lib/vgrindefs).

−l Specifies the language to use.  Among the languages currently known are: Bourne shell (−lsh), C (−lc, the default), C-shell (−lcsh), emacs MLisp, (−lml), FORTRAN (−lf), Icon (−lI), ISP (−i), LDL (−lLDL), Model (−lm), Pascal (−lp), and RATFOR (−lr). 

ENVIRONMENT

In regular mode vgrind feeds its intermediate output to the text formatter given by the value of the TROFF environment variable, or to ‘troff’ if this variable is not defined in the environment.  This mechanism allows for local variations in troff’s name.

FILES

index file where source for index is created

/usr/lib/vgrindefs language descriptions

/usr/lib/vfontedpr preprocessor

/usr/lib/tmac/tmac.vgrind macro package

SEE ALSO

troff(1), vgrindefs(5)

BUGS

Vgrind assumes that a certain programming style is followed:

C Function names can be preceded on a line only by spaces, tabs, or an asterisk.  The parenthesized arguments must also be on the same line. 

FORTRAN Function names need to appear on the same line as the keywords function or subroutine.

MLisp Function names should not appear on the same line as the preceding defun.

Model Function names need to appear on the same line as the keywords is beginproc.

Pascal Function names need to appear on the same line as the keywords function or procedure.

If these conventions are not followed, the indexing and marginal function name comment mechanisms will fail. 

More generally, arbitrary formatting styles for programs mostly look bad.  The use of spaces to align source code fails miserably; if you plan to vgrind your program you should use tabs.  This is somewhat inevitable since the fonts vgrind uses are variable width. 

The mechanism of ctags(1) in recognizing functions should be used here.

The −w option is a crock, but there’s no other way to achieve the desired effect. 

The macros defined in tmac.vgrind do not coexist gracefully with those of other macro packages, making filter mode difficult to use effectively. 

Sun Release 3.2  —  Last change: 11 July 1986