| blob | 2428245f379f86f3c15a8f37d1cc32c87f64b640 |
1 '\" te
2 .\" Copyright (c) 1980 Regents of the University
3 .\" of California. All rights reserved. The Berkeley software License Agreement
4 .\" specifies the terms and conditions for redistribution.
5 .\" Copyright (c) 2000, Sun Microsystems, Inc.
6 .\" All Rights Reserved
7 .TH VGRIND 1 "Mar 3, 2000"
8 .SH NAME
9 vgrind \- grind nice program listings
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBvgrind\fR [\fB-2fntwx\fR] [\fB-d\fR \fIdefs-file\fR] [\fB-h\fR \fIheader\fR] [\fB-l\fR \fIlanguage\fR]
14 [\fB-s\fR \fIn\fR] [\fB-o\fR \fIpagelist\fR] [\fB-P\fR \fIprinter\fR] [\fB-T\fR \fIoutput-device\fR] \fIfilename\fR...
15 .fi
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The \fBvgrind\fR utility formats the program sources named by the
21 \fIfilename\fR arguments in a nice style using \fBtroff\fR(1). Comments are
22 placed in italics, keywords in bold face, and as each function is encountered
23 its name is listed on the page margin.
24 .sp
25 .LP
26 \fBvgrind\fR runs in two basic modes, filter mode or regular mode. In filter
27 mode, \fBvgrind\fR acts as a filter in a manner similar to \fBtbl\fR(1). The
28 standard input is passed directly to the standard output except for lines
29 bracketed by the \fBtroff\fR-like macros:
30 .sp
31 .ne 2
32 .na
33 \fB\fB\&.vS\fR\fR
34 .ad
35 .RS 9n
36 starts processing
37 .RE
39 .sp
40 .ne 2
41 .na
42 \fB\fB\&.vE\fR\fR
43 .ad
44 .RS 9n
45 ends processing
46 .RE
48 .sp
49 .LP
50 These lines are formatted as described above. The output from this filter can
51 be passed to \fBtroff\fR for output. There need be no particular ordering with
52 \fBeqn\fR(1) or \fBtbl\fR(1).
53 .sp
54 .LP
55 In regular mode, \fBvgrind\fR accepts input \fIfilename\fRs, processes them,
56 and passes them to \fBtroff\fR for output. Use a hyphen (`\fB\(mi\fR\&') to
57 specify standard input; otherwise, \fBvgrind\fR will exit without attempting to
58 read from the standard input. Filenames must be specified after all other
59 option arguments.
60 .sp
61 .LP
62 In regular mode, if the \fB-t\fR or \fB-P\fR option is specified, the output
63 is:
64 .RS +4
65 .TP
66 .ie t \(bu
67 .el o
68 emitted (in \fBtroff\fR format) to stdout if the \fB-t\fR option is specified.
69 .RE
70 .RS +4
71 .TP
72 .ie t \(bu
73 .el o
74 printed (as PostScript) to the named printer if the \fB-P\fR option is
75 specified.
76 .RE
77 .sp
78 .LP
79 Otherwise, the output is:
80 .RS +4
81 .TP
82 .ie t \(bu
83 .el o
84 printed (as PostScript) on the system default printer, if one is defined, and
85 the command's stdout is a tty.
86 .RE
87 .RS +4
88 .TP
89 .ie t \(bu
90 .el o
91 emitted (as PostScript) to stdout if it is not a tty (that is, if stdout is a
92 pipe or a redirect to a file).
93 .RE
94 .sp
95 .LP
96 In both modes, \fBvgrind\fR passes any lines beginning with a decimal point
97 without conversion.
98 .SH OPTIONS
99 .sp
100 .LP
101 The following options are supported:
102 .sp
103 .ne 2
104 .na
105 \fB\fB-2\fR\fR
106 .ad
107 .RS 16n
108 Produces two-column output. Specifying this option changes the default point
109 size to 8 (as if the \fB-s8\fR option were supplied). It also arranges for
110 output to appear in landscape mode.
111 .RE
113 .sp
114 .ne 2
115 .na
116 \fB\fB-f\fR\fR
117 .ad
118 .RS 16n
119 Forces filter mode.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fB-n\fR\fR
126 .ad
127 .RS 16n
128 Does not make keywords boldface.
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fB-w\fR\fR
135 .ad
136 .RS 16n
137 Considers TAB characters to be spaced four columns apart instead of the usual
138 eight.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fB-x\fR\fR
145 .ad
146 .RS 16n
147 Outputs the index file in a "pretty" format. The index file itself is produced
148 whenever \fBvgrind\fR is run with a file called \fBindex\fR that is present in
149 the current directory. The index of function definitions can then be run off by
150 giving \fBvgrind\fR the \fB-x\fR option and the file \fBindex\fR as argument.
151 .RE
153 .sp
154 .ne 2
155 .na
156 \fB\fB-d\fR \fIdefs-file\fR\fR
157 .ad
158 .RS 16n
159 Specifies an alternate language definitions file (default is
160 \fB/usr/lib/vgrindefs\fR).
161 .RE
163 .sp
164 .ne 2
165 .na
166 \fB\fB-h\fR \fIheader\fR\fR
167 .ad
168 .RS 16n
169 Specifies a header to appear in the center of every output page. Use quotes to
170 specify headers with embedded spaces.
171 .RE
173 .sp
174 .ne 2
175 .na
176 \fB\fB-l\fR \fIlanguage\fR\fR
177 .ad
178 .RS 16n
179 Specifies the language to use. Among the \fIlanguage\fRs currently known are:
180 Bourne shell (\fB-lsh\fR), C (\fB-lc\fR, the default), C++ (\fB-lc++\fR), C
181 shell (\fB-lcsh\fR), emacs MLisp (\fB-lml\fR), FORTRAN (\fB-lf\fR), Icon
182 (\fB-lI\fR), ISP (\fB-i\fR), LDL (\fB-lLDL\fR), Model (\fB-lm\fR), Pascal
183 (\fB-lp\fR), and RATFOR (\fB-lr\fR).
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fB-P\fR \fIprinter\fR\fR
190 .ad
191 .RS 16n
192 Sends output to the named \fIprinter\fR.
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fB-s\fR \fIn\fR\fR
199 .ad
200 .RS 16n
201 Specifies a point size to use on output (exactly the same as the argument of a
202 \fBtroff\fR \fB\&.ps\fR point size request).
203 .RE
205 .sp
206 .LP
207 \fBvgrind\fR passes the following options to the formatter specified by the
208 \fBTROFF\fR environment variable. See ENVIRONMENT VARIABLES.
209 .sp
210 .ne 2
211 .na
212 \fB\fB-t\fR\fR
213 .ad
214 .RS 20n
215 Similar to the same option in \fBtroff\fR; that is, formatted text goes to the
216 standard output.
217 .RE
219 .sp
220 .ne 2
221 .na
222 \fB\fB-o\fR \fIpagelist\fR\fR
223 .ad
224 .RS 20n
225 Prints only those pages whose page numbers appear in the comma-separated
226 \fIpagelist\fR of numbers and ranges. A range \fIN\(miM\fR means pages \fIN\fR
227 through \fIM\fR; an initial \fB-N\fR means from the beginning to page \fIN\fR;
228 and a final \fIN\fR\(mi means from \fIN\fR to the end.
229 .RE
231 .sp
232 .ne 2
233 .na
234 \fB\fB-T\fR \fIoutput-device\fR\fR
235 .ad
236 .RS 20n
237 Formats output for the specified \fIoutput-device\fR.
238 .RE
240 .SH OPERANDS
241 .sp
242 .LP
243 The following operand is supported:
244 .sp
245 .ne 2
246 .na
247 \fB\fIfilename\fR\fR
248 .ad
249 .RS 12n
250 Name of the program source to be processed by \fBvgrind\fR. Use `\fB\(mi\fR\&'
251 to specify the standard input.
252 .RE
254 .SH ENVIRONMENT VARIABLES
255 .sp
256 .LP
257 In regular mode, \fBvgrind\fR feeds its intermediate output to the text
258 formatter given by the value of the \fBTROFF\fR environment variable, or to
259 \fB/usr/bin/troff\fR if this variable is not defined in the environment. This
260 mechanism allows for local variations in \fBtroff\fR's name.
261 .SH FILES
262 .sp
263 .ne 2
264 .na
265 \fB\fBindex\fR\fR
266 .ad
267 .sp .6
268 .RS 4n
269 file where source for index is created
270 .RE
272 .sp
273 .ne 2
274 .na
275 \fB\fB/usr/lib/vgrindefs\fR\fR
276 .ad
277 .sp .6
278 .RS 4n
279 language descriptions
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fB/usr/lib/vfontedpr\fR\fR
286 .ad
287 .sp .6
288 .RS 4n
289 preprocessor
290 .RE
292 .sp
293 .ne 2
294 .na
295 \fB\fB/usr/share/lib/tmac/tmac.vgrind\fR\fR
296 .ad
297 .sp .6
298 .RS 4n
299 macro package
300 .RE
302 .SH SEE ALSO
303 .sp
304 .LP
305 \fBcsh\fR(1), \fBctags\fR(1), \fBeqn\fR(1), \fBtbl\fR(1), \fBtroff\fR(1),
306 \fBattributes\fR(5), \fBvgrindefs\fR(5)
307 .SH BUGS
308 .sp
309 .LP
310 \fBvgrind\fR assumes that a certain programming style is followed:
311 .sp
312 .ne 2
313 .na
314 \fBC\fR
315 .ad
316 .RS 11n
317 Function names can be preceded on a line only by SPACE, TAB, or an asterisk
318 (\fB*\fR). The parenthesized arguments must also be on the same line.
319 .RE
321 .sp
322 .ne 2
323 .na
324 \fBFORTRAN\fR
325 .ad
326 .RS 11n
327 Function names need to appear on the same line as the keywords \fBfunction\fR
328 or \fBsubroutine\fR.
329 .RE
331 .sp
332 .ne 2
333 .na
334 \fBMLisp\fR
335 .ad
336 .RS 11n
337 Function names should not appear on the same line as the preceding \fBdefun\fR.
338 .RE
340 .sp
341 .ne 2
342 .na
343 \fBModel\fR
344 .ad
345 .RS 11n
346 Function names need to appear on the same line as the keywords \fBis
347 beginproc\fR.
348 .RE
350 .sp
351 .ne 2
352 .na
353 \fBPascal\fR
354 .ad
355 .RS 11n
356 Function names need to appear on the same line as the keywords \fBfunction\fR
357 or \fBprocedure\fR.
358 .RE
360 .sp
361 .LP
362 If these conventions are not followed, the indexing and marginal function name
363 comment mechanisms will fail.
364 .sp
365 .LP
366 More generally, arbitrary formatting styles for programs usually give unsightly
367 results. To prepare a program for \fBvgrind\fR output, use TAB rather than
368 SPACE characters to align source code properly, since \fBvgrind\fR uses
369 variable width fonts.
370 .sp
371 .LP
372 The mechanism of \fBctags\fR(1) in recognizing functions should be used here.
373 .sp
374 .LP
375 The \fB-w\fR option is annoying, but there is no other way to achieve the
376 desired effect.
377 .sp
378 .LP
379 The macros defined in \fBtmac.vgrind\fR do not coexist gracefully with those of
380 other macro packages, making filter mode difficult to use effectively.
381 .sp
382 .LP
383 \fBvgrind\fR does not process certain special characters in \fBcsh\fR(1)
384 scripts correctly.
385 .sp
386 .LP
387 The \fBtmac.vgrind\fR formatting macros wire in the page height and width used
388 in two-column mode, effectively making two column output useless for paper
389 sizes other than the standard American size of 8.5 inches by 11 inches. For
390 other paper sizes, it is necessary to edit the size values given in
391 \fBtmac.vgrind\fR. A better solution would be to create a \fBtroff\fR output
392 device specification intended specifically for landscape output and record size
393 information there.