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.3 2006/03/26 22:56:57 swildner 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.Ss Comments 383.Sq Em Box 384.Em comments . 385The 386.Nm 387utility 388assumes that any comment with a dash or star immediately after the start of 389comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars. 390Each line of such a comment is left unchanged, except that its indentation 391may be adjusted to account for the change in indentation of the first line 392of the comment. 393.Pp 394.Em Straight text . 395All other comments are treated as straight text. 396The 397.Nm 398utility fits as many words (separated by blanks, tabs, or newlines) on a 399line as possible. Blank lines break paragraphs. 400.Ss Comment indentation 401If a comment is on a line with code it is started in the `comment column', 402which is set by the 403.Fl c Ns Ns Ar n 404command line parameter. Otherwise, the comment is started at 405.Ar n 406indentation levels less than where code is currently being placed, where 407.Ar n 408is specified by the 409.Fl d Ns Ns Ar n 410command line parameter. If the code on a line extends past the comment 411column, the comment starts further to the right, and the right margin may be 412automatically extended in extreme cases. 413.Ss Preprocessor lines 414In general, 415.Nm 416leaves preprocessor lines alone. The only 417reformatting that it will do is to straighten up trailing comments. It 418leaves embedded comments alone. Conditional compilation 419.Pq Ic #ifdef...#endif 420is recognized and 421.Nm 422attempts to correctly 423compensate for the syntactic peculiarities introduced. 424.Ss C syntax 425The 426.Nm 427utility understands a substantial amount about the syntax of C, but it 428has a `forgiving' parser. It attempts to cope with the usual sorts of 429incomplete and misformed syntax. In particular, the use of macros like: 430.Pp 431.Dl #define forever for(;;) 432.Pp 433is handled properly. 434.Sh ENVIRONMENT 435The 436.Nm 437utility uses the 438.Ev HOME 439environment variable. 440.Sh FILES 441.Bl -tag -width "./.indent.pro" -compact 442.It Pa ./.indent.pro 443profile file 444.It Pa ~/.indent.pro 445profile file 446.El 447.Sh HISTORY 448The 449.Nm 450command appeared in 451.Bx 4.2 . 452.Sh BUGS 453The 454.Nm 455utility has even more switches than 456.Xr ls 1 . 457.Pp 458A common mistake that often causes grief is typing: 459.Pp 460.Dl indent *.c 461.Pp 462to the shell in an attempt to indent all the 463.Em C 464programs in a directory. 465This is probably a bug, not a feature. 466