mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-16 10:20:30 +00:00
3be5f1f5ce
track.
The $Id$ line is normally at the bottom of the main comment block in the
man page, separated from the rest of the manpage by an empty comment,
like so;
.\" $Id$
.\"
If the immediately preceding comment is a @(#) format ID marker than the
the $Id$ will line up underneath it with no intervening blank lines.
Otherwise, an additional blank line is inserted.
Approved by: bde
456 lines
12 KiB
Groff
456 lines
12 KiB
Groff
.\" 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
|
|
.\" $Id$
|
|
.\"
|
|
.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
|
|
.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
|
|
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. Default:
|
|
.Fl \&nbc .
|
|
.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 Ns Ar n
|
|
The column in which comments on code start. The default is 33.
|
|
.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:
|
|
.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 of `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. For example,
|
|
.Fl \&d\&1
|
|
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
|
|
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. The default is
|
|
.Fl ei .
|
|
.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 8.
|
|
.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 78.
|
|
.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. The default is
|
|
.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:
|
|
.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
|
|
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
|
|
can't find all
|
|
instances of
|
|
.Ic typedef .
|
|
.It Fl troff
|
|
Causes
|
|
.Nm
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|