usr.bin/vgrind/vgrind.1

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