1vgrind(1) User Commands vgrind(1)
2
3
4
6 vgrind - grind nice program listings
7
9 vgrind [-2fntwx] [-d defs-file] [-h header] [-l language]
10 [-s n] [-o pagelist] [-P printer] [-T output-device] filename...
11
12
14 The vgrind utility formats the program sources named by the filename
15 arguments in a nice style using troff(1). Comments are placed in ital‐
16 ics, keywords in bold face, and as each function is encountered its
17 name is listed on the page margin.
18
19
20 vgrind runs in two basic modes, filter mode or regular mode. In filter
21 mode, vgrind acts as a filter in a manner similar to tbl(1). The stan‐
22 dard input is passed directly to the standard output except for lines
23 bracketed by the troff-like macros:
24
25 .vS starts processing
26
27
28 .vE ends processing
29
30
31
32 These lines are formatted as described above. The output from this fil‐
33 ter can be passed to troff for output. There need be no particular
34 ordering with eqn(1) or tbl(1).
35
36
37 In regular mode, vgrind accepts input filenames, processes them, and
38 passes them to troff for output. Use a hyphen (`−') to specify standard
39 input; otherwise, vgrind will exit without attempting to read from the
40 standard input. Filenames must be specified after all other option
41 arguments.
42
43
44 In regular mode, if the -t or -P option is specified, the output is:
45
46 o emitted (in troff format) to stdout if the -t option is
47 specified.
48
49 o printed (as PostScript) to the named printer if the -P
50 option is specified.
51
52
53 Otherwise, the output is:
54
55 o printed (as PostScript) on the system default printer, if
56 one is defined, and the command's stdout is a tty.
57
58 o emitted (as PostScript) to stdout if it is not a tty (that
59 is, if stdout is a pipe or a redirect to a file).
60
61
62 In both modes, vgrind passes any lines beginning with a decimal point
63 without conversion.
64
66 The following options are supported:
67
68 -2 Produces two-column output. Specifying this option
69 changes the default point size to 8 (as if the -s8
70 option were supplied). It also arranges for output to
71 appear in landscape mode.
72
73
74 -f Forces filter mode.
75
76
77 -n Does not make keywords boldface.
78
79
80 -w Considers TAB characters to be spaced four columns
81 apart instead of the usual eight.
82
83
84 -x Outputs the index file in a "pretty" format. The index
85 file itself is produced whenever vgrind is run with a
86 file called index that is present in the current direc‐
87 tory. The index of function definitions can then be run
88 off by giving vgrind the -x option and the file index
89 as argument.
90
91
92 -d defs-file Specifies an alternate language definitions file
93 (default is /usr/lib/vgrindefs).
94
95
96 -h header Specifies a header to appear in the center of every
97 output page. Use quotes to specify headers with embed‐
98 ded spaces.
99
100
101 -l language Specifies the language to use. Among the languages cur‐
102 rently known are: Bourne shell (-lsh), C (-lc, the
103 default), C++ (-lc++), C shell (-lcsh), emacs MLisp
104 (-lml), FORTRAN (-lf), Icon (-lI), ISP (-i), LDL
105 (-lLDL), Model (-lm), Pascal (-lp), and RATFOR (-lr).
106
107
108 -P printer Sends output to the named printer.
109
110
111 -s n Specifies a point size to use on output (exactly the
112 same as the argument of a troff .ps point size
113 request).
114
115
116
117 vgrind passes the following options to the formatter specified by the
118 TROFF environment variable. See ENVIRONMENT VARIABLES.
119
120 -t Similar to the same option in troff; that is, for‐
121 matted text goes to the standard output.
122
123
124 -o pagelist Prints only those pages whose page numbers appear
125 in the comma-separated pagelist of numbers and
126 ranges. A range N−M means pages N through M; an
127 initial -N means from the beginning to page N; and
128 a final N− means from N to the end.
129
130
131 -T output-device Formats output for the specified output-device.
132
133
135 The following operand is supported:
136
137 filename Name of the program source to be processed by vgrind. Use
138 `−' to specify the standard input.
139
140
142 In regular mode, vgrind feeds its intermediate output to the text for‐
143 matter given by the value of the TROFF environment variable, or to
144 /usr/bin/troff if this variable is not defined in the environment. This
145 mechanism allows for local variations in troff's name.
146
148 index
149
150 file where source for index is created
151
152
153 /usr/lib/vgrindefs
154
155 language descriptions
156
157
158 /usr/lib/vfontedpr
159
160 preprocessor
161
162
163 /usr/share/lib/tmac/tmac.vgrind
164
165 macro package
166
167
169 See attributes(5) for descriptions of the following attributes:
170
171
172
173
174 ┌─────────────────────────────┬─────────────────────────────┐
175 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
176 ├─────────────────────────────┼─────────────────────────────┤
177 │Availability │SUNWdoc │
178 └─────────────────────────────┴─────────────────────────────┘
179
181 csh(1), ctags(1), eqn(1), tbl(1), troff(1), attributes(5), vgrindefs(5)
182
184 vgrind assumes that a certain programming style is followed:
185
186 C Function names can be preceded on a line only by SPACE, TAB,
187 or an asterisk (*). The parenthesized arguments must also be
188 on the same line.
189
190
191 FORTRAN Function names need to appear on the same line as the key‐
192 words function or subroutine.
193
194
195 MLisp Function names should not appear on the same line as the
196 preceding defun.
197
198
199 Model Function names need to appear on the same line as the key‐
200 words is beginproc.
201
202
203 Pascal Function names need to appear on the same line as the key‐
204 words function or procedure.
205
206
207
208 If these conventions are not followed, the indexing and marginal func‐
209 tion name comment mechanisms will fail.
210
211
212 More generally, arbitrary formatting styles for programs usually give
213 unsightly results. To prepare a program for vgrind output, use TAB
214 rather than SPACE characters to align source code properly, since
215 vgrind uses variable width fonts.
216
217
218 The mechanism of ctags(1) in recognizing functions should be used here.
219
220
221 The -w option is annoying, but there is no other way to achieve the
222 desired effect.
223
224
225 The macros defined in tmac.vgrind do not coexist gracefully with those
226 of other macro packages, making filter mode difficult to use effec‐
227 tively.
228
229
230 vgrind does not process certain special characters in csh(1) scripts
231 correctly.
232
233
234 The tmac.vgrind formatting macros wire in the page height and width
235 used in two-column mode, effectively making two column output useless
236 for paper sizes other than the standard American size of 8.5 inches by
237 11 inches. For other paper sizes, it is necessary to edit the size val‐
238 ues given in tmac.vgrind. A better solution would be to create a troff
239 output device specification intended specifically for landscape output
240 and record size information there.
241
242
243
244SunOS 5.11 3 Mar 2000 vgrind(1)