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