diff options
Diffstat (limited to 'usr.bin/indent/indent.1')
| -rw-r--r-- | usr.bin/indent/indent.1 | 452 |
1 files changed, 452 insertions, 0 deletions
diff --git a/usr.bin/indent/indent.1 b/usr.bin/indent/indent.1 new file mode 100644 index 0000000..c44964a --- /dev/null +++ b/usr.bin/indent/indent.1 @@ -0,0 +1,452 @@ +.\" Copyright (c) 1980, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1976 Board of Trustees of the University of Illinois. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)indent.1 8.1 (Berkeley) 7/1/93 +.\" +.Dd July 1, 1993 +.Dt INDENT 1 +.Os BSD 4.2 +.Sh NAME +.Nm indent +.Nd indent and format C program source +.Sh SYNOPSIS +.Nm indent +.Op Ar input-file Op Ar output-file +.Op Fl bad | Fl nbad +.Op Fl bap | Fl nbap +.Bk -words +.Op Fl bbb | Fl nbbb +.Ek +.Op Fl \&bc | Fl nbc +.Op Fl \&bl +.Op Fl \&br +.Op Fl c Ns Ar n +.Op Fl \&cd Ns Ar n +.Bk -words +.Op Fl cdb | Fl ncdb +.Ek +.Op Fl \&ce | Fl nce +.Op Fl \&ci Ns Ar n +.Op Fl cli Ns Ar n +.Op Fl d Ns Ar n +.Op Fl \&di Ns Ar n +.Bk -words +.Op Fl fc1 | Fl nfc1 +.Ek +.Op Fl i Ns Ar n +.Op Fl \&ip | Fl nip +.Op Fl l Ns Ar n +.Op Fl \&lc Ns Ar n +.Op Fl \&lp | Fl nlp +.Op Fl npro +.Op Fl pcs | Fl npcs +.Op Fl psl | Fl npsl +.Op Fl \&sc | Fl nsc +.Bk -words +.Op Fl sob | Fl nsob +.Ek +.Op Fl \&st +.Op Fl troff +.Op Fl v | Fl \&nv +.Sh DESCRIPTION +.Nm Indent +is a +.Ar C +program formatter. It reformats the +.Ar C +program in the +.Ar input-file +according to the switches. The switches which can be +specified are described below. They may appear before or after the file +names. +.Pp +.Sy NOTE : +If you only specify an +.Ar input-file , +the formatting is +done `in-place', that is, the formatted file is written back into +.Ar input-file +and a backup copy of +.Ar input-file +is written in the current directory. If +.Ar input-file +is named +.Sq Pa /blah/blah/file , +the backup file is named +.Pa file.BAK . +.Pp +If +.Ar output-file +is specified, +.Nm indent +checks to make sure it is different from +.Ar input-file . +.Pp +The options listed below control the formatting style imposed by +.Nm indent . +.Bl -tag -width Op +.It Fl bad , nbad +If +.Fl bad +is specified, a blank line is forced after every block of +declarations. Default: +.Fl nbad . +.It Fl bap , nbap +If +.Fl bap +is specified, a blank line is forced after every procedure body. Default: +.Fl nbap . +.It Fl bbb , nbbb +If +.Fl bbb +is specified, a blank line is forced before every block comment. Default: +.Fl nbbb . +.It Fl \&bc , nbc +If +.Fl \&bc +is specified, then a newline is forced after each comma in a declaration. +.Fl nbc +turns off this option. The default is +.Fl \&bc . +.It Fl \&br , \&bl +Specifying +.Fl \&bl +lines up compound statements like this: +.ne 4 +.Bd -literal -offset indent +if (...) +{ + code +} +.Ed +.Pp +Specifying +.Fl \&br +(the default) makes them look like this: +.ne 3 +.Bd -literal -offset indent +if (...) { + code +} +.Ed +.Pp +.It Fl c n +The column in which comments on code start. The default is 33. +.It Fl cd n +The column in which comments on declarations start. The default +is for these comments to start in the same column as those on code. +.It Fl cdb , ncdb +Enables (disables) the placement of comment delimiters on blank lines. With +this option enabled, comments look like this: +.Bd -literal -offset indent +.ne 3 + /* + * this is a comment + */ +.Ed +.Pp +Rather than like this: +.Bd -literal -offset indent + /* this is a comment */ +.Ed +.Pp +This only affects block comments, not comments to the right of +code. The default is +.Fl cdb . +.It Fl ce , nce +Enables (disables) forcing `else's to cuddle up to the immediately preceding +`}'. The default is +.Fl \&ce . +.It Fl \&ci Ns Ar n +Sets the continuation indent to be +.Ar n . +Continuation +lines will be indented that far from the beginning of the first line of the +statement. Parenthesized expressions have extra indentation added to +indicate the nesting, unless +.Fl \&lp +is in effect. +.Fl \&ci +defaults to the same value as +.Fl i . +.It Fl cli Ns Ar n +Causes case labels to be indented +.Ar n +tab stops to the right of the containing +.Ic switch +statement. +.Fl cli0 .5 +causes case labels to be indented half a tab stop. The +default is +.Fl cli0 . +.It Fl d Ns Ar n +Controls the placement of comments which are not to the +right of code. The default +.Fl \&d\&1 +means that such comments are placed one indentation level to the +left of code. Specifying +.Fl \&d\&0 +lines up these comments with the code. See the section on comment +indentation below. +.It Fl \&di Ns Ar n +Specifies the indentation, in character positions, from a declaration keyword +to the following identifier. The default is +.Fl di16 . +.It Fl dj , ndj +.Fl \&dj +left justifies declarations. +.Fl ndj +indents declarations the same as code. The default is +.Fl ndj . +.It Fl \&ei , nei +Enables (disables) special +.Ic else-if +processing. If it's enabled, an +.Ic if +following an +.Ic else +will have the same indentation as the preceding +.Ic \&if +statement. +.It Fl fc1 , nfc1 +Enables (disables) the formatting of comments that start in column 1. +Often, comments whose leading `/' is in column 1 have been carefully +hand formatted by the programmer. In such cases, +.Fl nfc1 +should be +used. The default is +.Fl fc1 . +.It Fl i Ns Ar n +The number of spaces for one indentation level. The default is 4. +.It Fl \&ip , nip +Enables (disables) the indentation of parameter declarations from the left +margin. The default is +.Fl \&ip . +.It Fl l Ns Ar n +Maximum length of an output line. The default is 75. +.It Fl \&lp , nlp +Lines up code surrounded by parenthesis in continuation lines. If a line +has a left paren which is not closed on that line, then continuation lines +will be lined up to start at the character position just after the left +paren. For example, here is how a piece of continued code looks with +.Fl nlp +in effect: +.ne 2 +.Bd -literal -offset indent +p1 = first_procedure(second_procedure(p2, p3), +\ \ third_procedure(p4,p5)); +.Ed +.Pp +.ne 5 +With +.Fl lp +in effect (the default) the code looks somewhat clearer: +.Bd -literal -offset indent +p1\ =\ first_procedure(second_procedure(p2,\ p3), +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,p5)); +.Ed +.Pp +.ne 5 +Inserting two more newlines we get: +.Bd -literal -offset indent +p1\ =\ first_procedure(second_procedure(p2, +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3), +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5)); +.Ed +.It Fl npro +Causes the profile files, +.Sq Pa ./.indent.pro +and +.Sq Pa ~/.indent.pro , +to be ignored. +.It Fl pcs , npcs +If true +.Pq Fl pcs +all procedure calls will have a space inserted between +the name and the `('. The default is +.Fl npcs . +.It Fl psl , npsl +If true +.Pq Fl psl +the names of procedures being defined are placed in +column 1 \- their types, if any, will be left on the previous lines. The +default is +.Fl psl . +.It Fl \&sc , nsc +Enables (disables) the placement of asterisks (`*'s) at the left edge of all +comments. +.It Fl sob , nsob +If +.Fl sob +is specified, indent will swallow optional blank lines. You can use this to +get rid of blank lines after declarations. Default: +.Fl nsob . +.It Fl \&st +Causes +.Nm indent +to take its input from stdin, and put its output to stdout. +.It Fl T Ns Ar typename +Adds +.Ar typename +to the list of type keywords. Names accumulate: +.Fl T +can be specified more than once. You need to specify all the typenames that +appear in your program that are defined by +.Ic typedef +\- nothing will be +harmed if you miss a few, but the program won't be formatted as nicely as +it should. This sounds like a painful thing to have to do, but it's really +a symptom of a problem in C: +.Ic typedef +causes a syntactic change in the +language and +.Nm indent +can't find all +instances of +.Ic typedef . +.It Fl troff +Causes +.Nm indent +to format the program for processing by +.Xr troff 1 . +It will produce a fancy +listing in much the same spirit as +.Xr vgrind 1 . +If the output file is not specified, the default is standard output, +rather than formatting in place. +.It Fl v , \&nv +.Fl v +turns on `verbose' mode; +.Fl \&nv +turns it off. When in verbose mode, +.Nm indent +reports when it splits one line of input into two or more lines of output, +and gives some size statistics at completion. The default is +.Fl \&nv . +.El +.Pp +You may set up your own `profile' of defaults to +.Nm indent +by creating a file called +.Pa .indent.pro +in your login directory and/or the current directory and including +whatever switches you like. A `.indent.pro' in the current directory takes +precedence over the one in your login directory. If +.Nm indent +is run and a profile file exists, then it is read to set up the program's +defaults. Switches on the command line, though, always override profile +switches. The switches should be separated by spaces, tabs or newlines. +.Pp +.Ss Comments +.Sq Em Box +.Em comments . +.Nm Indent +assumes that any comment with a dash or star immediately after the start of +comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars. +Each line of such a comment is left unchanged, except that its indentation +may be adjusted to account for the change in indentation of the first line +of the comment. +.Pp +.Em Straight text . +All other comments are treated as straight text. +.Nm Indent +fits as many words (separated by blanks, tabs, or newlines) on a +line as possible. Blank lines break paragraphs. +.Pp +.Ss Comment indentation +If a comment is on a line with code it is started in the `comment column', +which is set by the +.Fl c Ns Ns Ar n +command line parameter. Otherwise, the comment is started at +.Ar n +indentation levels less than where code is currently being placed, where +.Ar n +is specified by the +.Fl d Ns Ns Ar n +command line parameter. If the code on a line extends past the comment +column, the comment starts further to the right, and the right margin may be +automatically extended in extreme cases. +.Pp +.Ss Preprocessor lines +In general, +.Nm indent +leaves preprocessor lines alone. The only +reformatting that it will do is to straighten up trailing comments. It +leaves embedded comments alone. Conditional compilation +.Pq Ic #ifdef...#endif +is recognized and +.Nm indent +attempts to correctly +compensate for the syntactic peculiarities introduced. +.Pp +.Ss C syntax +.Nm Indent +understands a substantial amount about the syntax of C, but it +has a `forgiving' parser. It attempts to cope with the usual sorts of +incomplete and misformed syntax. In particular, the use of macros like: +.Pp +.Dl #define forever for(;;) +.Pp +is handled properly. +.Sh ENVIRONMENT +.Nm Indent +uses the +.Ev HOME +environment variable. +.Sh FILES +.Bl -tag -width "./.indent.pro" -compact +.It Pa ./.indent.pro +profile file +.It Pa ~/.indent.pro +profile file +.El +.Sh HISTORY +The +.Nm indent +command appeared in +.Bx 4.2 . +.Sh BUGS +.Nm Indent +has even more switches than +.Xr ls 1 . +.Pp +.ne 5 +A common mistake that often causes grief is typing: +.Pp +.Dl indent *.c +.Pp +to the shell in an attempt to indent all the +.Nm C +programs in a directory. +This is probably a bug, not a feature. |
