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