Commit patch from PR 9220 to document all options, and consistently
document defaults. Also, clean up nroff nits.
This commit is contained in:
fair
parent
85b0b4096f
commit
fb3c4927d6
@ -1,4 +1,4 @@
|
||||
.\" $NetBSD: indent.1,v 1.11 1999/03/24 06:25:57 mycroft Exp $
|
||||
.\" $NetBSD: indent.1,v 1.12 2001/03/16 06:23:20 fair Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 1980, 1990, 1993
|
||||
.\" The Regents of the University of California. All rights reserved.
|
||||
@ -48,6 +48,9 @@
|
||||
.Op Ar input-file Op Ar output-file
|
||||
.Ek
|
||||
.Bk -words
|
||||
.Op Fl bacc | Fl nbacc
|
||||
.Ek
|
||||
.Bk -words
|
||||
.Op Fl bad | Fl nbad
|
||||
.Ek
|
||||
.Bk -words
|
||||
@ -107,13 +110,14 @@
|
||||
.Nm
|
||||
is a
|
||||
.Ar C
|
||||
program formatter. It reformats the
|
||||
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.
|
||||
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
|
||||
@ -123,7 +127,8 @@ 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
|
||||
is written in the current directory.
|
||||
If
|
||||
.Ar input-file
|
||||
is named
|
||||
.Sq Pa /blah/blah/file ,
|
||||
@ -140,28 +145,41 @@ checks to make sure it is different from
|
||||
The options listed below control the formatting style imposed by
|
||||
.Nm "" .
|
||||
.Bl -tag -width Op
|
||||
.It Fl bacc , nbacc
|
||||
If
|
||||
.Fl bacc
|
||||
is specified, a blank line is forced around every conditional
|
||||
compilation block.
|
||||
For example, in from of every #ifdef and after every #endif.
|
||||
Other blank lines surrounding such blocks will be swallowed.
|
||||
Default:
|
||||
.Fl nbacc .
|
||||
.It Fl bad , nbad
|
||||
If
|
||||
.Fl bad
|
||||
is specified, a blank line is forced after every block of
|
||||
declarations. Default:
|
||||
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 .
|
||||
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 .
|
||||
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
|
||||
turns off this option.
|
||||
Default:
|
||||
.Fl \&bc .
|
||||
.It Fl \&br , \&bl
|
||||
Specifying
|
||||
@ -185,14 +203,24 @@ if (...) {
|
||||
}
|
||||
.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
|
||||
.It Fl bs , Fl nbs
|
||||
If
|
||||
.Fl bs
|
||||
is specified, a blank is forced after
|
||||
.Ic sizeof .
|
||||
Default:
|
||||
.Fl nbs .
|
||||
.It Fl c Ns Ar n
|
||||
The column in which comments on code start.
|
||||
Default:
|
||||
.Fl c33 .
|
||||
.It Fl cd Ns Ar 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:
|
||||
Enables (disables) the placement of comment delimiters on blank lines.
|
||||
With this option enabled, comments look like this:
|
||||
.Bd -literal -offset indent
|
||||
/*
|
||||
* this is a comment
|
||||
@ -205,84 +233,110 @@ Rather than like this:
|
||||
.Ed
|
||||
.Pp
|
||||
This only affects block comments, not comments to the right of
|
||||
code. The default is
|
||||
code.
|
||||
Default:
|
||||
.Fl cdb .
|
||||
.It Fl ce , nce
|
||||
Enables (disables) forcing `else's to cuddle up to the immediately preceding
|
||||
`}'. The default is
|
||||
`}'.
|
||||
Default:
|
||||
.Fl \&ce .
|
||||
.It Fl \&ci Ns Ar n
|
||||
.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
|
||||
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
|
||||
.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.5
|
||||
causes case labels to be indented half a tab stop.
|
||||
Default:
|
||||
.Fl cli0 .
|
||||
.It Fl d Ns Ar n
|
||||
Controls the placement of comments which are not to the
|
||||
right of code. The default
|
||||
.It Fl d Ns Ar n
|
||||
Controls the placement of comments which are not to the right of code.
|
||||
For example,
|
||||
.Fl \&d\&1
|
||||
means that such comments are placed one indentation level to the
|
||||
left of code. Specifying
|
||||
means that such comments are placed one indentation level to the left of code.
|
||||
Specifying the default
|
||||
.Fl \&d\&0
|
||||
lines up these comments with the code. See the section on comment
|
||||
lines up these comments with the code.
|
||||
See the section on comment
|
||||
indentation below.
|
||||
.It Fl \&di Ns Ar n
|
||||
.It Fl \&di Ns Ar n
|
||||
Specifies the indentation, in character positions, from a declaration keyword
|
||||
to the following identifier. The default is
|
||||
to the following identifier.
|
||||
Default:
|
||||
.Fl di16 .
|
||||
.It Fl dj , ndj
|
||||
.Fl \&dj
|
||||
left justifies declarations.
|
||||
.Fl ndj
|
||||
indents declarations the same as code. The default is
|
||||
indents declarations the same as code.
|
||||
Default:
|
||||
.Fl ndj .
|
||||
.It Fl \&ei , nei
|
||||
Enables (disables) special
|
||||
.Ic else-if
|
||||
processing. If it's enabled, an
|
||||
processing.
|
||||
If it's enabled, an
|
||||
.Ic if
|
||||
following an
|
||||
.Ic else
|
||||
will have the same indentation as the preceding
|
||||
.Ic \&if
|
||||
statement.
|
||||
Default:
|
||||
.Fl ei .
|
||||
.It Fl eei , neei
|
||||
Enables (disables) extra indentation on continuation lines of
|
||||
the expression part of
|
||||
.Ic if
|
||||
and
|
||||
.Ic while
|
||||
statements.
|
||||
These continuation lines will be indented one extra level.
|
||||
Default:
|
||||
.Fl neei .
|
||||
.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,
|
||||
hand formatted by the programmer.
|
||||
In such cases,
|
||||
.Fl nfc1
|
||||
should be
|
||||
used. The default is
|
||||
should be used.
|
||||
Default:
|
||||
.Fl fc1 .
|
||||
.It Fl i Ns Ar n
|
||||
The number of spaces for one indentation level. The default is 4.
|
||||
.It Fl i Ns Ar n
|
||||
The number of spaces for one indentation level.
|
||||
Default:
|
||||
.Fl i8 .
|
||||
.It Fl \&ip , nip
|
||||
Enables (disables) the indentation of parameter declarations from the left
|
||||
margin. The default is
|
||||
margin.
|
||||
Default:
|
||||
.Fl \&ip .
|
||||
.It Fl l Ns Ar n
|
||||
Maximum length of an output line. The default is 75.
|
||||
.It Fl l Ns Ar n
|
||||
Maximum length of an output line.
|
||||
Default:
|
||||
.Fl l78 .
|
||||
.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
|
||||
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
|
||||
@ -318,39 +372,46 @@ to be ignored.
|
||||
If true
|
||||
.Pq Fl pcs
|
||||
all procedure calls will have a space inserted between
|
||||
the name and the `('. The default is
|
||||
the name and the `('.
|
||||
Default:
|
||||
.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
|
||||
column 1 \- their types, if any, will be left on the previous lines.
|
||||
Default:
|
||||
.Fl psl .
|
||||
.It Fl \&sc , nsc
|
||||
Enables (disables) the placement of asterisks (`*'s) at the left edge of all
|
||||
comments.
|
||||
Default:
|
||||
.Fl sc .
|
||||
.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:
|
||||
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
|
||||
to take its input from stdin, and put its output to stdout.
|
||||
.It Fl T Ns Ar typename
|
||||
.It Fl T Ns Ar typename
|
||||
Adds
|
||||
.Ar typename
|
||||
to the list of type keywords. Names accumulate:
|
||||
to the list of type keywords.
|
||||
Names accumulate:
|
||||
.Fl T
|
||||
can be specified more than once. You need to specify all the typenames that
|
||||
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
|
||||
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
|
||||
@ -373,10 +434,12 @@ rather than formatting in place.
|
||||
.Fl v
|
||||
turns on `verbose' mode;
|
||||
.Fl \&nv
|
||||
turns it off. When in verbose mode,
|
||||
turns it off.
|
||||
When in verbose mode,
|
||||
.Nm
|
||||
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
|
||||
and gives some size statistics at completion.
|
||||
Default:
|
||||
.Fl \&nv .
|
||||
.El
|
||||
.Pp
|
||||
@ -385,51 +448,56 @@ You may set up your own `profile' of defaults to
|
||||
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
|
||||
whatever switches you like.
|
||||
A `.indent.pro' in the current directory takes
|
||||
precedence over the one in your login directory.
|
||||
If
|
||||
.Nm
|
||||
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.
|
||||
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
|
||||
assumes that any comment with a dash, star, or newline immediately after
|
||||
the start of comment (that is, `/*\-', `/**' or `/*' followed
|
||||
immediately by a newline character) 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
|
||||
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
|
||||
fits as many words (separated by blanks, tabs, or newlines) on a
|
||||
line as possible. Blank lines break paragraphs.
|
||||
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
|
||||
.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
|
||||
.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
|
||||
leaves preprocessor lines alone. The only
|
||||
reformatting that it will do is to straighten up trailing comments. It
|
||||
leaves embedded comments alone. Conditional compilation
|
||||
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
|
||||
@ -439,8 +507,9 @@ compensate for the syntactic peculiarities introduced.
|
||||
.Ss C syntax
|
||||
.Nm
|
||||
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:
|
||||
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user