usr.bin/indent/indent.1

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