Annotation of src/usr.bin/vgrind/vgrind.1, Revision 1.9
1.9 ! millert 1: .\" $OpenBSD: vgrind.1,v 1.8 2000/11/09 17:52:46 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.
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: .\"
33: .Dd June 6, 1993
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.4 aaron 41: .Op Fl
1.1 deraadt 42: .Op Fl W
43: .Op Fl d Ar file
44: .Op Fl f
45: .Op Fl h Ar header
46: .Op Fl l Ar language
47: .Op Fl n
48: .Op Fl sn
49: .Op Fl t
50: .Op Fl x
51: .Ar name Ar ...
52: .Sh DESCRIPTION
1.4 aaron 53: .Nm
54: formats the program sources which are arguments
1.1 deraadt 55: in a nice style using
56: .Xr troff 1 .
57: Comments are placed in italics, keywords in bold face,
58: and the name of the current function is listed down the margin of each
59: page as it is encountered.
60: .Pp
1.4 aaron 61: .Nm
1.1 deraadt 62: runs in two basic modes, filter mode (see the
63: .Fl f
1.7 aaron 64: option) or regular mode.
65: In filter mode
1.4 aaron 66: .Nm
1.1 deraadt 67: acts as a filter in a manner similar to
68: .Xr tbl 1 .
69: The standard input is passed directly to the standard output except
1.4 aaron 70: for lines bracketed by the
1.1 deraadt 71: .Em troff-like
72: macros:
73: .Bl -tag -width Ds
74: .It \&.vS
75: starts processing
76: .It \&.vE
77: ends processing
78: .El
79: .Pp
1.7 aaron 80: These lines are formatted as described above.
81: The output from this filter can be passed to
1.3 aaron 82: .Xr troff 1
1.7 aaron 83: for output.
84: There need be no particular ordering with
1.1 deraadt 85: .Xr eqn 1
86: or
87: .Xr tbl 1 .
88: .Pp
1.4 aaron 89: In regular mode
90: .Nm
91: accepts input files, processes them, and passes them to
1.1 deraadt 92: .Xr troff 1
1.4 aaron 93: for output.
1.1 deraadt 94: .Pp
1.4 aaron 95: In both modes
96: .Nm
1.1 deraadt 97: passes any lines beginning with a decimal point without conversion.
98: .Pp
1.5 aaron 99: The options are as follows:
1.8 aaron 100: .Bl -tag -width Ds
1.4 aaron 101: .It Fl
1.3 aaron 102: Forces input to be taken from standard input (default if
1.1 deraadt 103: .Fl f
1.3 aaron 104: is specified).
1.1 deraadt 105: .It Fl W
1.3 aaron 106: Forces output to the (wide) Versatec printer rather than the (narrow)
107: Varian.
1.1 deraadt 108: .It Fl d Ar file
1.3 aaron 109: Specifies an alternate language definitions
1.1 deraadt 110: file (default is
1.3 aaron 111: .Pa /usr/share/misc/vgrindefs Ns ).
1.1 deraadt 112: .It Fl f
1.3 aaron 113: Forces filter mode.
1.1 deraadt 114: .It Fl h Ar header
1.3 aaron 115: Specifies a particular header to put on every output page (default is
116: the file name).
1.1 deraadt 117: .It Fl l
1.7 aaron 118: Specifies the language to use.
119: Currently known are
1.1 deraadt 120: .Tn PASCAL
121: .Pq Fl l Ns Ar p ,
122: .Tn MODEL
123: .Pq Fl l Ns Ar m ,
124: C
125: .Pf ( Fl l Ns Ar c
126: or the default),
127: .Tn CSH
128: .Pq Fl l Ns Ar csh ,
129: .Tn SHELL
130: .Pq Fl l Ns Ar sh ,
131: .Tn RATFOR
132: .Pq Fl l Ns Ar r ,
133: .Tn MODULA2
134: .Pq Fl l Ns Ar mod2 ,
135: .Tn YACC
136: .Pq Fl l Ns Ar yacc ,
137: .Tn LISP
138: .Pq Fl l Ns Ar isp ,
139: and
140: .Tn ICON
141: .Pq Fl l Ns Ar I .
142: .It Fl n
1.3 aaron 143: Forces no keyword bolding.
1.1 deraadt 144: .It Fl s
1.3 aaron 145: Specifies a point size to use on output (exactly the same as the argument
146: of a .ps).
1.1 deraadt 147: .It Fl t
1.3 aaron 148: Similar to the same option in
149: .Xr troff 1
1.1 deraadt 150: causing formatted text to go to the standard output
151: .It Fl x
1.4 aaron 152: Outputs the index file in a
153: .Dq pretty
154: format.
155: The index file itself is produced whenever
156: .Nm
157: is run with a file called
1.1 deraadt 158: .Pa index
159: in the current directory.
160: The index of function
1.4 aaron 161: definitions can then be run off by giving
162: .Nm
1.1 deraadt 163: the
164: .Fl x
165: option and the file
166: .Pa index
167: as argument.
168: .El
169: .Sh FILES
170: .Bl -tag -width /usr/share/misc/vgrindefsxx -compact
171: .It Pa index
172: file where source for index is created
173: .It Pa /usr/share/tmac/tmac.vgrind
174: macro package
175: .It Pa /usr/libexec/vfontedpr
176: preprocessor
177: .It Pa /usr/share/misc/vgrindefs
178: language descriptions
179: .El
180: .Sh SEE ALSO
181: .Xr lpr 1 ,
182: .Xr troff 1 ,
183: .Xr getcap 3 ,
184: .Xr vgrindefs 5
1.6 aaron 185: .Sh HISTORY
186: The
187: .Nm
188: command appeared in
189: .Bx 3.0 .
1.1 deraadt 190: .Sh BUGS
1.3 aaron 191: vfontedpr assumes that a certain programming style is followed:
1.1 deraadt 192: .Pp
1.4 aaron 193: For
1.1 deraadt 194: .Tn C
195: \- function names can be preceded on a line only by spaces, tabs, or an
1.7 aaron 196: asterisk.
197: The parenthesized arguments must also be on the same line.
1.1 deraadt 198: .Pp
199: For
200: .Tn PASCAL
201: \- function names need to appear on the same line as the keywords
202: .Em function
203: or
204: .Em procedure .
205: .Pp
206: For
207: .Tn MODEL
208: \- function names need to appear on the same line as the keywords
209: .Em is beginproc .
210: .Pp
211: If these conventions are not followed, the indexing and marginal function
212: name comment mechanisms will fail.
213: .Pp
214: More generally, arbitrary formatting styles for programs mostly look bad.
215: The use of spaces to align source code fails miserably; if you plan to
1.4 aaron 216: .Nm
1.7 aaron 217: your program you should use tabs.
218: This is somewhat inevitable since the font used by
1.4 aaron 219: .Nm
1.1 deraadt 220: is variable width.
221: .Pp
222: The mechanism of
223: .Xr ctags 1
224: in recognizing functions should be used here.
225: .Pp
226: Filter mode does not work in documents using the
227: .Fl me
228: or
229: .Fl ms
230: macros.
231: (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