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