VGRIND(1)VGRIND(1)NAMEvgrind - grind nice program listings
SYNOPSISvgrind [-2fntwx] [-d defs-file] [-h header] [-l language]
[-s n] [-o pagelist] [-P printer] [-T output-device] filename...
DESCRIPTION
The vgrind utility formats the program sources named by the filename
arguments in a nice style using troff(1). Comments are placed in ital‐
ics, 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 stan‐
dard 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 fil‐
ter can be passed to troff for output. There need be no particular
ordering with eqn(1) or tbl(1).
In regular mode, vgrind accepts input filenames, processes them, and
passes them to troff for output. Use a hyphen (`−') to specify standard
input; otherwise, vgrind will exit without attempting to read from the
standard input. Filenames must be specified after all other option
arguments.
In regular mode, if the -t or -P option is specified, the output is:
o emitted (in troff format) to stdout if the -t option is
specified.
o printed (as PostScript) to the named printer if the -P
option is specified.
Otherwise, the output is:
o printed (as PostScript) on the system default printer, if
one is defined, and the command's stdout is a tty.
o emitted (as PostScript) to stdout if it is not a tty (that
is, if stdout is a pipe or a redirect to a file).
In both modes, vgrind passes any lines beginning with a decimal point
without conversion.
OPTIONS
The following options are supported:
-2
Produces two-column output. Specifying this option
changes the default point size to 8 (as if the -s8
option were supplied). It also arranges for output to
appear in landscape mode.
-f
Forces filter mode.
-n
Does not make keywords boldface.
-w
Considers TAB characters to be spaced four columns
apart instead of the usual eight.
-x
Outputs the index file in a "pretty" format. The index
file itself is produced whenever vgrind is run with a
file called index that is present in the current direc‐
tory. The index of function definitions can then be run
off by giving vgrind the -x option and the file index
as argument.
-d defs-file
Specifies an alternate language definitions file
(default is /usr/lib/vgrindefs).
-h header
Specifies a header to appear in the center of every
output page. Use quotes to specify headers with embed‐
ded spaces.
-l language
Specifies the language to use. Among the languages cur‐
rently known are: Bourne shell (-lsh), C (-lc, the
default), C++ (-lc++), C shell (-lcsh), emacs MLisp
(-lml), FORTRAN (-lf), Icon (-lI), ISP (-i), LDL
(-lLDL), Model (-lm), Pascal (-lp), and RATFOR (-lr).
-P printer
Sends output to the named printer.
-s n
Specifies a point size to use on output (exactly the
same as the argument of a troff .ps point size
request).
vgrind passes the following options to the formatter specified by the
TROFF environment variable. See ENVIRONMENT VARIABLES.
-t
Similar to the same option in troff; that is, for‐
matted text goes to the standard output.
-o pagelist
Prints only those pages whose page numbers appear
in the comma-separated pagelist of numbers and
ranges. A range N−M means pages N through M; an
initial -N means from the beginning to page N; and
a final N− means from N to the end.
-T output-device
Formats output for the specified output-device.
OPERANDS
The following operand is supported:
filename
Name of the program source to be processed by vgrind. Use
`−' to specify the standard input.
ENVIRONMENT VARIABLES
In regular mode, vgrind feeds its intermediate output to the text for‐
matter given by the value of the TROFF environment variable, or to
/usr/bin/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/share/lib/tmac/tmac.vgrind
macro package
SEE ALSOcsh(1), ctags(1), eqn(1), tbl(1), troff(1), attributes(5), vgrindefs(5)BUGSvgrind assumes that a certain programming style is followed:
C
Function names can be preceded on a line only by SPACE, TAB,
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 key‐
words 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 key‐
words is beginproc.
Pascal
Function names need to appear on the same line as the key‐
words function or procedure.
If these conventions are not followed, the indexing and marginal func‐
tion name comment mechanisms will fail.
More generally, arbitrary formatting styles for programs usually give
unsightly results. To prepare a program for vgrind output, use TAB
rather than SPACE characters to align source code properly, since
vgrind uses variable width fonts.
The mechanism of ctags(1) in recognizing functions should be used here.
The -w option is annoying, but there is 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 effec‐
tively.
vgrind does not process certain special characters in csh(1) scripts
correctly.
The tmac.vgrind formatting macros wire in the page height and width
used in two-column mode, effectively making two column output useless
for paper sizes other than the standard American size of 8.5 inches by
11 inches. For other paper sizes, it is necessary to edit the size val‐
ues given in tmac.vgrind. A better solution would be to create a troff
output device specification intended specifically for landscape output
and record size information there.
Mar 3, 2000 VGRIND(1)
