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