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