indent.tex

GNU 系统开发优化 C 语言程序的应用程序

@kindex -cli@var{n}
@kindex --case-indentation@var{n}
The @samp{-cli} option specifies the number of spaces that case labels
should be indented to the right of the containing @samp{switch}
statement.

@kindex -ss
@kindex --space-special-semicolon
@kindex -nss
@kindex --dont-space-special-semicolon
If a semicolon is on the same line as a @code{for} or @code{while}
statement, the @samp{-ss} option will cause a space to be placed before
the semicolon.  This emphasizes the semicolon, making it clear that the
body of the @code{for} or @code{while} statement is an empty statement.
@code{-nss} disables this feature.

@kindex -pcs
@kindex --space-after-procedure-calls
@kindex -npcs
@kindex --no-space-after-function-call-names
The @samp{-pcs} option causes a space to be placed between the name of
the procedure being called and the @samp{(} (for example, @w{@code{puts
("Hi");}}.  The @samp{-npcs} option would give @code{puts("Hi");}).
@refill

@kindex -cs
@kindex --space-after-cast
@kindex -ncs
@kindex --no-space-after-casts
If the @samp{-cs} option is specified, @code{indent} puts a space after
a cast operator.

@kindex -bs
@kindex --blank-after-sizeof
The @samp{-bs} option ensures that there is a space between the
keyword @code{sizeof} and its argument.  In some versions, this is
known as the @samp{Bill_Shannon} option.

@node Declarations, Indentation, Statements, Indent Program
@comment  node-name,  next,  previous,  up
@section Declarations

@kindex -di@var{n}
@kindex --declaration-indentation@var{n}
By default @code{indent} will line up identifiers, in the column
specified by the @samp{-di} option.  For example, @samp{-di16} makes
things look like:

@example
@group
int             foo;
char           *bar;
@end group
@end example

Using a small value (such as one or two) for the @samp{-di} option can
be used to cause the indentifiers to be placed in the first available
position, for example

@example
@group
int foo;
char *bar;
@end group
@end example

The value given to the @samp{-di} option will still affect variables
which are put on separate lines from their types, for example
@samp{-di2} will lead to

@example
@group
int
  foo;
@end group
@end example

@kindex -bc
@kindex --blank-lines-after-commas
@kindex -nbc
@kindex --no-blank-lines-after-commas
If the @samp{-bc} option is specified, a newline is forced after each
comma in a declaration.  For example,

@example
@group
int a,
  b,
  c;
@end group
@end example

@noindent
With the @samp{-nbc} option this would look like

@example
int a, b, c;
@end example

@kindex -psl
@kindex --procnames-start-lines
@kindex -npsl
@kindex --dont-break-procedure-type
@cindex @code{etags} requires @samp{-psl}
The @samp{-psl} option causes the type of a procedure being defined to
be placed on the line before the name of the procedure.  This style is
required for the @code{etags} program to work correctly, as well as some
of the @code{c-mode} functions of Emacs.

@kindex -T
@cindex Typenames
If you are not using the @samp{-di1} option to place variables being
declared immediately after their type, you need to use the @samp{-T}
option to tell @code{indent} the name of all the typenames in your
program that are defined by @code{typedef}.  @samp{-T} can be specified
more than once, and all names specified are used.  For example, if your
program contains

@example
@group
typedef unsigned long CODE_ADDR;
typedef enum @{red, blue, green@} COLOR;
@end group
@end example

@noindent
you would use the options @samp{-T CODE_ADDR -T COLOR}.

@node Indentation, Disabling Formatting, Declarations, Indent Program
@comment  node-name,  next,  previous,  up
@section Indentation

@kindex -i@var{n}
@kindex --indent-level@var{n}
@kindex -ci@var{n}
@kindex --continuation-indentation@var{n}
@kindex -lp
@kindex --continue-at-parentheses
@kindex -nlp
@kindex --dont-line-up-parentheses
One issue in the formatting of code is how far each line should be
indented from the left margin.  When the beginning of a statement such
as @code{if} or @code{for} is encountered, the indentation level is
increased by the value specified by the @samp{-i} option.  For example,
use @samp{-i8} to specify an eight character indentation for each
level.  When a statement is broken across two lines, the second line is
indented by a number of additional spaces specified by the @samp{-ci}
option.  @samp{-ci} defaults to 0.  However, if the @samp{-lp} option is
specified, and a line has a left parenthesis which is not closed on that
line, then continuation lines will be lined up to start at the character
position just after the left parenthesis.  This processing also applies
to @samp{[} and applies to @samp{@{} when it occurs in initialization
lists.  For example, a piece of continued code might look like this with
@samp{-nlp -ci3} in effect:

@example
@group
  p1 = first_procedure (second_procedure (p2, p3),
     third_procedure (p4, p5));
@end group
@end example

@noindent
With @samp{-lp} in effect the code looks somewhat clearer:

@example
@group
  p1 = first_procedure (second_procedure (p2, p3),
                        third_procedure (p4, p5));
@end group
@end example

@kindex -ts@var{n}
@kindex --tab-size@var{n}
@code{indent} assumes that tabs are placed at regular intervals of both
input and output character streams.  These intervals are by default 8
columns wide, but (as of version 1.2) may be changed by the @samp{-ts}
option.  Tabs are treated as the equivalent number of spaces.

@kindex -ip@var{n}
@kindex --parameter-indentation@var{n}
@kindex -nip
@kindex --no-parameter-indentation
The indentation of type declarations in old-style function definitions
is controlled by the @samp{-ip} parameter.  This is a numeric parameter
specifying how many spaces to indent type declarations.  For example,
the default @w{@samp{-ip5}} makes definitions look like this:

@example
@group
char *
create_world (x, y, scale)
     int x;
     int y;
     float scale;
@{
  . . .
@}
@end group
@end example

For compatibility with other versions of indent, the option @samp{-nip}
is provided, which is equivalent to @samp{-ip0}.

@kindex -lps
@kindex --leave-preprocessor-space
@kindex -nlps
@kindex --remove-preprocessor-space
ASCII C allows white space to be placed on preprocessor command lines
between the character @samp{#} and the command name.  By default,
@code{indent} removes this space, but specifying the @samp{-lps} option
directs @code{indent} to leave this space unmodified.

@node Disabling Formatting, Miscellaneous options, Indentation, Indent Program
@comment  node-name,  next,  previous,  up
@section Disabling Formatting

Formatting of C code may be disabled for portions of a program by
embedding special @dfn{control comments} in the program.  To turn off
formatting for a section of a program, place the disabling control
comment @code{/* *INDENT-OFF* */} on a line by itself just before that
section.  Program text scanned after this control comment is output
precisely as input with no modifications until the corresponding
enabling comment is scanned on a line by itself.  The disabling control
comment is @code{/* *INDENT-ON* */}, and any text following the comment
on the line is also output unformatted.  Formatting begins again with
the input line following the enabling control comment.

More precisely, @code{indent} does not attempt to verify the closing
delimiter (@code{*/}) for these C comments, and any whitespace on the
line is totally transparent.

These control comments also function in their C++ formats, namely
@code{// *INDENT-OFF*} and @code{// *INDENT-ON*}.

It should be noted that the internal state of @code{indent} remains
unchanged over the course of the unformatted section.  Thus, for
example, turning off formatting in the middle of a function and
continuing it after the end of the function may lead to bizarre
results.  It is therefore wise to be somewhat modular in selecting code
to be left unformatted.

As a historical note, some earlier versions of @code{indent} produced
error messages beginning with @code{*INDENT**}.  These versions of
@code{indent} were written to ignore any input text lines which began
with such error messages.  I have removed this incestuous feature from
@code{GNU indent}.

@node Miscellaneous options, Bugs, Disabling Formatting, Indent Program
@comment  node-name,  next,  previous,  up
@section Miscellaneous options

@kindex -version
To find out what version of @code{indent} you have, use the command
@code{indent -version}.  This will report the version number of
@code{indent}, without doing any of the normal processing.

@ignore
This is intentionally undocumented because
1.  Although GNU now has groff, it would be better to use TeX.

2.  The output of indent -troff looks awful, so we have heard.  Perhaps
    it would be reasonable to use this as a starting point to printing a
    program.

If you are printing your program, you may wish to use the @samp{-troff}
option to produce output suitable for processing by the @code{troff}
program.  When the @samp{-troff} option is specified, if the output file
is not specified, the default is standard output, rather than formatting
in place.
@end ignore

@kindex -v
@kindex --verbose
@kindex -nv
@kindex --no-verbosity
@comment Would --terse be better?  I think not, but perhaps accepting
@comment --no-verbose would avoid error messages.
The @samp{-v} option can be used to turn on verbose mode.  When in
verbose mode, @code{indent} reports when it splits one line of input
into two more more lines of output, and gives some size statistics at
completion. 

@node Bugs, Copyright, Miscellaneous options, Indent Program
@comment  node-name,  next,  previous,  up
@section Bugs

The "-troff" option is strongly deprecated, and is not supported.  A
good thing for someone to do is to rewrite `indent' to generate TeX
source as a hardcopy output option, amoung other things.

@node Copyright,  , Bugs, Indent Program
@comment  node-name,  next,  previous,  up
@section Copyright

The following copyright notice applies to the @code{indent} program.
The copyright and copying permissions for this manual appear near the
beginning of this document.

@display
Copyright (c) 1989, 1992 Free Software Foundation
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.

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.
@end display

@node Option Summary, Index, Indent Program, Top
@appendix Option Summary

Here is a list of all the options for @code{indent}, alphabetized by
short option.  It is followed by a cross key alphabetized by long option.

@c The cross references are all on lines by themselves because this
@c looks better in both printed output and Info.  4 Feb 1992  --rjc
@table @samp
@item -bad
@itemx --blank-lines-after-declarations
Force blank lines after the declarations.@*
@xref{Blank lines}.

@item -bap
@itemx --blank-lines-after-procedures
Force blank lines after procedure bodies.@*
@xref{Blank lines}.

@item -bbb
@itemx --blank-lines-after-block-comments
Force blank lines after block comments.@*
@xref{Blank lines}.

@item -bc
@itemx --blank-lines-after-commas
Force newline after comma in declaration.@*
@xref{Declarations}.

@item -bl
@itemx --braces-after-if-line
Put braces on line after @code{if}, etc.@*
@xref{Statements}.

@item -bli@var{n}
@item --brace-indent@var{n}
Indent braces @var{n} spaces.@*
@xref{Statements}.

@item -br
@itemx --braces-on-if-line
Put braces on line with @code{if}, etc. and structure declarations@*
@xref{Statements}.

@item -c@var{n}
@itemx --comment-indentation@var{n}
Put comments to the right of code in column @var{n}.@*
@xref{Comments}.

@item -cd@var{n}
@itemx --declaration-comment-column@var{n}
Put comments to the right of the declarations in column @var{n}.@*
@xref{Comments}.

@item -cdb
@itemx --comment-delimiters-on-blank-lines
Put comment delimiters on blank lines.@*
@xref{Comments}.

@item -ce