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