VGRIND(1) User Commands VGRIND(1)
NAME
vgrind - grind nice program listings
SYNOPSIS
vgrind [
-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 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(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
directory. 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 embedded
spaces.
-l language Specifies the language to use. Among the
languages
currently 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,
formatted 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
formatter 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 ALSO
csh(1),
ctags(1),
eqn(1),
tbl(1),
troff(1),
attributes(7),
vgrindefs(7)BUGS
vgrind 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 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 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 effectively.
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 values
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.
March 3, 2000
VGRIND(1)