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