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