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