| blob | d577c76b0de64bc79931dcfdd1b652d81bd931d8 |
1 .\" $NetBSD: indent.1,v 1.18 2005/09/11 23:17:34 wiz Exp $
2 .\"
3 .\" Copyright (c) 1980, 1990, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" Copyright (c) 1985 Sun Microsystems, Inc.
31 .\" Copyright (c) 1976 Board of Trustees of the University of Illinois.
32 .\" All rights reserved.
33 .\"
34 .\" Redistribution and use in source and binary forms, with or without
35 .\" modification, are permitted provided that the following conditions
36 .\" are met:
37 .\" 1. Redistributions of source code must retain the above copyright
38 .\" notice, this list of conditions and the following disclaimer.
39 .\" 2. Redistributions in binary form must reproduce the above copyright
40 .\" notice, this list of conditions and the following disclaimer in the
41 .\" documentation and/or other materials provided with the distribution.
42 .\" 3. All advertising materials mentioning features or use of this software
43 .\" must display the following acknowledgement:
44 .\" This product includes software developed by the University of
45 .\" California, Berkeley and its contributors.
46 .\" 4. Neither the name of the University nor the names of its contributors
47 .\" may be used to endorse or promote products derived from this software
48 .\" without specific prior written permission.
49 .\"
50 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
51 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
52 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
53 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
54 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
55 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
56 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
57 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
58 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
59 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
60 .\" SUCH DAMAGE.
61 .\"
62 .\" from: @(#)indent.1 8.1 (Berkeley) 7/1/93
63 .\"
64 .Dd July 1, 1993
65 .Dt INDENT 1
66 .Os
67 .Sh NAME
68 .Nm indent
69 .Nd indent and format C program source
70 .Sh SYNOPSIS
71 .Nm
72 .Bk -words
73 .Op Ar input-file Op Ar output-file
74 .Ek
75 .Bk -words
76 .Op Fl bacc | Fl nbacc
77 .Ek
78 .Bk -words
79 .Op Fl bad | Fl nbad
80 .Ek
81 .Bk -words
82 .Op Fl bap | Fl nbap
83 .Ek
84 .Bk -words
85 .Op Fl bbb | Fl nbbb
86 .Ek
87 .Bk -words
88 .Op Fl \&bc | Fl nbc
89 .Ek
90 .Op Fl \&bl
91 .Op Fl \&br
92 .Op Fl c Ns Ar n
93 .Op Fl \&cd Ns Ar n
94 .Bk -words
95 .Op Fl cdb | Fl ncdb
96 .Ek
97 .Bk -words
98 .Op Fl \&ce | Fl nce
99 .Ek
100 .Op Fl \&ci Ns Ar n
101 .Op Fl cli Ns Ar n
102 .Op Fl d Ns Ar n
103 .Op Fl \&di Ns Ar n
104 .Bk -words
105 .Op Fl fc1 | Fl nfc1
106 .Ek
107 .Op Fl i Ns Ar n
108 .Bk -words
109 .Op Fl \&ip | Fl nip
110 .Ek
111 .Op Fl l Ns Ar n
112 .Op Fl \&lc Ns Ar n
113 .Bk -words
114 .Op Fl \&lp | Fl nlp
115 .Ek
116 .Op Fl npro
117 .Bk -words
118 .Op Fl pcs | Fl npcs
119 .Ek
120 .Bk -words
121 .Op Fl psl | Fl npsl
122 .Ek
123 .Bk -words
124 .Op Fl \&sc | Fl nsc
125 .Ek
126 .Bk -words
127 .Op Fl sob | Fl nsob
128 .Ek
129 .Op Fl \&st
130 .Op Fl troff
131 .Bk -words
132 .Op Fl v | Fl \&nv
133 .Ek
134 .Sh DESCRIPTION
135 .Nm
136 is a
137 .Tn C
138 program formatter.
139 It reformats the
140 .Tn C
141 program in the
142 .Ar input-file
143 according to the switches.
144 The switches which can be specified are described below.
145 They may appear before or after the file names.
146 .Pp
147 .Sy NOTE :
148 If you only specify an
149 .Ar input-file ,
150 the formatting is
151 done `in-place', that is, the formatted file is written back into
152 .Ar input-file
153 and a backup copy of
154 .Ar input-file
155 is written in the current directory.
156 If
157 .Ar input-file
158 is named
159 .Sq Pa /blah/blah/file ,
160 the backup file is named
161 .Pa file.BAK .
162 .Pp
163 If
164 .Ar output-file
165 is specified,
166 .Nm
167 checks to make sure it is different from
168 .Ar input-file .
169 .Pp
170 The options listed below control the formatting style imposed by
171 .Nm .
172 .Bl -tag -width Op
173 .It Fl bacc , nbacc
174 If
175 .Fl bacc
176 is specified, a blank line is forced around every conditional
177 compilation block.
178 For example, in front of every #ifdef and after every #endif.
179 Other blank lines surrounding such blocks will be swallowed.
180 Default:
181 .Fl nbacc .
182 .It Fl bad , nbad
183 If
184 .Fl bad
185 is specified, a blank line is forced after every block of
186 declarations.
187 Default:
188 .Fl nbad .
189 .It Fl bap , nbap
190 If
191 .Fl bap
192 is specified, a blank line is forced after every procedure body.
193 Default:
194 .Fl nbap .
195 .It Fl bbb , nbbb
196 If
197 .Fl bbb
198 is specified, a blank line is forced before every block comment.
199 Default:
200 .Fl nbbb .
201 .It Fl \&bc , nbc
202 If
203 .Fl \&bc
204 is specified, then a newline is forced after each comma in a declaration.
205 .Fl nbc
206 turns off this option.
207 Default:
208 .Fl \&bc .
209 .It Fl \&br , \&bl
210 Specifying
211 .Fl \&bl
212 lines up compound statements like this:
213 .Bd -literal -offset indent
214 if (...)
215 {
216 code
217 }
218 .Ed
219 .Pp
220 Specifying
221 .Fl \&br
222 (the default) makes them look like this:
223 .Bd -literal -offset indent
224 if (...) {
225 code
226 }
227 .Ed
228 .Pp
229 .It Fl bs , Fl nbs
230 If
231 .Fl bs
232 is specified, a blank is forced after
233 .Ic sizeof .
234 Default:
235 .Fl nbs .
236 .It Fl c Ns Ar n
237 The column in which comments on code start.
238 Default:
239 .Fl c33 .
240 .It Fl cd Ns Ar n
241 The column in which comments on declarations start.
242 The default
243 is for these comments to start in the same column as those on code.
244 .It Fl cdb , ncdb
245 Enables (disables) the placement of comment delimiters on blank lines.
246 With this option enabled, comments look like this:
247 .Bd -literal -offset indent
248 /*
249 * this is a comment
250 */
251 .Ed
252 .Pp
253 Rather than like this:
254 .Bd -literal -offset indent
255 /* this is a comment */
256 .Ed
257 .Pp
258 This only affects block comments, not comments to the right of
259 code.
260 Default:
261 .Fl cdb .
262 .It Fl ce , nce
263 Enables (disables) forcing `else's to cuddle up to the immediately preceding
264 `}'.
265 Default:
266 .Fl \&ce .
267 .It Fl \&ci Ns Ar n
268 Sets the continuation indent to be
269 .Ar n .
270 Continuation
271 lines will be indented that far from the beginning of the first line of the
272 statement.
273 Parenthesized expressions have extra indentation added to
274 indicate the nesting, unless
275 .Fl \&lp
276 is in effect.
277 .Fl \&ci
278 defaults to the same value as
279 .Fl i .
280 .It Fl cli Ns Ar n
281 Causes case labels to be indented
282 .Ar n
283 tab stops to the right of the containing
284 .Ic switch
285 statement.
286 .Fl cli0.5
287 causes case labels to be indented half a tab stop.
288 Default:
289 .Fl cli0 .
290 .It Fl d Ns Ar n
291 Controls the placement of comments which are not to the right of code.
292 For example,
293 .Fl \&d\&1
294 means that such comments are placed one indentation level to the left of code.
295 Specifying the default
296 .Fl \&d\&0
297 lines up these comments with the code.
298 See the section on comment
299 indentation below.
300 .It Fl \&di Ns Ar n
301 Specifies the indentation, in character positions, from a declaration keyword
302 to the following identifier.
303 Default:
304 .Fl di16 .
305 .It Fl dj , ndj
306 .Fl \&dj
307 left justifies declarations.
308 .Fl ndj
309 indents declarations the same as code.
310 Default:
311 .Fl ndj .
312 .It Fl \&ei , nei
313 Enables (disables) special
314 .Ic else-if
315 processing.
316 If it's enabled, an
317 .Ic if
318 following an
319 .Ic else
320 will have the same indentation as the preceding
321 .Ic \&if
322 statement.
323 Default:
324 .Fl ei .
325 .It Fl eei , neei
326 Enables (disables) extra indentation on continuation lines of
327 the expression part of
328 .Ic if
329 and
330 .Ic while
331 statements.
332 These continuation lines will be indented one extra level.
333 Default:
334 .Fl neei .
335 .It Fl fc1 , nfc1
336 Enables (disables) the formatting of comments that start in column 1.
337 Often, comments whose leading `/' is in column 1 have been carefully
338 hand formatted by the programmer.
339 In such cases,
340 .Fl nfc1
341 should be used.
342 Default:
343 .Fl fc1 .
344 .It Fl i Ns Ar n
345 The number of spaces for one indentation level.
346 Default:
347 .Fl i8 .
348 .It Fl \&ip , nip
349 Enables (disables) the indentation of parameter declarations from the left
350 margin.
351 Default:
352 .Fl \&ip .
353 .It Fl l Ns Ar n
354 Maximum length of an output line.
355 Default:
356 .Fl l78 .
357 .It Fl \&lp , nlp
358 Lines up code surrounded by parenthesis in continuation lines.
359 If a line has a left paren which is not closed on that line, then
360 continuation lines will be lined up to start at the character
361 position just after the left paren.
362 For example, here is how a piece of continued code looks with
363 .Fl nlp
364 in effect:
365 .Bd -literal -offset indent
366 p1 = first_procedure(second_procedure(p2, p3),
367 \ \ third_procedure(p4,p5));
368 .Ed
369 .Pp
370 With
371 .Fl lp
372 in effect (the default) the code looks somewhat clearer:
373 .Bd -literal -offset indent
374 p1\ =\ first_procedure(second_procedure(p2,\ p3),
375 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,p5));
376 .Ed
377 .Pp
378 Inserting two more newlines we get:
379 .Bd -literal -offset indent
380 p1\ =\ first_procedure(second_procedure(p2,
381 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3),
382 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4
383 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5));
384 .Ed
385 .It Fl npro
386 Causes the profile files,
387 .Sq Pa ./.indent.pro
388 and
389 .Sq Pa ~/.indent.pro ,
390 to be ignored.
391 .It Fl pcs , npcs
392 If true
393 .Pq Fl pcs
394 all procedure calls will have a space inserted between
395 the name and the `('.
396 Default:
397 .Fl npcs .
398 .It Fl psl , npsl
399 If true
400 .Pq Fl psl
401 the names of procedures being defined are placed in
402 column 1 \- their types, if any, will be left on the previous lines.
403 Default:
404 .Fl psl .
405 .It Fl \&sc , nsc
406 Enables (disables) the placement of asterisks (`*'s) at the left edge of all
407 comments.
408 Default:
409 .Fl sc .
410 .It Fl sob , nsob
411 If
412 .Fl sob
413 is specified, indent will swallow optional blank lines.
414 You can use this to get rid of blank lines after declarations.
415 Default:
416 .Fl nsob .
417 .It Fl \&st
418 Causes
419 .Nm
420 to take its input from stdin, and put its output to stdout.
421 .It Fl T Ns Ar typename
422 Adds
423 .Ar typename
424 to the list of type keywords.
425 Names accumulate:
426 .Fl T
427 can be specified more than once.
428 You need to specify all the typenames that
429 appear in your program that are defined by
430 .Ic typedef
431 \- nothing will be
432 harmed if you miss a few, but the program won't be formatted as nicely as
433 it should.
434 This sounds like a painful thing to have to do, but it's really
435 a symptom of a problem in C:
436 .Ic typedef
437 causes a syntactic change in the
438 language and
439 .Nm
440 can't find all
441 instances of
442 .Ic typedef .
443 .It Fl troff
444 Causes
445 .Nm
446 to format the program for processing by
447 .Xr troff 1 .
448 It will produce a fancy
449 listing in much the same spirit as
450 .Xr vgrind 1 .
451 If the output file is not specified, the default is standard output,
452 rather than formatting in place.
453 .It Fl v , \&nv
454 .Fl v
455 turns on `verbose' mode;
456 .Fl \&nv
457 turns it off.
458 When in verbose mode,
459 .Nm
460 reports when it splits one line of input into two or more lines of output,
461 and gives some size statistics at completion.
462 Default:
463 .Fl \&nv .
464 .El
465 .Pp
466 You may set up your own `profile' of defaults to
467 .Nm
468 by creating a file called
469 .Pa .indent.pro
470 in your login directory and/or the current directory and including
471 whatever switches you like.
472 A `.indent.pro' in the current directory takes
473 precedence over the one in your login directory.
474 If
475 .Nm
476 is run and a profile file exists, then it is read to set up the program's
477 defaults.
478 Switches on the command line, though, always override profile switches.
479 The switches should be separated by spaces, tabs or newlines.
480 .Ss Comments
481 .Sq Em Box
482 .Em comments .
483 .Nm
484 assumes that any comment with a dash or star immediately after the start of
485 comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars.
486 Each line of such a comment is left unchanged, except that its indentation
487 may be adjusted to account for the change in indentation of the first line
488 of the comment.
489 .Pp
490 .Em Straight text .
491 All other comments are treated as straight text.
492 .Nm
493 fits as many words (separated by blanks, tabs, or newlines) on a
494 line as possible.
495 Blank lines break paragraphs.
496 .Ss Comment indentation
497 If a comment is on a line with code it is started in the `comment column',
498 which is set by the
499 .Fl c Ns Ns Ar n
500 command line parameter.
501 Otherwise, the comment is started at
502 .Ar n
503 indentation levels less than where code is currently being placed, where
504 .Ar n
505 is specified by the
506 .Fl d Ns Ns Ar n
507 command line parameter.
508 If the code on a line extends past the comment
509 column, the comment starts further to the right, and the right margin may be
510 automatically extended in extreme cases.
511 .Ss Preprocessor lines
512 In general,
513 .Nm
514 leaves preprocessor lines alone.
515 The only reformatting that it will do is to straighten up trailing comments.
516 It leaves embedded comments alone.
517 Conditional compilation
518 .Pq Ic #ifdef...#endif
519 is recognized and
520 .Nm
521 attempts to correctly
522 compensate for the syntactic peculiarities introduced.
523 .Ss C syntax
524 .Nm
525 understands a substantial amount about the syntax of C, but it
526 has a `forgiving' parser.
527 It attempts to cope with the usual sorts of incomplete and misformed syntax.
528 In particular, the use of macros like:
529 .Pp
530 .Dl #define forever for(;;)
531 .Pp
532 is handled properly.
533 .Sh ENVIRONMENT
534 .Nm
535 uses the
536 .Ev HOME
537 environment variable.
538 .Sh FILES
539 .Bl -tag -width "./.indent.pro" -compact
540 .It Pa ./.indent.pro
541 profile file
542 .It Pa ~/.indent.pro
543 profile file
544 .El
545 .Sh HISTORY
546 The
547 .Nm
548 command appeared in
549 .Bx 4.2 .
550 .Sh BUGS
551 .Nm
552 has even more switches than
553 .Xr ls 1 .
554 .Pp
555 A common mistake that often causes grief is typing:
556 .Pp
557 .Dl indent *.c
558 .Pp
559 to the shell in an attempt to indent all the
560 .Tn C
561 programs in a directory.
562 This is probably a bug, not a feature.