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