path: root/usr/src/man/man1/vgrind.1

'\" te
.\" Copyright (c) 1980 Regents of the University
.\" of California.  All rights reserved.  The Berkeley software License Agreement
.\"  specifies the terms and conditions for redistribution.
.\" Copyright (c) 2000, Sun Microsystems, Inc.
.\"  All Rights Reserved
.TH VGRIND 1 "Mar 3, 2000"
.SH NAME
vgrind \- grind nice program listings
.SH SYNOPSIS
.LP
.nf
\fBvgrind\fR [\fB-2fntwx\fR] [\fB-d\fR \fIdefs-file\fR] [\fB-h\fR \fIheader\fR] [\fB-l\fR \fIlanguage\fR]
     [\fB-s\fR \fIn\fR] [\fB-o\fR \fIpagelist\fR] [\fB-P\fR \fIprinter\fR] [\fB-T\fR \fIoutput-device\fR] \fIfilename\fR...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBvgrind\fR utility formats the program sources named by the
\fIfilename\fR arguments in a nice style using \fBtroff\fR(1). Comments are
placed in italics, keywords in bold face, and as each function is encountered
its name is listed on the page margin.
.sp
.LP
\fBvgrind\fR runs in two basic modes, filter mode or regular mode. In filter
mode, \fBvgrind\fR acts as a filter in a manner similar to \fBtbl\fR(1). The
standard input is passed directly to the standard output except for lines
bracketed by the \fBtroff\fR-like macros:
.sp
.ne 2
.na
\fB\fB\&.vS\fR\fR
.ad
.RS 9n
starts processing
.RE

.sp
.ne 2
.na
\fB\fB\&.vE\fR\fR
.ad
.RS 9n
ends processing
.RE

.sp
.LP
These lines are formatted as described above. The output from this filter can
be passed to \fBtroff\fR for output. There need be no particular ordering with
\fBeqn\fR(1) or \fBtbl\fR(1).
.sp
.LP
In regular mode, \fBvgrind\fR accepts input \fIfilename\fRs, processes them,
and passes them to \fBtroff\fR for output. Use a hyphen (`\fB\(mi\fR\&') to
specify standard input; otherwise, \fBvgrind\fR will exit without attempting to
read from the standard input. Filenames must be specified after all other
option arguments.
.sp
.LP
In regular mode, if the \fB-t\fR or \fB-P\fR option is specified, the output
is:
.RS +4
.TP
.ie t \(bu
.el o
emitted (in \fBtroff\fR format) to stdout if the \fB-t\fR option is specified.
.RE
.RS +4
.TP
.ie t \(bu
.el o
printed (as PostScript) to the named printer if the \fB-P\fR option is
specified.
.RE
.sp
.LP
Otherwise, the output is:
.RS +4
.TP
.ie t \(bu
.el o
printed (as PostScript) on the system default printer, if one is defined, and
the command's stdout is a tty.
.RE
.RS +4
.TP
.ie t \(bu
.el 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).
.RE
.sp
.LP
In both modes, \fBvgrind\fR passes any lines beginning with a decimal point
without conversion.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-2\fR\fR
.ad
.RS 16n
Produces two-column output. Specifying this option changes the default point
size to 8 (as if the \fB-s8\fR option were supplied). It also arranges for
output to appear in landscape mode.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 16n
Forces filter mode.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 16n
Does not make keywords boldface.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR\fR
.ad
.RS 16n
Considers TAB characters to be spaced four columns apart instead of the usual
eight.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 16n
Outputs the index file in a "pretty" format. The index file itself is produced
whenever \fBvgrind\fR is run with a file called \fBindex\fR that is present in
the current directory. The index of function definitions can then be run off by
giving \fBvgrind\fR the \fB-x\fR option and the file \fBindex\fR as argument.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR \fIdefs-file\fR\fR
.ad
.RS 16n
Specifies an alternate language definitions file (default is
\fB/usr/lib/vgrindefs\fR).
.RE

.sp
.ne 2
.na
\fB\fB-h\fR \fIheader\fR\fR
.ad
.RS 16n
Specifies a header to appear in the center of every output page. Use quotes to
specify headers with embedded spaces.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fIlanguage\fR\fR
.ad
.RS 16n
Specifies the language to use. Among the \fIlanguage\fRs currently known are:
Bourne shell (\fB-lsh\fR), C (\fB-lc\fR, the default), C++ (\fB-lc++\fR), C
shell (\fB-lcsh\fR), emacs MLisp (\fB-lml\fR), FORTRAN (\fB-lf\fR), Icon
(\fB-lI\fR), ISP (\fB-i\fR), LDL (\fB-lLDL\fR), Model (\fB-lm\fR), Pascal
(\fB-lp\fR), and RATFOR (\fB-lr\fR).
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIprinter\fR\fR
.ad
.RS 16n
Sends output to the named \fIprinter\fR.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIn\fR\fR
.ad
.RS 16n
Specifies a point size to use on output (exactly the same as the argument of a
\fBtroff\fR \fB\&.ps\fR point size request).
.RE

.sp
.LP
\fBvgrind\fR passes the following options to the formatter specified by the
\fBTROFF\fR environment variable. See ENVIRONMENT VARIABLES.
.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 20n
Similar to the same option in \fBtroff\fR; that is, formatted text goes to the
standard output.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIpagelist\fR\fR
.ad
.RS 20n
Prints only those pages whose page numbers appear in the comma-separated
\fIpagelist\fR of numbers and ranges. A range \fIN\(miM\fR means pages \fIN\fR
through \fIM\fR; an initial \fB-N\fR means from the beginning to page \fIN\fR;
and a final \fIN\fR\(mi means from \fIN\fR to the end.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fIoutput-device\fR\fR
.ad
.RS 20n
Formats output for the specified \fIoutput-device\fR.
.RE

.SH OPERANDS
.sp
.LP
The following operand is supported:
.sp
.ne 2
.na
\fB\fIfilename\fR\fR
.ad
.RS 12n
Name of the program source to be processed by \fBvgrind\fR. Use `\fB\(mi\fR\&'
to specify the standard input.
.RE

.SH ENVIRONMENT VARIABLES
.sp
.LP
In regular mode, \fBvgrind\fR feeds its intermediate output to the text
formatter given by the value of the \fBTROFF\fR environment variable, or to
\fB/usr/bin/troff\fR if this variable is not defined in the environment. This
mechanism allows for local variations in \fBtroff\fR's name.
.SH FILES
.sp
.ne 2
.na
\fB\fBindex\fR\fR
.ad
.sp .6
.RS 4n
file where source for index is created
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/vgrindefs\fR\fR
.ad
.sp .6
.RS 4n
language descriptions
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/vfontedpr\fR\fR
.ad
.sp .6
.RS 4n
preprocessor
.RE

.sp
.ne 2
.na
\fB\fB/usr/share/lib/tmac/tmac.vgrind\fR\fR
.ad
.sp .6
.RS 4n
macro package
.RE

.SH SEE ALSO
.sp
.LP
\fBcsh\fR(1), \fBctags\fR(1), \fBeqn\fR(1), \fBtbl\fR(1), \fBtroff\fR(1),
\fBattributes\fR(5), \fBvgrindefs\fR(5)
.SH BUGS
.sp
.LP
\fBvgrind\fR assumes that a certain programming style is followed:
.sp
.ne 2
.na
\fBC\fR
.ad
.RS 11n
Function names can be preceded on a line only by SPACE, TAB, or an asterisk
(\fB*\fR). The parenthesized arguments must also be on the same line.
.RE

.sp
.ne 2
.na
\fBFORTRAN\fR
.ad
.RS 11n
Function names need to appear on the same line as the keywords \fBfunction\fR
or \fBsubroutine\fR.
.RE

.sp
.ne 2
.na
\fBMLisp\fR
.ad
.RS 11n
Function names should not appear on the same line as the preceding \fBdefun\fR.
.RE

.sp
.ne 2
.na
\fBModel\fR
.ad
.RS 11n
Function names need to appear on the same line as the keywords \fBis
beginproc\fR.
.RE

.sp
.ne 2
.na
\fBPascal\fR
.ad
.RS 11n
Function names need to appear on the same line as the keywords \fBfunction\fR
or \fBprocedure\fR.
.RE

.sp
.LP
If these conventions are not followed, the indexing and marginal function name
comment mechanisms will fail.
.sp
.LP
More generally, arbitrary formatting styles for programs usually give unsightly
results. To prepare a program for \fBvgrind\fR output, use TAB rather than
SPACE characters to align source code properly, since \fBvgrind\fR uses
variable width fonts.
.sp
.LP
The mechanism of \fBctags\fR(1) in recognizing functions should be used here.
.sp
.LP
The \fB-w\fR option is annoying, but there is no other way to achieve the
desired effect.
.sp
.LP
The macros defined in \fBtmac.vgrind\fR do not coexist gracefully with those of
other macro packages, making filter mode difficult to use effectively.
.sp
.LP
\fBvgrind\fR does not process certain special characters in \fBcsh\fR(1)
scripts correctly.
.sp
.LP
The \fBtmac.vgrind\fR 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
\fBtmac.vgrind\fR. A better solution would be to create a \fBtroff\fR output
device specification intended specifically for landscape output and record size
information there.