1.\" Copyright (c) 1980, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)vgrind.1 8.1 (Berkeley) 06/06/93 7.\" 8.Dd 9.Dt VGRIND 1 10.Os BSD 4 11.Sh NAME 12.Nm vgrind 13.Nd grind nice listings of programs 14.Sh SYNOPSIS 15.Nm vgrind 16.Op Fl 17.Op Fl W 18.Op Fl d Ar file 19.Op Fl f 20.Op Fl h Ar header 21.Op Fl l Ar language 22.Op Fl n 23.Op Fl sn 24.Op Fl t 25.Op Fl x 26.Ar name Ar ... 27.Sh DESCRIPTION 28.Nm Vgrind 29formats the program sources which are arguments 30in a nice style using 31.Xr troff 1 32Comments are placed in italics, keywords in bold face, 33and the name of the current function is listed down the margin of each 34page as it is encountered. 35.Pp 36.Nm Vgrind 37runs in two basic modes, filter mode (see the 38.Fl f 39option) or regular mode. In filter mode 40.Nm vgrind 41acts as a filter in a manner similar to 42.Xr tbl 1 . 43The standard input is passed directly to the standard output except 44for lines bracketed by the 45.Em troff-like 46macros: 47.Bl -tag -width Ds 48.It \&.vS 49starts processing 50.It \&.vE 51ends processing 52.El 53.Pp 54These lines are formatted as described above. The output from this 55filter can be passed to 56.Xr troff 57for output. There need be no particular ordering with 58.Xr eqn 1 59or 60.Xr tbl 1 . 61.Pp 62In regular mode 63.Nm vgrind 64accepts input files, processes them, and passes them to 65.Xr troff 1 66for output. 67.Pp 68In both modes 69.Nm vgrind 70passes any lines beginning with a decimal point without conversion. 71.Pp 72The options are: 73.Bl -tag -width Ar 74.It Fl 75forces input to be taken from standard input (default if 76.Fl f 77is specified ) 78.It Fl W 79forces output to the (wide) Versatec printer rather than the (narrow) 80Varian 81.It Fl d Ar file 82specifies an alternate language definitions 83file (default is 84.Pa /usr/share/misc/vgrindefs ) 85.It Fl f 86forces filter mode 87.It Fl h Ar header 88specifies a particular header to put on every output page (default is 89the file name) 90.It Fl l 91specifies the language to use. Currently known are 92.Tn PASCAL 93.Pq Fl l Ns Ar p , 94.Tn MODEL 95.Pq Fl l Ns Ar m , 96C 97.Pf ( Fl l Ns Ar c 98or the default), 99.Tn CSH 100.Pq Fl l Ns Ar csh , 101.Tn SHELL 102.Pq Fl l Ns Ar sh , 103.Tn RATFOR 104.Pq Fl l Ns Ar r , 105.Tn MODULA2 106.Pq Fl l Ns Ar mod2 , 107.Tn YACC 108.Pq Fl l Ns Ar yacc , 109.Tn LISP 110.Pq Fl l Ns Ar isp , 111and 112.Tn ICON 113.Pq Fl l Ns Ar I . 114.It Fl n 115forces no keyword bolding 116.It Fl s 117specifies a point size to use on output (exactly the same as the argument 118of a .ps) 119.It Fl t 120similar to the same option in 121.Xr troff 122causing formatted text to go to the standard output 123.It Fl x 124outputs the index file in a ``pretty'' format. 125The index file itself is produced whenever 126.Nm vgrind 127is run with a file called 128.Pa index 129in the current directory. 130The index of function 131definitions can then be run off by giving 132.Nm vgrind 133the 134.Fl x 135option and the file 136.Pa index 137as argument. 138.El 139.Sh FILES 140.Bl -tag -width /usr/share/misc/vgrindefsxx -compact 141.It Pa index 142file where source for index is created 143.It Pa /usr/share/tmac/tmac.vgrind 144macro package 145.It Pa /usr/libexec/vfontedpr 146preprocessor 147.It Pa /usr/share/misc/vgrindefs 148language descriptions 149.El 150.Sh SEE ALSO 151.Xr getcap 3 , 152.Xr vgrindefs 5 153.Sh BUGS 154Vfontedpr assumes that a certain programming style is followed: 155.Pp 156For 157.Tn C 158\- function names can be preceded on a line only by spaces, tabs, or an 159asterisk. The parenthesized arguments must also be on the same line. 160.Pp 161For 162.Tn PASCAL 163\- function names need to appear on the same line as the keywords 164.Em function 165or 166.Em procedure . 167.Pp 168For 169.Tn MODEL 170\- function names need to appear on the same line as the keywords 171.Em is beginproc . 172.Pp 173If these conventions are not followed, the indexing and marginal function 174name comment mechanisms will fail. 175.Pp 176More generally, arbitrary formatting styles for programs mostly look bad. 177The use of spaces to align source code fails miserably; if you plan to 178.Nm vgrind 179your program you should use tabs. This is somewhat inevitable since the 180font used by 181.Nm vgrind 182is variable width. 183.Pp 184The mechanism of 185.Xr ctags 1 186in recognizing functions should be used here. 187.Pp 188Filter mode does not work in documents using the 189.Fl me 190or 191.Fl ms 192macros. 193(So what use is it anyway?) 194.Sh HISTORY 195The 196.Nm 197command appeared in 198.Bx 3.0 . 199