Commit | Line | Data |
---|---|---|
30f48914 KB |
1 | .\" Copyright (c) 1985 Sun Microsystems, Inc. |
2 | .\" Copyright (c) 1980 The Regents of the University of California. | |
3 | .\" Copyright (c) 1976 Board of Trustees of the University of Illinois. | |
4 | .\" All rights reserved. | |
438e9550 | 5 | .\" |
30f48914 KB |
6 | .\" Redistribution and use in source and binary forms are permitted |
7 | .\" provided that the above copyright notice and this paragraph are | |
8 | .\" duplicated in all such forms and that any documentation, | |
9 | .\" advertising materials, and other materials related to such | |
10 | .\" distribution and use acknowledge that the software was developed | |
11 | .\" by the University of California, Berkeley, the University of Illinois, | |
12 | .\" Urbana, and Sun Microsystems, Inc. The name of either University | |
13 | .\" or Sun Microsystems may not be used to endorse or promote products | |
14 | .\" derived from this software without specific prior written permission. | |
15 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
16 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
17 | .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
18 | .\" | |
19 | .\" @(#)indent.1 6.5 (Berkeley) %G% | |
438e9550 | 20 | .\" |
30f48914 KB |
21 | |
22 | .TH INDENT 1 " | |
438e9550 KM |
23 | .SH NAME |
24 | indent \- indent and format C program source | |
25 | .SH SYNOPSIS | |
1009bf5e KM |
26 | .in +\w'\fBindent \fR'u |
27 | .ti -\w'\fBindent \fR'u | |
28 | \fBindent \fR [ \fIinput-file\fR [ \fIoutput-file\fR ] ] | |
29 | [\ \fB\-bad\fR\ |\ \fB\-nbad\fR\ ] | |
30 | [\ \fB\-bap\fR\ |\ \fB\-nbap\fR\ ] | |
31 | [\ \fB\-bbb\fR\ |\ \fB\-nbbb\fR\ ] | |
32 | [\ \fB\-bc\fR\ |\ \fB\-nbc\fR\ ] | |
30f48914 KB |
33 | [\ \fB\-bl\fR\ ] |
34 | [\ \fB\-br\fR\ ] | |
1009bf5e KM |
35 | [\ \fB\-c\fIn\fR\ ] |
36 | [\ \fB\-cd\fIn\fR\ ] | |
37 | [\ \fB\-cdb\fR\ |\ \fB\-ncdb\fR\ ] | |
38 | [\ \fB\-ce\fR\ |\ \fB\-nce\fR\ ] | |
39 | [\ \fB\-ci\fIn\fR\ ] | |
40 | [\ \fB\-cli\fIn\fR\ ] | |
41 | [\ \fB\-d\fIn\fR\ ] | |
42 | [\ \fB\-di\fIn\fR\ ] | |
43 | [\ \fB\-fc1\fR\ |\ \fB\-nfc1\fR\ ] | |
44 | [\ \fB\-i\fIn\fR\ ] | |
45 | [\ \fB\-ip\fR\ |\ \fB\-nip\fR\ ] | |
46 | [\ \fB\-l\fIn\fR\ ] | |
47 | [\ \fB\-lc\fIn\fR\ ] | |
48 | [\ \fB\-lp\fR\ |\ \fB\-nlp\fR\ ] | |
9bdef9ea | 49 | [\ \fB\-pcs\fR\ |\ \fB\-npcs\fR\ ] |
30f48914 | 50 | [\ \fB\-npro\fR\ ] |
1009bf5e KM |
51 | [\ \fB\-psl\fR\ |\ \fB\-npsl\fR\ ] |
52 | [\ \fB\-sc\fR\ |\ \fB\-nsc\fR\ ] | |
53 | [\ \fB\-sob\fR\ |\ \fB\-nsob\fR\ ] | |
54 | [\ \fB\-st\fR\ ] | |
55 | [\ \fB\-troff\fR\ ] | |
56 | [\ \fB\-v\fR\ |\ \fB\-nv\fR\ ] | |
438e9550 KM |
57 | .SH DESCRIPTION |
58 | .I Indent | |
1009bf5e KM |
59 | is a \fBC\fR program formatter. It reformats the \fBC\fR program in the |
60 | \fIinput-file\fR according to the switches. The switches which can be | |
61 | specified are described below. They may appear before or after the file | |
62 | names. | |
63 | .LP | |
64 | \fBNOTE\fP: If you only specify an \fIinput-file\fR, the formatting is | |
65 | done `in-place', that is, the formatted file is written back into | |
66 | .I input-file | |
67 | and a backup copy of | |
68 | .I input-file | |
69 | is written in the current directory. If | |
70 | .I input-file | |
71 | is named `/blah/blah/file', the backup file is named | |
72 | .RI file .BAK. | |
73 | .LP | |
438e9550 | 74 | If |
1009bf5e | 75 | .I output-file |
438e9550 KM |
76 | is specified, |
77 | .I indent | |
78 | checks to make sure it is different from | |
1009bf5e KM |
79 | .IR input-file . |
80 | .SH OPTIONS | |
81 | .LP | |
82 | The options listed below control the formatting style imposed by | |
438e9550 | 83 | .IR indent . |
1009bf5e | 84 | .TP 15 |
9bdef9ea KM |
85 | .BR \-bap , \-nbap |
86 | If | |
87 | .B \-bap | |
88 | is specified, a blank line is forced after every procedure body. Default: | |
89 | .B \-nbap. | |
90 | .TP 15 | |
30f48914 KB |
91 | .BR \-bad , \-nbad |
92 | If | |
93 | .B \-bad | |
94 | is specified, a blank line is forced after every block of | |
95 | declarations. Default: | |
96 | .B \-nbad. | |
97 | .TP 15 | |
1009bf5e KM |
98 | .BR \-bbb , \-nbbb |
99 | If | |
100 | .B \-bbb | |
101 | is specified, a blank line is forced before every block comment. Default: | |
102 | .B \-nbbb. | |
103 | .TP 15 | |
438e9550 KM |
104 | .BR \-bc , \-nbc |
105 | If | |
106 | .B \-bc | |
1009bf5e | 107 | is specified, then a newline is forced after each comma in a declaration. |
438e9550 | 108 | .B \-nbc |
1009bf5e | 109 | turns off this option. The default is |
30f48914 | 110 | .BR \-bc . |
1009bf5e | 111 | .TP 15 |
438e9550 KM |
112 | .BR \-br , \-bl |
113 | Specifying | |
114 | .B \-bl | |
1009bf5e | 115 | lines up compound statements like this: |
438e9550 KM |
116 | .ne 4 |
117 | .nf | |
1009bf5e | 118 | .ft L |
438e9550 KM |
119 | if (...) |
120 | { | |
121 | code | |
122 | } | |
1009bf5e | 123 | .ft R |
438e9550 KM |
124 | .fi |
125 | Specifying | |
126 | .B \-br | |
1009bf5e | 127 | (the default) makes them look like this: |
438e9550 KM |
128 | .ne 3 |
129 | .nf | |
1009bf5e | 130 | .ft L |
438e9550 KM |
131 | if (...) { |
132 | code | |
133 | } | |
1009bf5e | 134 | .ft R |
438e9550 | 135 | .fi |
1009bf5e KM |
136 | .LP |
137 | .TP 15 | |
138 | .BI \-c n | |
139 | The column in which comments on code start. The default is 33. | |
140 | .TP 15 | |
141 | .BI \-cd n | |
142 | The column in which comments on declarations start. The default | |
143 | is for these comments to start in the same column as those on code. | |
144 | .TP 15 | |
145 | .BI \-cdb , \-ncdb | |
146 | Enables (disables) the placement of comment delimiters on blank lines. With | |
147 | this option enabled, comments look like this: | |
438e9550 | 148 | .nf |
1009bf5e KM |
149 | .ft L |
150 | .ne 3 | |
151 | /* | |
152 | * this is a comment | |
153 | */ | |
154 | .ft R | |
155 | .fi | |
156 | Rather than like this: | |
157 | .nf | |
158 | .ft L | |
159 | /* this is a comment */ | |
160 | .ft R | |
161 | .fi | |
30f48914 KB |
162 | This only affects block comments, not comments to the right of code. The default is |
163 | .B \-cdb . | |
1009bf5e KM |
164 | .TP 15 |
165 | .BI \-ce , \-nce | |
30f48914 | 166 | Enables (disables) forcing `else's to cuddle up to the immediatly preceeding |
1009bf5e | 167 | `}'. The default is |
30f48914 | 168 | .B \-ce . |
1009bf5e KM |
169 | .TP 15 |
170 | .BI \-ci n | |
171 | Sets the continuation indent to be \fIn\fR. Continuation | |
172 | lines will be indented that far from the beginning of the first line of the | |
173 | statement. Parenthesized expressions have extra indentation added to | |
174 | indicate the nesting, unless \fB\-lp\fR is in effect. | |
175 | \fB\-ci\fR defaults to the same value as \fB\-i\fR. | |
176 | .TP 15 | |
177 | .BI \-cli n | |
178 | Causes case labels to be indented | |
179 | .I n | |
180 | tab stops to the right of the containing \fBswitch\fR statement. | |
30f48914 | 181 | \fB-cli0.5\fR causes case labels to be indented half a tab stop. The |
1009bf5e | 182 | default is |
30f48914 | 183 | .B \-cli0 . |
1009bf5e KM |
184 | .TP 15 |
185 | .BI \-d n | |
186 | Controls the placement of comments which are not to the | |
30f48914 | 187 | right of code. The default |
1009bf5e KM |
188 | .B \-d1 |
189 | means that such comments are placed one indentation level to the | |
30f48914 | 190 | left of code. Specifying |
1009bf5e KM |
191 | .B \-d0 |
192 | lines up these comments with the code. See the section on comment | |
193 | indentation below. | |
194 | .TP 15 | |
195 | .BI \-di n | |
196 | Specifies the indentation, in character positions, from a declaration keyword | |
197 | to the following identifier. The default is | |
30f48914 KB |
198 | .B \-di16 . |
199 | .if 0 \{.TP 15 | |
1009bf5e KM |
200 | .BR \-dj , \-ndj |
201 | .B \-dj | |
202 | left justifies declarations. | |
203 | .B \-ndj | |
204 | indents declarations the same as code. The default is | |
205 | .BR \-ndj . | |
206 | .TP 15 | |
207 | .BI \-ei , \-nei | |
208 | Enables (disables) special | |
209 | .B else-if | |
30f48914 | 210 | processing. If it's enabled, |
1009bf5e KM |
211 | .BR if "s" |
212 | following | |
213 | .BR else "s" | |
30f48914 | 214 | will have the same indendation as the preceeding |
1009bf5e | 215 | .B if |
30f48914 | 216 | statement.\} |
1009bf5e KM |
217 | .TP 15 |
218 | .BI \-fc1 , \-nfc1 | |
219 | Enables (disables) the formatting of comments that start in column 1. | |
220 | Often, comments whose leading `/' is in column 1 have been carefully | |
221 | hand formatted by the programmer. In such cases, \fB\-nfc1\fR should be | |
222 | used. The default is \fB\-fc1\fR. | |
223 | .TP 15 | |
224 | .BI \-i n | |
30f48914 | 225 | The number of spaces for one indentation level. The default is 4. |
1009bf5e KM |
226 | .TP 15 |
227 | .BI \-ip , \-nip | |
228 | Enables (disables) the indentation of parameter declarations from the left | |
229 | margin. The default is | |
30f48914 | 230 | .B \-ip . |
1009bf5e KM |
231 | .TP 15 |
232 | .BI \-l n | |
30f48914 KB |
233 | Maximum length of an output line. The default is 75. |
234 | .TP 15 | |
235 | .B \-npro | |
236 | Causes the profile files, `./.indent.pro' and `~/.indent.pro', to be ignored. | |
1009bf5e KM |
237 | .TP 15 |
238 | .BI \-lp , \-nlp | |
239 | Lines up code surrounded by parenthesis in continuation lines. If a line | |
240 | has a left paren which is not closed on that line, then continuation lines | |
241 | will be lined up to start at the character position just after the left | |
30f48914 KB |
242 | paren. For example, here is how a piece of continued code looks with -nlp |
243 | in effect: | |
1009bf5e KM |
244 | .ne 2 |
245 | .nf | |
246 | .ft L | |
247 | p1 = first_procedure(second_procedure(p2, p3), | |
248 | third_procedure(p4, p5)); | |
249 | .ft R | |
438e9550 | 250 | .fi |
1009bf5e | 251 | .ne 5 |
30f48914 | 252 | With \fB-lp\fR in effect (the default) the code looks somewhat clearer: |
1009bf5e KM |
253 | .nf |
254 | .ft L | |
255 | p1 = first_procedure(second_procedure(p2, p3), | |
30f48914 | 256 | third_procedure(p4, p5)); |
1009bf5e KM |
257 | .ft R |
258 | .fi | |
259 | .ne 5 | |
30f48914 | 260 | Inserting a couple more newlines we get: |
1009bf5e KM |
261 | .nf |
262 | .ft L | |
263 | p1 = first_procedure(second_procedure(p2, | |
30f48914 KB |
264 | p3), |
265 | third_procedure(p4, | |
266 | p5)); | |
1009bf5e KM |
267 | .ft R |
268 | .fi | |
269 | .TP 15 | |
30f48914 KB |
270 | .B \-pcs , \-npcs |
271 | If true (\fB-pcs\fR) all procedure calls will have a space inserted between | |
272 | the name and the '('. The default is | |
273 | .B \-npcs | |
9bdef9ea | 274 | .TP 15 |
30f48914 KB |
275 | .B \-psl , \-npsl |
276 | If true (\fB-psl\fR) the names of procedures being defined are placed in | |
1009bf5e KM |
277 | column 1 \- their types, if any, will be left on the previous lines. The |
278 | default is | |
30f48914 | 279 | .B -psl |
1009bf5e | 280 | .TP 15 |
30f48914 | 281 | .BI \-sc , \-nsc |
1009bf5e | 282 | Enables (disables) the placement of asterisks (`*'s) at the left edge of all |
30f48914 | 283 | comments. |
1009bf5e KM |
284 | .TP 15 |
285 | .BR \-sob , \-nsob | |
286 | If | |
287 | .B \-sob | |
288 | is specified, indent will swallow optional blank lines. You can use this to | |
289 | get rid of blank lines after declarations. Default: | |
30f48914 | 290 | .B \-nsob |
1009bf5e KM |
291 | .TP 15 |
292 | .B \-st | |
293 | Causes | |
294 | .B indent | |
295 | to take its input from stdin, and put its output to stdout. | |
296 | .TP 15 | |
297 | .BI \-T typename | |
298 | Adds | |
299 | .I typename | |
300 | to the list of type keywords. Names accumulate: | |
301 | .B \-T | |
302 | can be specified more than once. You need to specify all the typenames that | |
303 | appear in your program that are defined by \fBtypedef\fRs \- nothing will be | |
304 | harmed if you miss a few, but the program won't be formatted as nicely as | |
305 | it should. This sounds like a painful thing to have to do, but it's really | |
306 | a symptom of a problem in C: \fBtypedef\fR causes a syntactic change in the | |
30f48914 | 307 | laguage and \fIindent\fR can't find all \fBtypedef\fRs. |
1009bf5e KM |
308 | .TP 15 |
309 | .B \-troff | |
310 | Causes | |
311 | .B indent | |
312 | to format the program for processing by troff. It will produce a fancy | |
313 | listing in much the same spirit as | |
30f48914 | 314 | .BR vgrind. |
1009bf5e KM |
315 | If the output file is not specified, the default is standard output, |
316 | rather than formatting in place. | |
317 | .TP 15 | |
318 | .BR \-v , \-nv | |
319 | .B \-v | |
30f48914 | 320 | turns on `verbose' mode, |
1009bf5e KM |
321 | .B \-nv |
322 | turns it off. When in verbose mode, | |
323 | .I indent | |
324 | reports when it splits one line of input into two or more lines of output, | |
325 | and gives some size statistics at completion. The default is | |
326 | .BR \-nv . | |
327 | .SH "FURTHER DESCRIPTION" | |
328 | .LP | |
329 | You may set up your own `profile' of defaults to | |
330 | .I indent | |
331 | by creating a file called | |
332 | .BI . indent . pro | |
30f48914 KB |
333 | in either your login directory or the current directory and including |
334 | whatever switches you like. A `.indent.pro' in the current directory takes | |
335 | precedence over the one in your login directory. If | |
1009bf5e KM |
336 | .I indent |
337 | is run and a profile file exists, then it is read to set up the program's | |
30f48914 KB |
338 | defaults. Switches on the command line, though, always override profile |
339 | switches. The switches should be separated by spaces, tabs or newlines. | |
1009bf5e | 340 | .LP |
438e9550 | 341 | .B Comments |
1009bf5e KM |
342 | .LP |
343 | .IR "`Box' comments" . | |
438e9550 | 344 | .I Indent |
1009bf5e KM |
345 | assumes that any comment with a dash or star immediately after the start of |
346 | comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars. | |
347 | Each line of such a comment is left unchanged, except that its indentation | |
348 | may be adjusted to account for the change in indentation of the first line | |
349 | of the comment. | |
350 | .LP | |
351 | .IR "Straight text" . | |
352 | All other comments are treated as straight text. | |
438e9550 | 353 | .I Indent |
1009bf5e KM |
354 | fits as many words (separated by blanks, tabs, or newlines) on a |
355 | line as possible. Blank lines break paragraphs. | |
356 | .LP | |
438e9550 | 357 | .B Comment indentation |
1009bf5e KM |
358 | .LP |
359 | If a comment is on a line with code it is started in the `comment column', | |
360 | which is set by the | |
361 | .BI \-c n | |
362 | command line parameter. Otherwise, the comment is started at | |
363 | .I n | |
364 | indentation levels less than where code is currently being placed, where | |
365 | .I n | |
438e9550 | 366 | is specified by the |
1009bf5e KM |
367 | .BI \-d n |
368 | command line parameter. If the code on a line extends past the comment | |
369 | column, the comment starts further to the right, and the right margin may be | |
370 | automatically extended in extreme cases. | |
371 | .LP | |
372 | .B Preprocessor lines | |
373 | .LP | |
374 | In general, \fIindent\fR leaves preprocessor lines alone. The only | |
30f48914 KB |
375 | reformmatting that it will do is to straighten up trailing comments. It |
376 | leaves imbedded comments alone. Conditional compilation | |
1009bf5e | 377 | (\fB#ifdef...#endif\fR) is recognized and \fIindent\fR attempts to correctly |
30f48914 | 378 | compensate for the syntactic peculiarites introduced. |
1009bf5e KM |
379 | .LP |
380 | .B C syntax | |
381 | .LP | |
382 | \fIIndent\fR understands a substantial amount about the syntax of C, but it | |
383 | has a `forgiving' parser. It attempts to cope with the usual sorts of | |
384 | incomplete and misformed syntax. In particular, the use of macros like: | |
385 | .nf | |
386 | .ft L | |
387 | #define forever for(;;) | |
388 | .ft R | |
389 | .fi | |
390 | is handled properly. | |
438e9550 KM |
391 | .SH FILES |
392 | .DT | |
1009bf5e KM |
393 | .br |
394 | \&./.indent.pro profile file | |
395 | .br | |
438e9550 | 396 | .SH BUGS |
1009bf5e KM |
397 | .I Indent |
398 | has even more switches than \fIls\fR. | |
30f48914 | 399 | |
1009bf5e KM |
400 | .ne 5 |
401 | A common mistake that often causes grief is typing: | |
402 | .nf | |
403 | .ft L | |
404 | indent *.c | |
405 | .ft R | |
406 | .fi | |
407 | to the shell in an attempt to indent all the \fBC\fR programs in a directory. | |
408 | This is probably a bug, not a feature. |