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