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