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