new version from James Gosling <jag@Sun.COM>
[unix-history] / usr / src / usr.bin / indent / indent.1
index 40973a5..72c5447 100644 (file)
-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1985 Sun Microsystems, Inc.
+.\" Copyright (c) 1980 The Regents of the University of California.
+.\" Copyright (c) 1976 Board of Trustees of the University of Illinois.
+.\" All rights reserved.
 .\"
 .\"
-.\"    @(#)indent.1    6.1 (Berkeley) %G%
+.\" Redistribution and use in source and binary forms are permitted
+.\" provided that the above copyright notice and this paragraph are
+.\" duplicated in all such forms and that any documentation,
+.\" advertising materials, and other materials related to such
+.\" distribution and use acknowledge that the software was developed
+.\" by the University of California, Berkeley, the University of Illinois,
+.\" Urbana, and Sun Microsystems, Inc.  The name of either University
+.\" or Sun Microsystems may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission.
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\" 
+.\"    @(#)indent.1    6.5 (Berkeley) %G%
 .\"
 .\"
-.TH INDENT 1 ""
-.UC 5
+
+.TH INDENT 1 "
 .SH NAME
 indent \- indent and format C program source
 .SH SYNOPSIS
 .SH NAME
 indent \- indent and format C program source
 .SH SYNOPSIS
-.B indent
-.I input
-[
-.I output
-] [
-.I flags
-]
+.in +\w'\fBindent \fR'u
+.ti -\w'\fBindent \fR'u
+\fBindent \fR [ \fIinput-file\fR [ \fIoutput-file\fR ] ]
+[\ \fB\-bad\fR\ |\ \fB\-nbad\fR\ ]
+[\ \fB\-bap\fR\ |\ \fB\-nbap\fR\ ]
+[\ \fB\-bbb\fR\ |\ \fB\-nbbb\fR\ ]
+[\ \fB\-bc\fR\ |\ \fB\-nbc\fR\ ]
+[\ \fB\-bl\fR\ ]
+[\ \fB\-br\fR\ ]
+[\ \fB\-c\fIn\fR\ ]
+[\ \fB\-cd\fIn\fR\ ]
+[\ \fB\-cdb\fR\ |\ \fB\-ncdb\fR\ ]
+[\ \fB\-ce\fR\ |\ \fB\-nce\fR\ ]
+[\ \fB\-ci\fIn\fR\ ]
+[\ \fB\-cli\fIn\fR\ ]
+[\ \fB\-d\fIn\fR\ ]
+[\ \fB\-di\fIn\fR\ ]
+[\ \fB\-fc1\fR\ |\ \fB\-nfc1\fR\ ]
+[\ \fB\-i\fIn\fR\ ]
+[\ \fB\-ip\fR\ |\ \fB\-nip\fR\ ]
+[\ \fB\-l\fIn\fR\ ]
+[\ \fB\-lc\fIn\fR\ ]
+[\ \fB\-lp\fR\ |\ \fB\-nlp\fR\ ]
+[\ \fB\-pcs\fR\ |\ \fB\-npcs\fR\ ]
+[\ \fB\-npro\fR\ ]
+[\ \fB\-psl\fR\ |\ \fB\-npsl\fR\ ]
+[\ \fB\-sc\fR\ |\ \fB\-nsc\fR\ ]
+[\ \fB\-sob\fR\ |\ \fB\-nsob\fR\ ]
+[\ \fB\-st\fR\ ]
+[\ \fB\-troff\fR\ ]
+[\ \fB\-v\fR\ |\ \fB\-nv\fR\ ]
 .SH DESCRIPTION
 .I Indent
 .SH DESCRIPTION
 .I Indent
-is intended primarily as a C program formatter.
-Specifically,
-.I indent
-will:
-.IP \(bu
-indent code lines
-.IP \(bu
-align comments
-.IP \(bu
-insert spaces around operators where necessary
-.IP \(bu
-break up declaration lists as in ``int a,b,c;''.
-.PP
-.I Indent
-will not break up long statements to make them fit within the
-maximum line length, but it will flag lines that are too long.  Lines
-will be broken so that each statement starts a new line, and braces
-will appear alone on a line.  (See the \-br option to inhibit this.)
-Also, an attempt is made to line up identifiers in declarations.
-.PP
-The 
-.I flags
-which can be specified follow. They
-may appear before or after the file names.
-If the
-.I output
-file is omitted, the formatted file will be written
-back into
-.I input
-and a ``backup'' copy of
-.I input
-will be written in the current directory.
+is a \fBC\fR program formatter.  It reformats the \fBC\fR program in the
+\fIinput-file\fR according to the switches.  The switches which can be
+specified are described below. They may appear before or after the file
+names.
+.LP
+\fBNOTE\fP: If you only specify an \fIinput-file\fR, the formatting is
+done `in-place', that is, the formatted file is written back into
+.I input-file
+and a backup copy of
+.I input-file
+is written in the current directory.  If
+.I input-file
+is named `/blah/blah/file', the backup file is named
+.RI file .BAK.
+.LP
 If
 If
-.I input
-is named ``/blah/blah/file'',
-the backup file will be
-named ``.Bfile''.
-If
-.I output
+.I output-file
 is specified,
 .I indent
 checks to make sure it is different from
 is specified,
 .I indent
 checks to make sure it is different from
-.IR input .
-.PP
-The following flags may be used to control the formatting
-style imposed by
+.IR input-file .
+.SH OPTIONS
+.LP
+The options listed below control the formatting style imposed by
 .IR indent .
 .IR indent .
-.TP 10
-.BI \-l nnn
-Maximum length of an output line.  The default is 75.
-.TP 10
-.BI \-c nnn
-The column in which comments will start.  The default is 33.
-.TP 10
-.BI \-cd nnn
-The column in which comments on declarations will start.  The default
-is for these comments to start in the same column as other comments.
-.TP 10
-.BI \-i nnn
-The number of spaces for one indentation level.  The default is 4.
-.TP 10
-.BR \-dj , \-ndj
-.B \-dj
-will cause declarations to be left justified. 
-.B \-ndj
-will cause
-them to be indented the same as code.  The default is
-.BR \-ndj .
-.TP 10
-.BR \-v , \-nv
-.B \-v turns on ``verbose'' mode,
-.B \-nv
-turns it off.  When in verbose mode,
-.I indent
-will report when it 
-splits one line of input into two or more lines of output,
-and it will give some size statistics at completion. 
-The default is
-.BR \-nv .
-.TP 10
+.TP 15
+.BR \-bap , \-nbap
+If
+.B \-bap
+is specified, a blank line is forced after every procedure body.  Default:
+.B \-nbap.
+.TP 15
+.BR \-bad , \-nbad
+If
+.B \-bad
+is specified, a blank line is forced after every block of
+declarations.  Default:  
+.B \-nbad.
+.TP 15
+.BR \-bbb , \-nbbb
+If
+.B \-bbb
+is specified, a blank line is forced before every block comment.  Default:
+.B \-nbbb.
+.TP 15
 .BR \-bc , \-nbc
 If
 .B \-bc
 .BR \-bc , \-nbc
 If
 .B \-bc
-is specified, then a newline will be forced after each
-comma in a declaration. 
+is specified, then a newline is forced after each comma in a declaration. 
 .B \-nbc
 .B \-nbc
-will turn off this option.  The default is
+turns off this option.  The default is
 .BR \-bc .
 .BR \-bc .
-.TP 10
-.BI \-d nnn
-This option controls the placement of comments
-which are not to the right of code.
-Specifying
-.B \-d2
-means that such comments will be placed two
-indentation levels to the left of code.
-The default
-.B \-d0
-lines up these comments with the code.
-See the section on comment indentation below.
-.TP 10
+.TP 15
 .BR \-br , \-bl
 Specifying
 .B \-bl
 .BR \-br , \-bl
 Specifying
 .B \-bl
-will cause
-complex statements to be lined up like this:
+lines up compound statements like this:
 .ne 4
 .nf
 .ne 4
 .nf
+.ft L
     if (...)
     {
         code
     }
     if (...)
     {
         code
     }
+.ft R
 .fi
 Specifying
 .B \-br
 .fi
 Specifying
 .B \-br
-(the default) will make them look like this:
+(the default) makes them look like this:
 .ne 3
 .nf
 .ne 3
 .nf
+.ft L
     if (...) {
         code
     }
     if (...) {
         code
     }
+.ft R
 .fi
 .fi
-.PP
-You may set up your own ``profile'' of defaults to
-.I indent
-by creating the file ``.indent.pro'' in your login directory
-and including whatever switches you like.
-If
-.I 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,
-will always override profile switches.
-The profile
-file must be a single line of not more than 127 characters.
-The switches should be separated on the line by spaces or tabs.
-.PP
-.B Multi-line expressions
-.PP
-.I Indent
-will not break up complicated expressions that extend over multiple
-lines, but it will usually correctly indent such expressions which have
-already been broken up.  Such an expression might end up looking like this:
-.ne 10
-.in +4
+.LP
+.TP 15
+.BI \-c n
+The column in which comments on code start.  The default is 33.  
+.TP 15
+.BI \-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.
+.TP 15
+.BI \-cdb , \-ncdb
+Enables (disables) the placement of comment delimiters on blank lines.  With
+this option enabled, comments look like this:
 .nf
 .nf
-x =
-        (
-            (Arbitrary parenthesized expression)
-            +
-            (
-                (Parenthesized expression)
-                *
-                (Parenthesized expression)
-            )
-        );
-
+.ft L
+.ne 3
+       /*
+        * this is a comment
+        */
+.ft R
 .fi
 .fi
-.PP
+Rather than like this:
+.nf
+.ft L
+       /* this is a comment */
+.ft R
+.fi
+This only affects block comments, not comments to the right of code. The default is
+.B \-cdb .
+.TP 15
+.BI \-ce , \-nce
+Enables (disables) forcing `else's to cuddle up to the immediatly preceeding
+`}'.  The default is
+.B \-ce .
+.TP 15
+.BI \-ci n
+Sets the continuation indent to be \fIn\fR.  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 \fB\-lp\fR is in effect.
+\fB\-ci\fR defaults to the same value as \fB\-i\fR.
+.TP 15
+.BI \-cli n
+Causes case labels to be indented
+.I n
+tab stops to the right of the containing \fBswitch\fR statement.
+\fB-cli0.5\fR causes case labels to be indented half a tab stop.  The
+default is
+.B \-cli0 .
+.TP 15
+.BI \-d n
+Controls the placement of comments which are not to the
+right of code.  The default
+.B \-d1
+means that such comments are placed one indentation level to the
+left of code.  Specifying
+.B \-d0
+lines up these comments with the code.  See the section on comment
+indentation below.
+.TP 15
+.BI \-di n
+Specifies the indentation, in character positions, from a declaration keyword
+to the following identifier.  The default is
+.B \-di16 .
+.if 0 \{.TP 15
+.BR \-dj , \-ndj
+.B \-dj
+left justifies declarations.
+.B \-ndj
+indents declarations the same as code.  The default is
+.BR \-ndj .
+.TP 15
+.BI \-ei , \-nei
+Enables (disables) special
+.B else-if
+processing.  If it's enabled,
+.BR if "s"
+following
+.BR else "s"
+will have the same indendation as the preceeding
+.B if
+statement.\}
+.TP 15
+.BI \-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, \fB\-nfc1\fR should be
+used.  The default is \fB\-fc1\fR.
+.TP 15
+.BI \-i n
+The number of spaces for one indentation level.  The default is 4.
+.TP 15
+.BI \-ip , \-nip
+Enables (disables) the indentation of parameter declarations from the left
+margin.  The default is
+.B \-ip .
+.TP 15
+.BI \-l n
+Maximum length of an output line.  The default is 75.
+.TP 15
+.B \-npro
+Causes the profile files, `./.indent.pro' and `~/.indent.pro', to be ignored.
+.TP 15
+.BI \-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 -nlp
+in effect:
+.ne 2
+.nf
+.ft L
+    p1 = first_procedure(second_procedure(p2, p3),
+        third_procedure(p4, p5));
+.ft R
+.fi
+.ne 5
+With \fB-lp\fR in effect (the default) the code looks somewhat clearer:
+.nf
+.ft L
+    p1 = first_procedure(second_procedure(p2, p3),
+                         third_procedure(p4, p5));
+.ft R
+.fi
+.ne 5
+Inserting a couple more newlines we get:
+.nf
+.ft L
+    p1 = first_procedure(second_procedure(p2,
+                                          p3),
+                         third_procedure(p4,
+                                         p5));
+.ft R
+.fi
+.TP 15
+.B \-pcs , \-npcs
+If true (\fB-pcs\fR) all procedure calls will have a space inserted between
+the name and the '('.  The default is 
+.B \-npcs
+.TP 15
+.B \-psl , \-npsl
+If true (\fB-psl\fR) 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 
+.B -psl
+.TP 15
+.BI \-sc , \-nsc
+Enables (disables) the placement of asterisks (`*'s) at the left edge of all
+comments.
+.TP 15
+.BR \-sob , \-nsob
+If
+.B \-sob
+is specified, indent will swallow optional blank lines.  You can use this to
+get rid of blank lines after declarations.  Default:
+.B \-nsob
+.TP 15
+.B \-st
+Causes
+.B indent
+to take its input from stdin, and put its output to stdout.
+.TP 15
+.BI \-T typename
+Adds
+.I typename
+to the list of type keywords.  Names accumulate:
+.B \-T
+can be specified more than once.  You need to specify all the typenames that
+appear in your program that are defined by \fBtypedef\fRs \- 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: \fBtypedef\fR causes a syntactic change in the
+laguage and \fIindent\fR can't find all \fBtypedef\fRs.
+.TP 15
+.B \-troff
+Causes
+.B indent
+to format the program for processing by troff.  It will produce a fancy
+listing in much the same spirit as
+.BR vgrind.
+If the output file is not specified, the default is standard output,
+rather than formatting in place.
+.TP 15
+.BR \-v , \-nv
+.B \-v
+turns on `verbose' mode,
+.B \-nv
+turns it off.  When in verbose mode,
+.I 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
+.BR \-nv .
+.SH "FURTHER DESCRIPTION"
+.LP
+You may set up your own `profile' of defaults to
+.I indent
+by creating a file called
+.BI . indent . pro
+in either your login directory 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
+.I 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.
+.LP
 .B Comments
 .B Comments
-.PP
+.LP
+.IR "`Box' comments" .
 .I Indent
 .I Indent
-recognizes four kinds of comments. 
-They are: straight text, ``box'' comments,
-UNIX-style comments,
-and comments that should be passed through unchanged. 
-The action taken with these
-various types are as follows:
-.PP
-.I ``Box'' comments.\ \  
+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.
+.LP
+.IR "Straight text" .
+All other comments are treated as straight text.
 .I Indent
 .I Indent
-assumes that any comment with a dash
-immediately after the start of comment (i.e. ``/*\-'')
-is a comment surrounded by a box of stars.  Each line
-of such a comment will be left unchanged,
-except that the first non-blank
-character of each successive line will be lined up with the beginning
-slash of the first line.  Box comments will be indented (see below).
-.PP
-.I ``Unix-style'' comments.\ \ 
-This is the type of section header which is used 
-extensively in the UNIX system source.  If the start
-of comment (``/*'') appears on a
-line by itself, indent assumes that it is a
-UNIX-style comment.  These will be
-treated similarly to box comments, except
-the first non-blank character on each
-line will be lined up with the `*' of the ``/*''.
-.PP
-.I Unchanged comments.\ \ 
-Any comment which starts in column 1 will be left completely
-unchanged.  This is intended primarily for documentation header pages.
-The check for unchanged comments is made before
-the check for UNIX-style comments.
-.PP
-.I Straight text.\ \ 
-All other comments are treated as straight text. 
-.I Indent
-will fit
-as many words (separated by blanks, tabs, or newlines) on a line as possible.
-Straight text comments will be indented.
-.PP
+fits as many words (separated by blanks, tabs, or newlines) on a
+line as possible.  Blank lines break paragraphs.
+.LP
 .B Comment indentation
 .B Comment indentation
-.PP
-Box, UNIX-style, and straight text comments may be indented.
-If a comment is on a line
-with code it will be started in the ``comment
-column'', which is set by the
-.B \-cnnn
-command line parameter.
-Otherwise, the
-comment will be started at 
-.I nnn
-indentation levels less than where code is
-currently being placed, where
-.I nnn
+.LP
+If a comment is on a line with code it is started in the `comment column',
+which is set by the
+.BI \-c n
+command line parameter.  Otherwise, the comment is started at
+.I n
+indentation levels less than where code is currently being placed, where
+.I n
 is specified by the
 is specified by the
-.B \-dnnn
-command line parameter.  (Indented
-comments will never be placed in column 1.)
-If the code on a line extends past the comment column,
-the comment will be moved to the next line.
-.SH DIAGNOSTICS
-Diagnostic error messages, mostly to
-tell that a text line has been broken
-or is too long for the output line.
+.BI \-d 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.
+.LP
+.B Preprocessor lines
+.LP
+In general, \fIindent\fR leaves preprocessor lines alone.  The only
+reformmatting that it will do is to straighten up trailing comments.  It
+leaves imbedded comments alone.  Conditional compilation
+(\fB#ifdef...#endif\fR) is recognized and \fIindent\fR attempts to correctly
+compensate for the syntactic peculiarites introduced.
+.LP
+.B C syntax
+.LP
+\fIIndent\fR 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:
+.nf
+.ft L
+        #define forever for(;;)
+.ft R
+.fi
+is handled properly.
 .SH FILES
 .DT
 .SH FILES
 .DT
-\&.indent.pro  profile file
+.br
+\&./.indent.pro        profile file
+.br
 .SH BUGS
 .SH BUGS
-Does not know how to format ``long'' declarations.
+.I Indent
+has even more switches than \fIls\fR.
+
+.ne 5
+A common mistake that often causes grief is typing:
+.nf
+.ft L
+    indent *.c
+.ft R
+.fi
+to the shell in an attempt to indent all the \fBC\fR programs in a directory.
+This is probably a bug, not a feature.