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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd August 29, 2006 29.Dt VGRIND 1 30.Os 31.Sh NAME 32.Nm vgrind 33.Nd grind nice listings of programs 34.Sh SYNOPSIS 35.Nm 36.Op Fl 37.Op Fl W 38.Op Fl d Ar file 39.Op Fl f 40.Op Fl h Ar header 41.Op Fl l Ns Ar language 42.Op Fl n 43.Op Fl p Ar postproc 44.Op Fl s Ar pointsize 45.Op Fl t 46.Op Fl x 47.Ar name Ar ... 48.Sh DESCRIPTION 49The 50.Nm 51utility formats the program sources specified as arguments 52on the command line in a nice style using 53.Xr troff 1 Pq Pa ports/textproc/groff . 54Comments are placed in italics, keywords in bold face, 55and the name of the current function is listed down the margin of each 56page as it is encountered. 57.Pp 58The 59.Nm 60utility runs in two basic modes, filter mode (see the 61.Fl f 62option) or regular mode. 63In filter mode 64.Nm 65acts as a filter in a manner similar to 66.Xr tbl 1 . 67The standard input is passed directly to the standard output except 68for lines bracketed by the 69.Em troff-like 70macros: 71.Bl -tag -width Ds 72.It \&.vS 73starts processing 74.It \&.vE 75ends processing 76.El 77.Pp 78These lines are formatted as described above. 79The output from this 80filter can be passed to 81.Xr troff 1 Pq Pa ports/textproc/groff 82for output. 83There need be no particular ordering with 84.Xr eqn 1 Pq Pa ports/textproc/groff 85or 86.Xr tbl 1 Pq Pa ports/textproc/groff . 87.Pp 88In regular mode 89.Nm 90accepts input files, processes them, and passes them to the postprocessor 91for output, 92.Xr psroff 1 93by default. 94.Pp 95In both modes 96.Nm 97passes any lines beginning with a decimal point without conversion. 98.Pp 99The options are: 100.Bl -tag -width Ar 101.It Fl 102forces input to be taken from standard input (default if 103.Fl f 104is specified) 105.It Fl W 106forces output to the (wide) Versatec printer rather than the (narrow) 107Varian 108.It Fl d Ar file 109specifies an alternate language definitions 110file (default is 111.Pa /usr/share/misc/vgrindefs ) 112.It Fl f 113forces filter mode 114.It Fl h Ar header 115specifies a particular header to put on every output page (default is 116the file name) 117.It Fl l 118specifies the language to use. 119Currently known are 120.Tn PASCAL 121.Pq Fl l Ns Ar p , 122.Tn MODEL 123.Pq Fl l Ns Ar m , 124C 125.Pf ( Fl l Ns Ar c 126or the default), 127.Tn C++ 128.Pq Fl l Ns Ar c++ , 129.Tn CSH 130.Pq Fl l Ns Ar csh , 131.Tn SHELL 132.Pq Fl l Ns Ar sh , 133.Tn RATFOR 134.Pq Fl l Ns Ar r , 135.Tn MODULA2 136.Pq Fl l Ns Ar mod2 , 137.Tn YACC 138.Pq Fl l Ns Ar yacc , 139.Tn LISP 140.Pq Fl l Ns Ar isp , 141.Tn ICON 142.Pq Fl l Ns Ar I , 143and 144.Tn PERL 145.Pq Fl l Ns Ar perl . 146.It Fl n 147forces no keyword bolding 148.It Fl p Ar postproc 149use 150.Ar postproc 151to post-process the output, 152.Xr psroff 1 153by default. 154.It Fl s Ar pointsize 155specifies a point size to use on output (exactly the same as the argument 156of a .ps) 157.It Fl t 158similar to the same option in 159.Xr troff 1 Pq Pa ports/textproc/groff 160causing formatted text to go to the standard output 161.It Fl x 162outputs the index file in a ``pretty'' format. 163The index file itself is produced whenever 164.Nm 165is run with a file called 166.Pa index 167in the current directory. 168The index of function 169definitions can then be run off by giving 170.Nm 171the 172.Fl x 173option and the file 174.Pa index 175as argument. 176.El 177.Sh FILES 178.Bl -tag -width /usr/share/misc/vgrindefsxx -compact 179.It Pa index 180file where source for index is created 181.It Pa /usr/share/tmac/tmac.vgrind 182macro package 183.It Pa /usr/libexec/vfontedpr 184preprocessor 185.It Pa /usr/share/misc/vgrindefs 186language descriptions 187.El 188.Sh SEE ALSO 189.Xr getcap 3 , 190.Xr vgrindefs 5 191.Sh HISTORY 192The 193.Nm 194command appeared in 195.Bx 3.0 . 196.Sh BUGS 197The vfontedpr preprocessor assumes that a certain programming style is 198followed: 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 226font used by 227.Nm 228is variable width. 229.Pp 230The mechanism of 231.Xr ctags 1 232in recognizing functions should be used here. 233.Pp 234Filter mode does not work in documents using the 235.Fl me 236or 237.Fl ms 238macros. 239(So what use is it anyway?) 240