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