|
| 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 ... |
|
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:
- emitted (in troff format) to stdout if
the -t option is specified.
- printed (as PostScript) to the named printer if the -P option is specified.
Otherwise, the output is:
- printed (as PostScript) on the system default printer, if
one is defined, and the command's stdout is a tty.
- 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.
|
|
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.
|
|
The following operand is supported:
-
filename
- Name of the program source
to be processed by vgrind. Use `-'
to specify the standard input.
|
|
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.
|
|
-
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 attributes(5)
for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
Availability | SUNWdoc |
|
|
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.
|
| |