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