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