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