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