Annotation of src/usr.bin/indent/indent.1, Revision 1.13
1.13 ! deraadt 1: .\" $OpenBSD: indent.1,v 1.12 2003/06/10 09:12:10 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.10 pjanzen 35: .Dd July 1, 1993
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
43: .Op Ar input-file Op Ar output-file
44: .Op Fl bad | Fl nbad
45: .Op Fl bap | Fl nbap
46: .Bk -words
47: .Op Fl bbb | Fl nbbb
48: .Ek
49: .Op Fl \&bc | Fl nbc
50: .Op Fl \&bl
51: .Op Fl \&br
52: .Op Fl c Ns Ar n
53: .Op Fl \&cd Ns Ar n
54: .Bk -words
55: .Op Fl cdb | Fl ncdb
56: .Ek
57: .Op Fl \&ce | Fl nce
58: .Op Fl \&ci Ns Ar n
59: .Op Fl cli Ns Ar n
60: .Op Fl d Ns Ar n
61: .Op Fl \&di Ns Ar n
62: .Bk -words
63: .Op Fl fc1 | Fl nfc1
64: .Ek
65: .Op Fl i Ns Ar n
66: .Op Fl \&ip | Fl nip
67: .Op Fl l Ns Ar n
68: .Op Fl \&lc Ns Ar n
69: .Op Fl \&lp | Fl nlp
70: .Op Fl npro
71: .Op Fl pcs | Fl npcs
72: .Op Fl psl | Fl npsl
73: .Op Fl \&sc | Fl nsc
74: .Bk -words
75: .Op Fl sob | Fl nsob
76: .Ek
77: .Op Fl \&st
78: .Op Fl troff
79: .Op Fl v | Fl \&nv
80: .Sh DESCRIPTION
1.7 aaron 81: .Nm
1.1 deraadt 82: is a
83: .Ar C
1.8 aaron 84: program formatter.
85: It reformats the
1.1 deraadt 86: .Ar C
87: program in the
88: .Ar input-file
1.8 aaron 89: according to the switches.
90: The switches which can be specified are described below.
91: They may appear before or after the file names.
1.1 deraadt 92: .Pp
1.8 aaron 93: .Sy NOTE :
1.1 deraadt 94: If you only specify an
1.8 aaron 95: .Ar input-file ,
1.1 deraadt 96: the formatting is
1.8 aaron 97: done
98: .Dq in-place ,
99: that is, the formatted file is written back into
1.1 deraadt 100: .Ar input-file
101: and a backup copy of
102: .Ar input-file
1.8 aaron 103: is written in the current directory.
104: If
1.1 deraadt 105: .Ar input-file
106: is named
1.8 aaron 107: .Pa /blah/blah/file ,
1.1 deraadt 108: the backup file is named
109: .Pa file.BAK .
1.10 pjanzen 110: If
111: .Pa file.BAK
112: exists, it is overwritten.
1.1 deraadt 113: .Pp
114: If
115: .Ar output-file
116: is specified,
1.7 aaron 117: .Nm
1.1 deraadt 118: checks to make sure it is different from
1.7 aaron 119: .Ar input-file .
1.1 deraadt 120: .Pp
121: The options listed below control the formatting style imposed by
1.8 aaron 122: .Nm indent .
1.1 deraadt 123: .Bl -tag -width Op
124: .It Fl bad , nbad
125: If
126: .Fl bad
127: is specified, a blank line is forced after every block of
1.8 aaron 128: declarations.
129: Default:
130: .Fl nbad .
1.1 deraadt 131: .It Fl bap , nbap
132: If
133: .Fl bap
1.8 aaron 134: is specified, a blank line is forced after every procedure body.
135: Default:
1.1 deraadt 136: .Fl nbap .
137: .It Fl bbb , nbbb
138: If
139: .Fl bbb
1.10 pjanzen 140: is specified, a blank line is forced before every block comment.
141: Default:
1.1 deraadt 142: .Fl nbbb .
143: .It Fl \&bc , nbc
144: If
145: .Fl \&bc
146: is specified, then a newline is forced after each comma in a declaration.
147: .Fl nbc
1.8 aaron 148: turns off this option.
149: The default is
1.10 pjanzen 150: .Fl \&nbc .
1.1 deraadt 151: .It Fl \&br , \&bl
152: Specifying
153: .Fl \&bl
154: lines up compound statements like this:
155: .ne 4
156: .Bd -literal -offset indent
157: if (...)
158: {
159: code
160: }
161: .Ed
162: .Pp
163: Specifying
164: .Fl \&br
165: (the default) makes them look like this:
166: .ne 3
167: .Bd -literal -offset indent
168: if (...) {
169: code
170: }
171: .Ed
172: .Pp
1.4 deraadt 173: .It Fl c Ns Ar n
1.8 aaron 174: The column in which comments on code start.
175: The default is 33.
1.4 deraadt 176: .It Fl cd Ns Ar n
1.8 aaron 177: The column in which comments on declarations start.
178: The default
1.1 deraadt 179: is for these comments to start in the same column as those on code.
180: .It Fl cdb , ncdb
1.8 aaron 181: Enables (disables) the placement of comment delimiters on blank lines.
182: With this option enabled, comments look like this:
1.1 deraadt 183: .Bd -literal -offset indent
184: .ne 3
185: /*
186: * this is a comment
187: */
188: .Ed
189: .Pp
190: Rather than like this:
191: .Bd -literal -offset indent
192: /* this is a comment */
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.
232: The default
1.1 deraadt 233: .Fl \&d\&1
234: means that such comments are placed one indentation level to the
1.8 aaron 235: left of code.
236: Specifying
1.1 deraadt 237: .Fl \&d\&0
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.
263: .It Fl fc1 , nfc1
264: Enables (disables) the formatting of comments that start in column 1.
1.8 aaron 265: Often, comments whose leading
266: .Ql /
267: is in column 1 have been carefully have formatted by the programmer.
268: In such cases,
1.1 deraadt 269: .Fl nfc1
270: should be
1.8 aaron 271: used.
272: The default is
273: .Fl fc1 .
1.6 aaron 274: .It Fl i Ns Ar n
1.8 aaron 275: The number of spaces for one indentation level.
276: The default is 8.
1.1 deraadt 277: .It Fl \&ip , nip
278: Enables (disables) the indentation of parameter declarations from the left
1.8 aaron 279: margin.
280: The default is
281: .Fl \&ip .
1.6 aaron 282: .It Fl l Ns Ar n
1.8 aaron 283: Maximum length of an output line.
284: The default is 75.
1.1 deraadt 285: .It Fl \&lp , nlp
1.8 aaron 286: Lines up code surrounded by parenthesis in continuation lines.
287: If a line
1.1 deraadt 288: has a left paren which is not closed on that line, then continuation lines
289: will be lined up to start at the character position just after the left
1.8 aaron 290: paren.
291: For example, here is how a piece of continued code looks with
1.1 deraadt 292: .Fl nlp
293: in effect:
294: .ne 2
295: .Bd -literal -offset indent
1.10 pjanzen 296: p1 = first_procedure(second_procedure(p2, p3),
297: \ \ third_procedure(p4,p5));
1.1 deraadt 298: .Ed
299: .Pp
300: .ne 5
301: With
302: .Fl lp
303: in effect (the default) the code looks somewhat clearer:
304: .Bd -literal -offset indent
1.10 pjanzen 305: p1\ =\ first_procedure(second_procedure(p2,\ p3),
306: \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,p5));
1.1 deraadt 307: .Ed
308: .Pp
309: .ne 5
310: Inserting two more newlines we get:
311: .Bd -literal -offset indent
1.10 pjanzen 312: p1\ =\ first_procedure(second_procedure(p2,
313: \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3),
314: \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,
315: \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5));
1.1 deraadt 316: .Ed
317: .It Fl npro
318: Causes the profile files,
1.8 aaron 319: .Pa ./.indent.pro
1.1 deraadt 320: and
1.8 aaron 321: .Pa ~/.indent.pro ,
1.1 deraadt 322: to be ignored.
323: .It Fl pcs , npcs
324: If true
325: .Pq Fl pcs
326: all procedure calls will have a space inserted between
1.8 aaron 327: the name and the
328: .Ql ( .
329: The default is
330: .Fl npcs .
1.1 deraadt 331: .It Fl psl , npsl
332: If true
333: .Pq Fl psl
334: the names of procedures being defined are placed in
1.8 aaron 335: column 1 \- their types, if any, will be left on the previous lines.
336: The default is
337: .Fl psl .
1.1 deraadt 338: .It Fl \&sc , nsc
1.8 aaron 339: Enables (disables) the placement of asterisks
340: .Pq Ql *
341: at the left edge of all comments.
1.1 deraadt 342: .It Fl sob , nsob
343: If
344: .Fl sob
1.8 aaron 345: is specified, indent will swallow optional blank lines.
346: You can use this to get rid of blank lines after declarations.
347: Default:
348: .Fl nsob .
1.1 deraadt 349: .It Fl \&st
350: Causes
1.7 aaron 351: .Nm
1.1 deraadt 352: to take its input from stdin, and put its output to stdout.
1.6 aaron 353: .It Fl T Ns Ar typename
1.1 deraadt 354: Adds
355: .Ar typename
1.8 aaron 356: to the list of type keywords.
357: Names accumulate:
1.1 deraadt 358: .Fl T
1.8 aaron 359: can be specified more than once.
360: You need to specify all the typenames that
1.1 deraadt 361: appear in your program that are defined by
362: .Ic typedef
363: \- nothing will be
364: harmed if you miss a few, but the program won't be formatted as nicely as
1.8 aaron 365: it should.
366: This sounds like a painful thing to have to do, but it's really
1.1 deraadt 367: a symptom of a problem in C:
368: .Ic typedef
369: causes a syntactic change in the
370: language and
1.7 aaron 371: .Nm
1.1 deraadt 372: can't find all
373: instances of
374: .Ic typedef .
375: .It Fl troff
376: Causes
1.7 aaron 377: .Nm
1.1 deraadt 378: to format the program for processing by
379: .Xr troff 1 .
380: It will produce a fancy
381: listing in much the same spirit as
382: .Xr vgrind 1 .
383: If the output file is not specified, the default is standard output,
384: rather than formatting in place.
385: .It Fl v , \&nv
386: .Fl v
1.8 aaron 387: turns on
388: .Dq verbose
389: mode;
1.1 deraadt 390: .Fl \&nv
1.8 aaron 391: turns it off.
392: When in verbose mode,
1.7 aaron 393: .Nm
1.1 deraadt 394: reports when it splits one line of input into two or more lines of output,
1.9 aaron 395: and gives some size statistics at completion.
396: The default is
1.8 aaron 397: .Fl \&nv .
1.1 deraadt 398: .El
399: .Pp
1.8 aaron 400: You may set up your own
401: .Dq profile
402: of defaults to
1.7 aaron 403: .Nm
1.1 deraadt 404: by creating a file called
405: .Pa .indent.pro
406: in your login directory and/or the current directory and including
1.8 aaron 407: whatever switches you like.
408: An
409: .Pa \&.indent.pro
410: file in the current directory takes
411: precedence over the one in your login directory.
412: If
1.7 aaron 413: .Nm
1.1 deraadt 414: is run and a profile file exists, then it is read to set up the program's
1.8 aaron 415: defaults.
416: Switches on the command line, though, always override profile
417: switches.
418: The switches should be separated by spaces, tabs or newlines.
1.1 deraadt 419: .Ss Comments
420: .Sq Em Box
421: .Em comments .
1.7 aaron 422: .Nm
1.1 deraadt 423: assumes that any comment with a dash, star, or newline immediately after
1.8 aaron 424: the start of comment (that is,
425: .Ql /*\- ,
426: .Ql /** ,
427: or
428: .Ql /*
429: followed immediately by a newline character) is a comment surrounded
430: by a box of stars.
431: Each line of such a comment is left unchanged, except
1.1 deraadt 432: that its indentation may be adjusted to account for the change in indentation
433: of the first line
434: of the comment.
435: .Pp
436: .Em Straight text .
437: All other comments are treated as straight text.
1.7 aaron 438: .Nm
1.1 deraadt 439: fits as many words (separated by blanks, tabs, or newlines) on a
1.8 aaron 440: line as possible.
441: Blank lines break paragraphs.
1.1 deraadt 442: .Ss Comment indentation
1.8 aaron 443: If a comment is on a line with code it is started in the
444: .Dq comment column ,
1.1 deraadt 445: which is set by the
1.6 aaron 446: .Fl c Ns Ns Ar n
1.8 aaron 447: command line parameter.
448: Otherwise, the comment is started at
1.1 deraadt 449: .Ar n
450: indentation levels less than where code is currently being placed, where
451: .Ar n
452: is specified by the
1.6 aaron 453: .Fl d Ns Ns Ar n
1.8 aaron 454: command line parameter.
455: If the code on a line extends past the comment
1.1 deraadt 456: column, the comment starts further to the right, and the right margin may be
457: automatically extended in extreme cases.
458: .Ss Preprocessor lines
459: In general,
1.7 aaron 460: .Nm
1.8 aaron 461: leaves preprocessor lines alone.
462: The only
463: reformatting that it will do is to straighten up trailing comments.
464: It leaves embedded comments alone.
465: Conditional compilation
1.1 deraadt 466: .Pq Ic #ifdef...#endif
467: is recognized and
1.7 aaron 468: .Nm
1.1 deraadt 469: attempts to correctly
470: compensate for the syntactic peculiarities introduced.
471: .Ss C syntax
1.7 aaron 472: .Nm
1.1 deraadt 473: understands a substantial amount about the syntax of C, but it
1.8 aaron 474: has a
475: .Dq forgiving
476: parser.
477: It attempts to cope with the usual sorts of
478: incomplete and misformed syntax.
479: In particular, the use of macros like:
1.1 deraadt 480: .Pp
481: .Dl #define forever for(;;)
482: .Pp
483: is handled properly.
484: .Sh ENVIRONMENT
1.8 aaron 485: .Bl -tag -width Ds
486: .It Ev HOME
487: Used to locate the full path to
488: .Pa ~/.indent.pro .
489: .El
1.1 deraadt 490: .Sh FILES
491: .Bl -tag -width "./.indent.pro" -compact
492: .It Pa ./.indent.pro
493: profile file
494: .It Pa ~/.indent.pro
495: profile file
496: .El
497: .Sh HISTORY
498: The
1.7 aaron 499: .Nm
1.1 deraadt 500: command appeared in
501: .Bx 4.2 .
502: .Sh BUGS
1.7 aaron 503: .Nm
1.1 deraadt 504: has even more switches than
505: .Xr ls 1 .
506: .Pp
507: .ne 5
508: A common mistake that often causes grief is typing:
509: .Pp
510: .Dl indent *.c
511: .Pp
512: to the shell in an attempt to indent all the
513: .Nm C
514: programs in a directory.
515: 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