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