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 | .\" | |
1a43f1ba | 19 | .\" @(#)indent.1 6.6 (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\ ] | |
30f48914 | 49 | [\ \fB\-npro\fR\ ] |
1a43f1ba | 50 | [\ \fB\-pcs\fR\ |\ \fB\-npcs\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 |
30f48914 KB |
85 | .BR \-bad , \-nbad |
86 | If | |
87 | .B \-bad | |
88 | is specified, a blank line is forced after every block of | |
89 | declarations. Default: | |
1a43f1ba KB |
90 | .BR \-nbad . |
91 | .TP 15 | |
92 | .BR \-bap , \-nbap | |
93 | If | |
94 | .B \-bap | |
95 | is specified, a blank line is forced after every procedure body. Default: | |
96 | .B \-nbap. | |
30f48914 | 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 | |
1a43f1ba KB |
162 | This only affects block comments, not comments to the right of |
163 | code. The default is | |
164 | .BR \-cdb . | |
1009bf5e KM |
165 | .TP 15 |
166 | .BI \-ce , \-nce | |
1a43f1ba | 167 | Enables (disables) forcing `else's to cuddle up to the immediately preceding |
1009bf5e | 168 | `}'. The default is |
1a43f1ba | 169 | .BR \-ce . |
1009bf5e KM |
170 | .TP 15 |
171 | .BI \-ci n | |
172 | Sets the continuation indent to be \fIn\fR. Continuation | |
173 | lines will be indented that far from the beginning of the first line of the | |
174 | statement. Parenthesized expressions have extra indentation added to | |
175 | indicate the nesting, unless \fB\-lp\fR is in effect. | |
176 | \fB\-ci\fR defaults to the same value as \fB\-i\fR. | |
177 | .TP 15 | |
178 | .BI \-cli n | |
179 | Causes case labels to be indented | |
180 | .I n | |
181 | tab stops to the right of the containing \fBswitch\fR statement. | |
1a43f1ba | 182 | \fB\-cli0.5\fR causes case labels to be indented half a tab stop. The |
1009bf5e | 183 | default is |
1a43f1ba | 184 | .BR \-cli0 . |
1009bf5e KM |
185 | .TP 15 |
186 | .BI \-d n | |
187 | Controls the placement of comments which are not to the | |
30f48914 | 188 | right of code. The default |
1009bf5e KM |
189 | .B \-d1 |
190 | means that such comments are placed one indentation level to the | |
30f48914 | 191 | left of code. Specifying |
1009bf5e KM |
192 | .B \-d0 |
193 | lines up these comments with the code. See the section on comment | |
194 | indentation below. | |
195 | .TP 15 | |
196 | .BI \-di n | |
197 | Specifies the indentation, in character positions, from a declaration keyword | |
198 | to the following identifier. The default is | |
1a43f1ba | 199 | .BR \-di16 . |
30f48914 | 200 | .if 0 \{.TP 15 |
1009bf5e KM |
201 | .BR \-dj , \-ndj |
202 | .B \-dj | |
203 | left justifies declarations. | |
204 | .B \-ndj | |
205 | indents declarations the same as code. The default is | |
206 | .BR \-ndj . | |
207 | .TP 15 | |
208 | .BI \-ei , \-nei | |
209 | Enables (disables) special | |
210 | .B else-if | |
30f48914 | 211 | processing. If it's enabled, |
1009bf5e KM |
212 | .BR if "s" |
213 | following | |
214 | .BR else "s" | |
1a43f1ba | 215 | will have the same indentation as the preceding |
1009bf5e | 216 | .B if |
30f48914 | 217 | statement.\} |
1009bf5e KM |
218 | .TP 15 |
219 | .BI \-fc1 , \-nfc1 | |
220 | Enables (disables) the formatting of comments that start in column 1. | |
221 | Often, comments whose leading `/' is in column 1 have been carefully | |
222 | hand formatted by the programmer. In such cases, \fB\-nfc1\fR should be | |
223 | used. The default is \fB\-fc1\fR. | |
224 | .TP 15 | |
225 | .BI \-i n | |
30f48914 | 226 | The number of spaces for one indentation level. The default is 4. |
1009bf5e KM |
227 | .TP 15 |
228 | .BI \-ip , \-nip | |
229 | Enables (disables) the indentation of parameter declarations from the left | |
230 | margin. The default is | |
1a43f1ba | 231 | .BR \-ip . |
1009bf5e KM |
232 | .TP 15 |
233 | .BI \-l n | |
30f48914 KB |
234 | Maximum length of an output line. The default is 75. |
235 | .TP 15 | |
1009bf5e KM |
236 | .BI \-lp , \-nlp |
237 | Lines up code surrounded by parenthesis in continuation lines. If a line | |
238 | has a left paren which is not closed on that line, then continuation lines | |
239 | will be lined up to start at the character position just after the left | |
1a43f1ba KB |
240 | paren. For example, here is how a piece of continued code looks with |
241 | \fB\-nlp\fR in effect: | |
1009bf5e KM |
242 | .ne 2 |
243 | .nf | |
244 | .ft L | |
245 | p1 = first_procedure(second_procedure(p2, p3), | |
246 | third_procedure(p4, p5)); | |
247 | .ft R | |
438e9550 | 248 | .fi |
1009bf5e | 249 | .ne 5 |
1a43f1ba | 250 | With \fB\-lp\fR in effect (the default) the code looks somewhat clearer: |
1009bf5e KM |
251 | .nf |
252 | .ft L | |
1a43f1ba | 253 | .ta \w' p1 = first_procedure('u |
1009bf5e | 254 | p1 = first_procedure(second_procedure(p2, p3), |
1a43f1ba | 255 | third_procedure(p4, p5)); |
1009bf5e KM |
256 | .ft R |
257 | .fi | |
258 | .ne 5 | |
1a43f1ba | 259 | Inserting two more newlines we get: |
1009bf5e KM |
260 | .nf |
261 | .ft L | |
1a43f1ba | 262 | .ta \w' p1 = first_procedure('u +\w'second_procedure('u |
1009bf5e | 263 | p1 = first_procedure(second_procedure(p2, |
1a43f1ba KB |
264 | p3), |
265 | .ta \w' p1 = first_procedure('u +\w'third_procedure('u | |
266 | third_procedure(p4, | |
267 | p5)); | |
1009bf5e KM |
268 | .ft R |
269 | .fi | |
270 | .TP 15 | |
1a43f1ba KB |
271 | .B \-npro |
272 | Causes the profile files, `./.indent.pro' and `~/.indent.pro', to be ignored. | |
9bdef9ea | 273 | .TP 15 |
1a43f1ba KB |
274 | .BR \-pcs , \-npcs |
275 | If true (\fB\-pcs\fR) all procedure calls will have a space inserted between | |
276 | the name and the `('. The default is | |
277 | .BR \-npcs . | |
278 | .TP 15 | |
279 | .BR \-psl , \-npsl | |
280 | If true (\fB\-psl\fR) the names of procedures being defined are placed in | |
1009bf5e KM |
281 | column 1 \- their types, if any, will be left on the previous lines. The |
282 | default is | |
1a43f1ba | 283 | .BR \-psl . |
1009bf5e | 284 | .TP 15 |
1a43f1ba | 285 | .BR \-sc , \-nsc |
1009bf5e | 286 | Enables (disables) the placement of asterisks (`*'s) at the left edge of all |
30f48914 | 287 | comments. |
1009bf5e KM |
288 | .TP 15 |
289 | .BR \-sob , \-nsob | |
290 | If | |
291 | .B \-sob | |
292 | is specified, indent will swallow optional blank lines. You can use this to | |
293 | get rid of blank lines after declarations. Default: | |
1a43f1ba | 294 | .BR \-nsob . |
1009bf5e KM |
295 | .TP 15 |
296 | .B \-st | |
297 | Causes | |
298 | .B indent | |
299 | to take its input from stdin, and put its output to stdout. | |
300 | .TP 15 | |
301 | .BI \-T typename | |
302 | Adds | |
303 | .I typename | |
304 | to the list of type keywords. Names accumulate: | |
305 | .B \-T | |
306 | can be specified more than once. You need to specify all the typenames that | |
307 | appear in your program that are defined by \fBtypedef\fRs \- nothing will be | |
308 | harmed if you miss a few, but the program won't be formatted as nicely as | |
309 | it should. This sounds like a painful thing to have to do, but it's really | |
310 | a symptom of a problem in C: \fBtypedef\fR causes a syntactic change in the | |
1a43f1ba | 311 | language and \fIindent\fR can't find all \fBtypedef\fRs. |
1009bf5e KM |
312 | .TP 15 |
313 | .B \-troff | |
314 | Causes | |
315 | .B indent | |
316 | to format the program for processing by troff. It will produce a fancy | |
317 | listing in much the same spirit as | |
1a43f1ba | 318 | .BR vgrind . |
1009bf5e KM |
319 | If the output file is not specified, the default is standard output, |
320 | rather than formatting in place. | |
321 | .TP 15 | |
322 | .BR \-v , \-nv | |
323 | .B \-v | |
1a43f1ba | 324 | turns on `verbose' mode; |
1009bf5e KM |
325 | .B \-nv |
326 | turns it off. When in verbose mode, | |
327 | .I indent | |
328 | reports when it splits one line of input into two or more lines of output, | |
329 | and gives some size statistics at completion. The default is | |
330 | .BR \-nv . | |
331 | .SH "FURTHER DESCRIPTION" | |
332 | .LP | |
333 | You may set up your own `profile' of defaults to | |
334 | .I indent | |
335 | by creating a file called | |
336 | .BI . indent . pro | |
1a43f1ba | 337 | in your login directory and/or the current directory and including |
30f48914 KB |
338 | whatever switches you like. A `.indent.pro' in the current directory takes |
339 | precedence over the one in your login directory. If | |
1009bf5e KM |
340 | .I indent |
341 | is run and a profile file exists, then it is read to set up the program's | |
30f48914 KB |
342 | defaults. Switches on the command line, though, always override profile |
343 | switches. The switches should be separated by spaces, tabs or newlines. | |
1009bf5e | 344 | .LP |
438e9550 | 345 | .B Comments |
1009bf5e KM |
346 | .LP |
347 | .IR "`Box' comments" . | |
438e9550 | 348 | .I Indent |
1009bf5e KM |
349 | assumes that any comment with a dash or star immediately after the start of |
350 | comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars. | |
351 | Each line of such a comment is left unchanged, except that its indentation | |
352 | may be adjusted to account for the change in indentation of the first line | |
353 | of the comment. | |
354 | .LP | |
355 | .IR "Straight text" . | |
356 | All other comments are treated as straight text. | |
438e9550 | 357 | .I Indent |
1009bf5e KM |
358 | fits as many words (separated by blanks, tabs, or newlines) on a |
359 | line as possible. Blank lines break paragraphs. | |
360 | .LP | |
438e9550 | 361 | .B Comment indentation |
1009bf5e KM |
362 | .LP |
363 | If a comment is on a line with code it is started in the `comment column', | |
364 | which is set by the | |
365 | .BI \-c n | |
366 | command line parameter. Otherwise, the comment is started at | |
367 | .I n | |
368 | indentation levels less than where code is currently being placed, where | |
369 | .I n | |
438e9550 | 370 | is specified by the |
1009bf5e KM |
371 | .BI \-d n |
372 | command line parameter. If the code on a line extends past the comment | |
373 | column, the comment starts further to the right, and the right margin may be | |
374 | automatically extended in extreme cases. | |
375 | .LP | |
376 | .B Preprocessor lines | |
377 | .LP | |
378 | In general, \fIindent\fR leaves preprocessor lines alone. The only | |
1a43f1ba KB |
379 | reformatting that it will do is to straighten up trailing comments. It |
380 | leaves embedded comments alone. Conditional compilation | |
1009bf5e | 381 | (\fB#ifdef...#endif\fR) is recognized and \fIindent\fR attempts to correctly |
1a43f1ba | 382 | compensate for the syntactic peculiarities introduced. |
1009bf5e KM |
383 | .LP |
384 | .B C syntax | |
385 | .LP | |
386 | \fIIndent\fR understands a substantial amount about the syntax of C, but it | |
387 | has a `forgiving' parser. It attempts to cope with the usual sorts of | |
388 | incomplete and misformed syntax. In particular, the use of macros like: | |
389 | .nf | |
390 | .ft L | |
391 | #define forever for(;;) | |
392 | .ft R | |
393 | .fi | |
394 | is handled properly. | |
438e9550 KM |
395 | .SH FILES |
396 | .DT | |
1009bf5e KM |
397 | .br |
398 | \&./.indent.pro profile file | |
399 | .br | |
1a43f1ba | 400 | ~/.indent.pro profile file |
438e9550 | 401 | .SH BUGS |
1009bf5e KM |
402 | .I Indent |
403 | has even more switches than \fIls\fR. | |
1a43f1ba | 404 | .sp |
1009bf5e KM |
405 | .ne 5 |
406 | A common mistake that often causes grief is typing: | |
407 | .nf | |
408 | .ft L | |
409 | indent *.c | |
410 | .ft R | |
411 | .fi | |
412 | to the shell in an attempt to indent all the \fBC\fR programs in a directory. | |
413 | This is probably a bug, not a feature. |