indent.texinfo

indent为linux下代码自动格式化工具

@kindex -l@var{n}
@kindex --line-length@var{n}
With the option @option{-l@var{n}}, or @option{--line-length@var{n}}, it is
possible to specify the maximum length of a line of C code, not including
possible comments that follow it.

When lines become longer then the specified line length, GNU @command{indent}
tries to break the line at a logical place.  This is new as of version 2.1
however and not very intelligent or flexible yet.

@kindex -bbo
@kindex --break-before-boolean-operator
@kindex -nbbo
@kindex --break-after-boolean-operator
@kindex -hnl
@kindex --honour-newlines
@kindex -nhnl
@kindex --ignore-newlines
Currently there are two options that allows one to interfere with the
algorithm that determines where to break a line.

The @option{-bbo} option causes GNU @command{indent} to prefer to break
long lines before the boolean operators @code{&&} and @code{||}.  The
@option{-nbbo} option causes GNU @command{indent} not have that
preference.  For example, the default option @option{-bbo} (together
with @option{--line-length60} and @option{--ignore-newlines}) makes code
look like this:

@example
@group
  if (mask
      && ((mask[0] == '\0')
          || (mask[1] == '\0'
              && ((mask[0] == '0') || (mask[0] == '*')))))
@end group
@end example

Using the option @option{-nbbo} will make it look like this:

@example
@group
  if (mask &&
      ((mask[0] == '\0') ||
       (mask[1] == '\0' &&
        ((mask[0] == '0') || (mask[0] == '*')))))
@end group
@end example

The default @option{-hnl}, however, honours newlines in the input file by
giving them the highest possible priority to break lines at.  For example,
when the input file looks like this:

@example
@group
  if (mask
      && ((mask[0] == '\0')
      || (mask[1] == '\0' && ((mask[0] == '0') || (mask[0] == '*')))))
@end group
@end example

@noindent
then using the option @option{-hnl}, or @option{--honour-newlines},
together with the previously mentioned @option{-nbbo} and
@option{--line-length60}, will cause the output not to be what is given
in the last example but instead will prefer to break at the positions
where the code was broken in the input file:

@example
@group
  if (mask
      && ((mask[0] == '\0')
          || (mask[1] == '\0' &&
              ((mask[0] == '0') || (mask[0] == '*')))))
@end group
@end example

The idea behind this option is that lines which are too long, but are already
broken up, will not be touched by GNU @command{indent}.  Really messy code
should be run through @command{indent} at least once using the
@option{--ignore-newlines} option though.

@node Disabling Formatting, Miscellaneous options, Breaking long lines, 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, @command{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 @command{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 @command{indent} produced
error messages beginning with @code{*INDENT**}.  These versions of
@command{indent} were written to ignore any input text lines which began
with such error messages.  I have removed this incestuous feature from
GNU @command{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 @command{indent} you have, use the command
@code{indent -version}.  This will report the version number of
@command{indent}, without doing any of the normal processing.

@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 @option{-v} option can be used to turn on verbose mode.  When in
verbose mode, @command{indent} reports when it splits one line of input
into two more more lines of output, and gives some size statistics at
completion. 

@kindex -pmt
@kindex --preserve-mtime
@kindex -npmt
The @option{-pmt} option causes @command{indent} to preserve the access
and modification times on the output files.  Using this option
has the advantage that running indent on all source and header
files in a project won't cause @code{make} to rebuild all targets.
This option is only available on Operating Systems that have the
POSIX @code{utime(2)} function.

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

Please report any bugs to @email{bug-indent@@gnu.org}.

When @command{indent} is run twice on a file, with the same profile,
it should @emph{never} change that file the second time.  With the
current design of @command{indent}, this can not be guaranteed,
and it has not been extensively tested.

@command{indent} does not understand C.  In some cases this leads to
the inability to join lines.  The result is that running a file
through @command{indent} is @emph{irreversible}, even if the used input
file was the result of running @command{indent} with a given profile
(@file{.indent.pro}).

While an attempt was made to get @command{indent} working for C++, it
will not do a good job on any C++ source except the very simplest.

@command{indent} does not look at the given @option{--line-length} option
when writing comments to the output file.  This results often in comments
being put far to the right.  In order to prohibit @command{indent} from
joining a broken line that has a comment at the end, make sure that the
comments start on the first line of the break.

@command{indent} does not count lines and comments (see the @option{-v}
option) when @command{indent} is turned off with 
@code{/* *INDENT-OFF* */}.

Comments of the form @code{/*UPPERCASE*/} are not treated as comment but as an
identifier, causing them to be joined with the next line. This renders
comments of this type useless, unless they are embedded in the code to
begin with.

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

The following copyright notice applies to the @command{indent} program.
The copyright and copying permissions for this manual appear near the
beginning of @file{indent.texinfo} and @file{indent.info}, and near the
end of @file{indent.1}.

@display
Copyright @copyright{} 2001 David Ingamells.
Copyright @copyright{} 1999 Carlo Wood.
Copyright @copyright{} 1995, 1996 Joseph Arceneaux.
Copyright @copyright{} 1989, 1992, 1993, 1994, 1995, 1996 Free Software Foundation
Copyright @copyright{} 1985 Sun Microsystems, Inc.
Copyright @copyright{} 1980 The Regents of the University of California.
Copyright @copyright{} 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
@c !END THEREST

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

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

@c !BEGIN OPTIONS
@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-before-block-comments
Force blank lines before block comments.@*
@xref{Blank lines}.

@item -bbo
@itemx --break-before-boolean-operator
Prefer to break long lines before boolean operators.@*
@xref{Breaking long 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}
@itemx --brace-indent@var{n}
Indent braces @var{n} spaces.@*
@xref{Statements}.

@item -bls
@itemx --braces-after-struct-decl-line
Put braces on the line after @code{struct} declaration lines.@*
@xref{Declarations}.

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

@item -brs
@itemx --braces-on-struct-decl-line
Put braces on @code{struct} declaration line.@*
@xref{Declarations}.

@item -bs
@itemx --Bill-Shannon
@itemx --blank-before-sizeof
Put a space between @code{sizeof} and its argument.@*
@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 -cbi@var{n}
@itemx --case-brace-indentation@var{n}
Indent braces after a case label N spaces.@*
@xref{Statements}.

@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 -cdw
@itemx --cuddle-do-while
Cuddle while of @code{do @{@} while;} and preceeding @samp{@}}.@*
@xref{Comments}.

@item -ce
@itemx --cuddle-else
Cuddle else and preceeding @samp{@}}.@*
@xref{Comments}.

@item -ci@var{n}
@itemx --continuation-indentation@var{n}
Continuation indent of @var{n} spaces.@*
@xref{Statements}.

@item -cli@var{n}
@itemx --case-indentation@var{n}
Case label indent of @var{n} spaces.@*
@xref{Statements}.

@item -cp@var{n}
@itemx --else-endif-column@var{n}
Put comments to the right of @code{#else} and 
@code{#endif} statements in column @var{n}.@*
@xref{Comments}.

@item -cs
@itemx --space-after-cast
Put a space after a cast operator.@*
@xref{Statements}.

@item -d@var{n}
@itemx --line-comments-indentation@var{n}
Set indentation of comments not to the right 
of code to @var{n} spaces.@*
@xref{Comments}.

@item -bfda
@itemx --break-function-decl-args
Break the line before all arguments in a declaration.@*
@xref{Declarations}.

@item -bfde
@itemx --break-function-decl-args
Break the line after the last argument in a declaration.@*
@xref{Declarations}.

@item -di@var{n}
@itemx --declaration-indentation@var{n}
Put variables in column @var{n}.@*
@xref{Declarations}.

@item -fc1
@itemx --format-first-column-comments
Format comments in the first column.@*
@xref{Comments}.

@item -fca
@itemx --format-all-comments
Do not disable all formatting of comments.@*
@xref{Comments}.

@item -gnu
@itemx --gnu-style
Use GNU coding style.  This is the default.@*
@xref{Common styles}.

@item -hnl
@itemx --honour-newlines
Prefer to break long lines at the position of newlines in the input.@*
@xref{Breaking long lines}.

@item -i@var{n}
@itemx --indent-level@var{n}
Set indentation level to @var{n} spaces.@*
@xref{Indentation}.

@item -ip@var{n}
@itemx --parameter-indentation@var{n}
Indent parameter types in old-style function 
definitions by @var{n} spaces.@*
@xref{Indentation}.

@item -kr
@itemx --k-and-r-style
Use Kernighan & Ritchie coding style.@*
@xref{Common styles}.

@item -l@var{n}
@itemx --line-length@var{n}
Set maximum line length for non-comment lines to @var{n}.@*
@xref{Breaking long lines}.

@item -lc@var{n}
@itemx --comment-line-length@var{n}
Set maximum line length for comment formatting to @var{n}.@*
@xref{Comments}.

@item -lp
@itemx --continue-at-parentheses
Line up continued lines at parentheses.@*
@xref{Indentation}.

@item -lps
@itemx --leave-preprocessor-space
Leave space between @samp{#} and preprocessor directive.@*
@xref{Indentation}.

@item -nbad
@itemx --no-blank-lines-after-declarations
Do not force blank lines after declarations.@*
@xref{Blank lines}.

@item -nbap
@itemx --no-blank-lines-after-procedures
Do not force blank lines after procedure bodies.@*