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