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