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