Annotation of src/usr.bin/vgrind/vgrind.1, Revision 1.14
1.14 ! sobrado 1: .\" $OpenBSD: vgrind.1,v 1.13 2008/04/11 14:24:29 millert 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.13 millert 33: .Dd $Mdocdate: April 11 2008 $
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.
142: The default device is ps (PostScript).
1.11 jmc 143: .It Fl W
144: Forces output to the (wide) Versatec printer rather than the (narrow)
145: Varian.
1.1 deraadt 146: .It Fl x
1.4 aaron 147: Outputs the index file in a
148: .Dq pretty
149: format.
150: The index file itself is produced whenever
151: .Nm
152: is run with a file called
1.1 deraadt 153: .Pa index
154: in the current directory.
155: The index of function
1.4 aaron 156: definitions can then be run off by giving
157: .Nm
1.1 deraadt 158: the
159: .Fl x
160: option and the file
161: .Pa index
162: as argument.
163: .El
164: .Sh FILES
165: .Bl -tag -width /usr/share/misc/vgrindefsxx -compact
166: .It Pa index
167: file where source for index is created
168: .It Pa /usr/share/tmac/tmac.vgrind
169: macro package
170: .It Pa /usr/libexec/vfontedpr
171: preprocessor
172: .It Pa /usr/share/misc/vgrindefs
173: language descriptions
174: .El
175: .Sh SEE ALSO
176: .Xr lpr 1 ,
177: .Xr troff 1 ,
178: .Xr getcap 3 ,
179: .Xr vgrindefs 5
1.6 aaron 180: .Sh HISTORY
181: The
182: .Nm
183: command appeared in
184: .Bx 3.0 .
1.1 deraadt 185: .Sh BUGS
1.3 aaron 186: vfontedpr assumes that a certain programming style is followed:
1.1 deraadt 187: .Pp
1.4 aaron 188: For
1.1 deraadt 189: .Tn C
190: \- function names can be preceded on a line only by spaces, tabs, or an
1.7 aaron 191: asterisk.
192: The parenthesized arguments must also be on the same line.
1.1 deraadt 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.7 aaron 212: your program you should use tabs.
213: This is somewhat inevitable since the 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?)
![[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