usr.bin/indent/indent.1

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