VGRIND(1) General Commands Manual VGRIND(1)NAME
vgrind - grind nice listings of programs
SYNOPSIS
vgrind [ -f ] [ - ] [ -t ] [ -n ] [ -x ] [ -W ] [ -sn ] [ -h header ] [ -d file ] [ -llanguage ] name ...
DESCRIPTION
Vgrind formats the program sources which are arguments in a nice style using troff(1) Comments are placed in italics, keywords in bold
face, and the name of the current function is listed down the margin of each page as it is encountered.
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 files, processes them, and passes them to troff(1) for output.
In both modes vgrind passes any lines beginning with a decimal point without conversion.
The options are:
-f forces filter mode
- forces input to be taken from standard input (default if -f is specified )
-t similar to the same option in troff causing formatted text to go to the standard output
-n forces no keyword bolding
-x outputs the index file in a ``pretty'' format. The index file itself is produced whenever vgrind is run with a file called index 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 forces output to the (wide) Versatec printer rather than the (narrow) Varian
-s specifies a point size to use on output (exactly the same as the argument of a .ps)
-h specifies a particular header to put on every output page (default is the file name)
-d specifies an alternate language definitions file (default is /usr/share/misc/vgrindefs)
-l specifies the language to use. Currently known are PASCAL (-lp), MODEL (-lm),C (-lc or the default), CSH (-lcsh), SHELL (-lsh),
RATFOR (-lr), MODULA2 (-lmod2), YACC (-lyacc), ISP (-lisp), and ICON (-lI).
FILES
index file where source for index is created
/usr/share/tmac/tmac.vgrindmacro package
/usr/libexec/vfontedprpreprocessor
/usr/share/misc/vgrindefslanguage descriptions
AUTHOR
Dave Presotto & William Joy
SEE ALSO vlp(1), vtroff(1), vgrindefs(5)BUGS
Vfontedpr assumes that a certain programming style is followed:
For 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.
For PASCAL - function names need to appear on the same line as the keywords function or procedure.
For MODEL - function names need to appear on the same line as the keywords is beginproc.
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 font used by vgrind is variable width.
The mechanism of ctags in recognizing functions should be used here.
Filter mode does not work in documents using the -me or -ms macros. (So what use is it anyway?)
4th Berkeley Distribution October 22, 1996 VGRIND(1)
Check Out this Related Man Page
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 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
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 stan-
dard 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 sup-
plied). 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
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Availability |SUNWdoc |
+-----------------------------+-----------------------------+
SEE ALSO csh(1), ctags(1), eqn(1), tbl(1), troff(1), attributes(5), vgrindefs(5)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 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
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.
SunOS 5.11 3 Mar 2000 vgrind(1)