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