xref: /freebsd/usr.bin/vgrind/vgrind.1 (revision 06c3fb2749bda94cb5201f81ffdb8fa6c3161b2e)
1.\" Copyright (c) 1980, 1990, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd August 29, 2006
29.Dt VGRIND 1
30.Os
31.Sh NAME
32.Nm vgrind
33.Nd grind nice listings of programs
34.Sh SYNOPSIS
35.Nm
36.Op Fl
37.Op Fl W
38.Op Fl d Ar file
39.Op Fl f
40.Op Fl h Ar header
41.Op Fl l Ns Ar language
42.Op Fl n
43.Op Fl p Ar postproc
44.Op Fl s Ar pointsize
45.Op Fl t
46.Op Fl x
47.Ar name Ar ...
48.Sh DESCRIPTION
49The
50.Nm
51utility formats the program sources specified as arguments
52on the command line in a nice style using
53.Xr troff 1 Pq Pa ports/textproc/groff .
54Comments are placed in italics, keywords in bold face,
55and the name of the current function is listed down the margin of each
56page as it is encountered.
57.Pp
58The
59.Nm
60utility runs in two basic modes, filter mode (see the
61.Fl f
62option) or regular mode.
63In filter mode
64.Nm
65acts as a filter in a manner similar to
66.Xr tbl 1 .
67The standard input is passed directly to the standard output except
68for lines bracketed by the
69.Em troff-like
70macros:
71.Bl -tag -width Ds
72.It \&.vS
73starts processing
74.It \&.vE
75ends processing
76.El
77.Pp
78These lines are formatted as described above.
79The output from this
80filter can be passed to
81.Xr troff 1 Pq Pa ports/textproc/groff
82for output.
83There need be no particular ordering with
84.Xr eqn 1 Pq Pa ports/textproc/groff
85or
86.Xr tbl 1 Pq Pa ports/textproc/groff .
87.Pp
88In regular mode
89.Nm
90accepts input files, processes them, and passes them to the postprocessor
91for output,
92.Xr psroff 1
93by default.
94.Pp
95In both modes
96.Nm
97passes any lines beginning with a decimal point without conversion.
98.Pp
99The options are:
100.Bl -tag -width Ar
101.It Fl
102forces input to be taken from standard input (default if
103.Fl f
104is specified)
105.It Fl W
106forces output to the (wide) Versatec printer rather than the (narrow)
107Varian
108.It Fl d Ar file
109specifies an alternate language definitions
110file (default is
111.Pa /usr/share/misc/vgrindefs )
112.It Fl f
113forces filter mode
114.It Fl h Ar header
115specifies a particular header to put on every output page (default is
116the file name)
117.It Fl l
118specifies the language to use.
119Currently known are
120.Tn PASCAL
121.Pq Fl l Ns Ar p ,
122.Tn MODEL
123.Pq Fl l Ns Ar m ,
124C
125.Pf ( Fl l Ns Ar c
126or the default),
127.Tn C++
128.Pq Fl l Ns Ar c++ ,
129.Tn CSH
130.Pq Fl l Ns Ar csh ,
131.Tn SHELL
132.Pq Fl l Ns Ar sh ,
133.Tn RATFOR
134.Pq Fl l Ns Ar r ,
135.Tn MODULA2
136.Pq Fl l Ns Ar mod2 ,
137.Tn YACC
138.Pq Fl l Ns Ar yacc ,
139.Tn LISP
140.Pq Fl l Ns Ar isp ,
141.Tn ICON
142.Pq Fl l Ns Ar I ,
143and
144.Tn PERL
145.Pq Fl l Ns Ar perl .
146.It Fl n
147forces no keyword bolding
148.It Fl p Ar postproc
149use
150.Ar postproc
151to post-process the output,
152.Xr psroff 1
153by default.
154.It Fl s Ar pointsize
155specifies a point size to use on output (exactly the same as the argument
156of a .ps)
157.It Fl t
158similar to the same option in
159.Xr troff 1 Pq Pa ports/textproc/groff
160causing formatted text to go to the standard output
161.It Fl x
162outputs the index file in a ``pretty'' format.
163The index file itself is produced whenever
164.Nm
165is run with a file called
166.Pa index
167in the current directory.
168The index of function
169definitions can then be run off by giving
170.Nm
171the
172.Fl x
173option and the file
174.Pa index
175as argument.
176.El
177.Sh FILES
178.Bl -tag -width /usr/share/misc/vgrindefsxx -compact
179.It Pa index
180file where source for index is created
181.It Pa /usr/share/tmac/tmac.vgrind
182macro package
183.It Pa /usr/libexec/vfontedpr
184preprocessor
185.It Pa /usr/share/misc/vgrindefs
186language descriptions
187.El
188.Sh SEE ALSO
189.Xr getcap 3 ,
190.Xr vgrindefs 5
191.Sh HISTORY
192The
193.Nm
194command appeared in
195.Bx 3.0 .
196.Sh BUGS
197The vfontedpr preprocessor assumes that a certain programming style is
198followed:
199.Pp
200For
201.Tn C
202\- function names can be preceded on a line only by spaces, tabs, or an
203asterisk.
204The parenthesized arguments must also be on the same line.
205.Pp
206For
207.Tn PASCAL
208\- function names need to appear on the same line as the keywords
209.Em function
210or
211.Em procedure .
212.Pp
213For
214.Tn MODEL
215\- function names need to appear on the same line as the keywords
216.Em is beginproc .
217.Pp
218If these conventions are not followed, the indexing and marginal function
219name comment mechanisms will fail.
220.Pp
221More generally, arbitrary formatting styles for programs mostly look bad.
222The use of spaces to align source code fails miserably; if you plan to
223.Nm
224your program you should use tabs.
225This is somewhat inevitable since the
226font used by
227.Nm
228is variable width.
229.Pp
230The mechanism of
231.Xr ctags 1
232in recognizing functions should be used here.
233.Pp
234Filter mode does not work in documents using the
235.Fl me
236or
237.Fl ms
238macros.
239(So what use is it anyway?)
240