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