Annotation of src/usr.bin/vgrind/vgrind.1, Revision 1.4
1.4 ! aaron 1: .\" $OpenBSD: vgrind.1,v 1.3 1998/10/30 00:24:42 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.4 ! aaron 68: option) or regular mode. In filter mode
! 69: .Nm
1.1 deraadt 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
1.4 ! aaron 73: for lines bracketed by the
1.1 deraadt 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
1.4 ! aaron 84: filter can be passed to
1.3 aaron 85: .Xr troff 1
1.4 ! aaron 86: for output. There need be no particular ordering with
1.1 deraadt 87: .Xr eqn 1
88: or
89: .Xr tbl 1 .
90: .Pp
1.4 ! aaron 91: In regular mode
! 92: .Nm
! 93: accepts input files, processes them, and passes them to
1.1 deraadt 94: .Xr troff 1
1.4 ! aaron 95: for output.
1.1 deraadt 96: .Pp
1.4 ! aaron 97: In both modes
! 98: .Nm
1.1 deraadt 99: passes any lines beginning with a decimal point without conversion.
100: .Pp
101: The options are:
102: .Bl -tag -width Ar
1.4 ! aaron 103: .It Fl
1.3 aaron 104: Forces input to be taken from standard input (default if
1.1 deraadt 105: .Fl f
1.3 aaron 106: is specified).
1.1 deraadt 107: .It Fl W
1.3 aaron 108: Forces output to the (wide) Versatec printer rather than the (narrow)
109: Varian.
1.1 deraadt 110: .It Fl d Ar file
1.3 aaron 111: Specifies an alternate language definitions
1.1 deraadt 112: file (default is
1.3 aaron 113: .Pa /usr/share/misc/vgrindefs Ns ).
1.1 deraadt 114: .It Fl f
1.3 aaron 115: Forces filter mode.
1.1 deraadt 116: .It Fl h Ar header
1.3 aaron 117: Specifies a particular header to put on every output page (default is
118: the file name).
1.1 deraadt 119: .It Fl l
1.3 aaron 120: Specifies the language to use. Currently known are
1.1 deraadt 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
1.3 aaron 144: Forces no keyword bolding.
1.1 deraadt 145: .It Fl s
1.3 aaron 146: Specifies a point size to use on output (exactly the same as the argument
147: of a .ps).
1.1 deraadt 148: .It Fl t
1.3 aaron 149: Similar to the same option in
150: .Xr troff 1
1.1 deraadt 151: causing formatted text to go to the standard output
152: .It Fl x
1.4 ! aaron 153: Outputs the index file in a
! 154: .Dq pretty
! 155: format.
! 156: The index file itself is produced whenever
! 157: .Nm
! 158: is run with a file called
1.1 deraadt 159: .Pa index
160: in the current directory.
161: The index of function
1.4 ! aaron 162: definitions can then be run off by giving
! 163: .Nm
1.1 deraadt 164: the
165: .Fl x
166: option and the file
167: .Pa index
168: as argument.
169: .El
170: .Sh FILES
171: .Bl -tag -width /usr/share/misc/vgrindefsxx -compact
172: .It Pa index
173: file where source for index is created
174: .It Pa /usr/share/tmac/tmac.vgrind
175: macro package
176: .It Pa /usr/libexec/vfontedpr
177: preprocessor
178: .It Pa /usr/share/misc/vgrindefs
179: language descriptions
180: .El
181: .Sh SEE ALSO
182: .Xr lpr 1 ,
183: .Xr troff 1 ,
184: .Xr getcap 3 ,
185: .Xr vgrindefs 5
186: .Sh BUGS
1.3 aaron 187: vfontedpr assumes that a certain programming style is followed:
1.1 deraadt 188: .Pp
1.4 ! aaron 189: For
1.1 deraadt 190: .Tn C
191: \- function names can be preceded on a line only by spaces, tabs, or an
192: asterisk. The parenthesized arguments must also be on the same line.
193: .Pp
194: For
195: .Tn PASCAL
196: \- function names need to appear on the same line as the keywords
197: .Em function
198: or
199: .Em procedure .
200: .Pp
201: For
202: .Tn MODEL
203: \- function names need to appear on the same line as the keywords
204: .Em is beginproc .
205: .Pp
206: If these conventions are not followed, the indexing and marginal function
207: name comment mechanisms will fail.
208: .Pp
209: More generally, arbitrary formatting styles for programs mostly look bad.
210: The use of spaces to align source code fails miserably; if you plan to
1.4 ! aaron 211: .Nm
1.1 deraadt 212: your program you should use tabs. This is somewhat inevitable since the
213: font used by
1.4 ! aaron 214: .Nm
1.1 deraadt 215: is variable width.
216: .Pp
217: The mechanism of
218: .Xr ctags 1
219: in recognizing functions should be used here.
220: .Pp
221: Filter mode does not work in documents using the
222: .Fl me
223: or
224: .Fl ms
225: macros.
226: (So what use is it anyway?)
227: .Sh HISTORY
228: The
229: .Nm
230: command appeared in
231: .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