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