indent.tex

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

A block comment is one which starts in column one when formatting of
such comments is disabled, or one with @code{-} or @code{*} immediately
following the @code{/*}.  The @samp{-nbbb} option does not force such
blank lines.

@kindex -sob
@kindex --swallow-optional-blank-lines
@kindex -nsob
@kindex --leave-optional-blank-lines
The @samp{-sob} option causes @code{indent} to swallow optional blank
lines (that is, any optional blank lines present in the input will be
removed from the output).  If the @samp{-nsob} is specified, any blank
lines present in the input file will be copied to the output file.

@menu
* -bad::                        More on the @samp{-bad} option.
* -bap::                        More on the @samp{-bap} option.
@end menu

@ifinfo
@node -bad, -bap,  , Blank lines
@comment  node-name,  next,  previous,  up
@subsection --blank-lines-after-declarations

The @samp{-bad} option forces a blank line after every block of
declarations.  The @samp{-nbad} option does not add any such blank
lines.
@end ifinfo

For example, given the input
@example
@group
char *foo;
char *bar;
/* This separates blocks of declarations.  */
int baz;
@end group
@end example

@kindex -bad
@kindex --blank-lines-after-declarations
@kindex -nbad
@kindex --no-blank-lines-after-declarations
@noindent
@code{indent -bad} produces

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

/* This separates blocks of declarations.  */
int baz;
@end group
@end example

@noindent
and @code{indent -nbad} produces

@example
@group
char *foo;
char *bar;
/* This separates blocks of declarations.  */
int baz;
@end group
@end example

@ifinfo
@node -bap,  , -bad, Blank lines
@comment  node-name,  next,  previous,  up
@subsection --blank-lines-after-procedures
@end ifinfo

@kindex -bap
@kindex --blank-lines-after-procedures
@kindex -nbap
@kindex --no-blank-lines-after-procedures
The @samp{-bap} option forces a blank line after every procedure body.

For example, given the input

@example
@group
int
foo ()
@{
  puts("Hi");
@}
/* The procedure bar is even less interesting.  */
char *
bar ()
@{
  puts("Hello");
@}
@end group
@end example

@noindent
@code{indent -bap} produces

@example
@group
int
foo ()
@{
  puts ("Hi");
@}

/* The procedure bar is even less interesting.  */
char *
bar ()
@{
  puts ("Hello");
@}
@end group
@end example

@noindent
and @code{indent -nbap} produces

@example
@group
int
foo ()
@{
  puts ("Hi");
@}
/* The procedure bar is even less interesting.  */
char *
bar ()
@{
  puts ("Hello");
@}
@end group
@end example

@noindent
No blank line will be added after the procedure @code{foo}.

@node Comments, Statements, Blank lines, Indent Program
@comment  node-name,  next,  previous,  up
@section Comments
@cindex Comments

@code{indent} formats both C and C++ comments. C comments are begun with
@samp{/*} and terminated with @samp{*/} and may contain newline
characters.  C++ comments begin with the delimiter @samp{//} and end at
the newline.

@code{indent} handles comments differently depending upon their
context.  @code{indent} attempts to distinguish amoung comments which
follow statements, comments which follow declarations, comments
following preprocessor directives, and comments which are not preceded
by code of any sort, i.e., they begin the text of the line (although not
neccessarily in column 1).

@code{indent} further attempts to leave @dfn{boxed comments}
unmodified.  The general idea of such a comment is that it is enclosed
in a rectangle or ''box'' of stars or dashes to visually set it apart.
More precisely, boxed comments are defined as those in which the initial
@samp{/*} is followed immediately by the character @samp{*}, @samp{=},
@samp{_}, or @samp{-}, or those in which the beginning comment delimiter
(@samp{/*}) is on a line by itself, and the following line begins with a
@samp{*} in the same column as the star of the opening delimiter.

Examples of boxed comments are:

@example
@group
/**********************
 * Comment in a box!! *
 **********************/

       /*
        * A different kind of scent,
        * for a different kind of comment.
        */
@end group
@end example

@code{indent} attempts to leave boxed comments exactly as they are found
in the source file.  Thus the indentation of the comment is unchanged,
and its length is not checked in any way.  The only alteration made is
that an embedded tab character may be converted into the appropriate
number of spaces.

@kindex -fca
@kindex --format-all-comments
@kindex -nfca
@kindex --dont-format-comments
@kindex -fc1
@kindex --format-first-column-comments
@kindex -nfc1
@kindex --dont-format-first-column-comments
@kindex -l@var{n}
@kindex --line-length@var{n}
Comments which are not boxed may be formatted, which means that the
line is broken to fit within a right margin and left-filled with
whitespace.  Single newlines are equivalent to a space, but blank
lines (two or more newlines in a row) are taken to mean a paragraph
break.  Formatting of comments which begin after the first column is
enabled with the @samp{-fca} option.  To format those beginning in
column one, specify @samp{-fc1}.  The right margin defaults to 78, but
may be changed with the @samp{-l} option.  Such formatting is disabled
by default.

If the margin specified does not allow the comment to be printed, the
margin will be automatically extended for the duration of that
comment.  The margin is not respected if the comment is not being
formatted.

@kindex -d@var{n}
@kindex --line-comments-indentation@var{n}
If the comment begins a line (i.e., there is no program text to its
left), it will be indented to the column it was found in unless the
comment is within a block of code.  In that case, such a comment will
be aligned with the indented code of that block.  This alignment may
be affected by the @samp{-d} option, which specifies an amount by
which such comments are moved to the @emph{left}, or unindented.  For
example, @samp{-d2} places comments two spaces to the left of code.
By default, comments are aligned with code.

@kindex -c@var{n}
@kindex --comment-indentation@var{n}
@kindex -cd@var{n}
@kindex --declaration-comment-column@var{n}
@kindex -cp@var{n}
@kindex --else-endif-column@var{n}
Comments to the right of code will appear by default in column 33.
This may be changed with one of three options.  @samp{-c} will specify
the column for comments following code, @samp{-cd} specifies the
column for comments following declarations, and @samp{-cp} specifies
the column for comments following preprocessor directives @code{#else}
and @code{#endif}.

If the code to the left of the comment exceeds the beginning column,
the comment column will be extended to the next tabstop column past
the end of the code, or in the case of preprocessor directives, to one
space past the end of the directive.  This extension lasts only for
the output of that particular comment.

@kindex -cdb
@kindex --comment-delimiters-on-blank-lines
@kindex -ncdb
@kindex --no-comment-delimiters-on-blank-lines
The @samp{-cdb} option places the comment delimiters on blank lines.
Thus, a single line comment like @code{/* Claustrophobia */} can be
transformed into:

@example
@group
/*
   Claustrophobia
 */
@end group
@end example

@kindex -sc
@kindex --star-left-side-of-comments
@kindex -nsc
@kindex --dont-star-comments
Stars can be placed at the beginning of multi-line comments with the
@samp{-sc} option.  Thus, the single-line comment above can be
transformed (with @samp{-cdb -sc}) into:

@example
@group
/*
 * Claustrophobia
 */
@end group
@end example

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

@kindex -br
@kindex --braces-on-if-line
@kindex -bl
@kindex --braces-after-if-line
The @samp{-br} or @samp{-bl} option specifies how to format braces.

The @samp{-br} option formats statement braces like this:

@example
@group
if (x > 0) @{
  x--;
@}
@end group
@end example

@noindent
The @samp{-bl} option formats them like this:

@example
@group
if (x > 0)
  @{
    x--;
  @}
@end group
@end example

These options also affect structure and enumeration declarations.  The
@samp{-br} option produces structure declarations like the following:

@example
@group
struct Sname @{
    int i;
    char chp;
@} Vname;
@end group
@end example

The default behaviour, also obtained by specifying @samp{-bl}, would
yield the following format for the same declaration:

@example
@group
struct Sname
  @{
     int i;
     char chp;
  @}
Vname;
@end group
@end example

@kindex -bli@var{n}
@kindex --brace-indent@var{n}
If you use the @samp{-bl} option, you may also want to specify the
@samp{-bli} option.  This option specifies the number of spaces by
which braces are indented.  @samp{-bli2}, the default, gives the
result shown above.  @samp{-bli0} results in the following:

@example
@group
if (x > 0)
@{
  x--;
@}
@end group
@end example

@kindex -ce
@kindex --cuddle-else
@kindex -dce
@kindex --dont-cuddle-else
If you are using the @samp{-br} option, you probably want to also use
the @samp{-ce} option.  This causes the @code{else} in an if-then-else
construct to cuddle up to the immediately preceding @samp{@}}.  For
example, with @samp{-br -ce} you get the following:

@example
@group
if (x > 0) @{
  x--;
@} else @{
  fprintf (stderr, "...something wrong?\n");
@}
@end group
@end example

@noindent
With @samp{-br -nce} that code would appear as

@smallexample
@group
if (x > 0) @{
  x--;
@}
else @{
  fprintf (stderr, "...something wrong?\n");
@}
@end group
@end smallexample