indent.1

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

\`-nlp -ci3\' in effect:

.in +5
.nf
.na
  p1 = first_procedure (second_procedure (p2, p3),
     third_procedure (p4, p5));
.in -5
.ad
.fi

With \`-lp\' in effect the code looks somewhat clearer:

.in +5
.nf
.na
  p1 = first_procedure (second_procedure (p2, p3),
                        third_procedure (p4, p5));
.in -5
.ad
.fi

When a statement is broken in between two or more paren pairs (...),
each extra pair causes the indentation level extra indentation:

.in +5
.nf
.na
if ((((i < 2 &&
        k > 0) || p == 0) &&
    q == 1) ||
  n = 0)
.in -5
.ad
.fi

The option \`-ip\fIN\fR\' can be used to set the extra offset per paren.
For instance, \`-ip0\' would format the above as:

.in +5
.nf
.na
if ((((i < 2 &&
  k > 0) || p == 0) &&
  q == 1) ||
  n = 0)
.in -5
.ad
.fi

.B indent\fR 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 \`-ts\'
option.  Tabs are treated as the equivalent number of spaces.

The indentation of type declarations in old-style function definitions
is controlled by the \`-ip\' parameter.  This is a numeric parameter
specifying how many spaces to indent type declarations.  For example,
the default \`-ip5\' makes definitions look like this:

.in +5
.nf
.na
char *
create_world (x, y, scale)
     int x;
     int y;
     float scale;
{
  . . .
}
.in -5
.ad
.fi

For compatibility with other versions of indent, the option \`-nip\'
is provided, which is equivalent to \`-ip0\'.

ANSI C allows white space to be placed on preprocessor command lines
between the character \`#\' and the command name.  By default,
.B indent\fR removes this space, but specifying the \`-lps\' option
directs \fBindent\fR to leave this space unmodified. The option \`-ppi\' 
overrides  \`-nlps\' and  \`-lps\'.

This option can be used to request that preprocessor conditional statements can
be indented by to given number of spaces, for example with the option \`-ppi 3\'

.in +5
.nf
.na
#if X
#if Y
#define Z 1
#else
#define Z 0
#endif
#endif
.in -5
.ad
.fi
becomes
.in +5
.nf
.na
#if X
#   if Y
#      define Z 1
#   else
#      define Z 0
#   endif
#endif
.in -5
.ad
.fi

.SH "BREAKING LONG LINES"

With the option \`-l\fIn\fR\', or \`--line-length\fIn\fR\', 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 \fBindent\fR
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.

Currently there are two options that allows one to interfere with the
algorithm that determines where to break a line.

The \`-bbo\' option causes GNU \fBindent\fR to prefer to break
long lines before the boolean operators \fB&&\fR and \fB||\fR.  The
\`-nbbo\' option causes GNU \fBindent\fR not have that
preference.  For example, the default option \`-bbo\' (together
with \`--line-length60\' and \`--ignore-newlines\') makes code
look like this:

.in +5
.nf
.na
  if (mask
      && ((mask[0] == \'\\0\')
          || (mask[1] == \'\\0\'
              && ((mask[0] == \'0\') || (mask[0] == \'*\')))))
.in -5
.ad
.fi

Using the option \`-nbbo\' will make it look like this:

.in +5
.nf
.na
  if (mask &&
      ((mask[0] == \'\\0\') ||
       (mask[1] == \'\\0\' &&
        ((mask[0] == \'0\') || (mask[0] == \'*\')))))
.in -5
.ad
.fi

The default \`-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:

.in +5
.nf
.na
  if (mask
      && ((mask[0] == \'\\0\')
      || (mask[1] == \'\\0\' && ((mask[0] == \'0\') || (mask[0] == \'*\')))))
.in -5
.ad
.fi

then using the option \`-hnl\', or \`--honour-newlines\',
together with the previously mentioned \`-nbbo\' and
\`--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:

.in +5
.nf
.na
  if (mask
      && ((mask[0] == \'\\0\')
          || (mask[1] == \'\\0\' &&
              ((mask[0] == \'0\') || (mask[0] == \'*\')))))
.in -5
.ad
.fi

The idea behind this option is that lines which are too long, but are already
broken up, will not be touched by GNU \fBindent\fR.  Really messy code
should be run through \fBindent\fR at least once using the
\`--ignore-newlines\' option though.

.SH "DISABLING FORMATTING"

Formatting of C code may be disabled for portions of a program by
embedding special \fIcontrol comments\fR in the program.  To turn off
formatting for a section of a program, place the disabling control
comment \fB/* *INDENT-OFF* */\fR 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 \fB/* *INDENT-ON* */\fR, 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, \fBindent\fR does not attempt to verify the closing
delimiter (\fB*/\fR) for these C comments, and any whitespace on the
line is totally transparent.

These control comments also function in their C++ formats, namely
.B // *INDENT-OFF*\fR and \fB// *INDENT-ON*\fR.

It should be noted that the internal state of \fBindent\fR 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 \fBindent\fR produced
error messages beginning with \fB*INDENT**\fR.  These versions of
.B indent\fR were written to ignore any input text lines which began
with such error messages.  I have removed this incestuous feature from
GNU \fBindent\fR.

.SH "MISCELLANEOUS OPTIONS"

To find out what version of \fBindent\fR you have, use the command
.B indent -version\fR.  This will report the version number of
.B indent\fR, without doing any of the normal processing.

The \`-v\' option can be used to turn on verbose mode.  When in
verbose mode, \fBindent\fR reports when it splits one line of input
into two more more lines of output, and gives some size statistics at
completion. 

The \`-pmt\' option causes \fBindent\fR 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 \fBmake\fR to rebuild all targets.
This option is only available on Operating Systems that have the
POSIX \fButime(2)\fR function.

.SH "BUGS"

Please report any bugs to [e-mail].

When \fBindent\fR is run twice on a file, with the same profile,
it should \fInever\fR change that file the second time.  With the
current design of \fBindent\fR, this can not be guaranteed,
and it has not been extensively tested.

.B indent\fR does not understand C.  In some cases this leads to
the inability to join lines.  The result is that running a file
through \fBindent\fR is \fIirreversible\fR, even if the used input
file was the result of running \fBindent\fR with a given profile
(\`.indent.pro\').

While an attempt was made to get \fBindent\fR working for C++, it
will not do a good job on any C++ source except the very simplest.

.B indent\fR does not look at the given \`--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 \fBindent\fR 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.

.B indent\fR does not count lines and comments (see the \`-v\'
option) when \fBindent\fR is turned off with 
.B /* *INDENT-OFF* */\fR.

Comments of the form \fB/*UPPERCASE*/\fR 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.

.SH "COPYRIGHT"

The following copyright notice applies to the \fBindent\fR program.
The copyright and copying permissions for this manual appear near the
beginning of \`indent.texinfo\' and \`indent.info\', and near the
end of \`indent.1\'.

.nf
.na
Copyright (c) 2001 David Ingamells.
Copyright (c) 1999 Carlo Wood.
Copyright (c) 1995, 1996 Joseph Arceneaux.
Copyright (c) 1989, 1992, 1993, 1994, 1995, 1996 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.
.ad
.fi

.SH "Options\' Cross Key"

Here is a list of options alphabetized by long option, to help you find
the corresponding short option.


.in +5
.nf
.na
--blank-lines-after-commas                      -bc             
--blank-lines-after-declarations                -bad            
--blank-lines-after-procedures                  -bap            
--blank-lines-before-block-comments             -bbb            
--braces-after-if-line                          -bl             
--brace-indent                                  -bli
--braces-after-struct-decl-line                 -bls
--braces-on-if-line                             -br             
--braces-on-struct-decl-line                    -brs
--break-after-boolean-operator                  -nbbo
--break-before-boolean-operator                 -bbo
--break-function-decl-args                      -bfda
--break-function-decl-args-end                  -bfde
--case-indentation                              -cli\fIn\fR     
--case-brace-indentation                        -cbi\fIn\fR
--comment-delimiters-on-blank-lines             -cdb            
--comment-indentation                           -c\fIn\fR       
--continuation-indentation                      -ci\fIn\fR      
--continue-at-parentheses                       -lp             
--cuddle-do-while                               -cdw
--cuddle-else                                   -ce             
--declaration-comment-column                    -cd\fIn\fR      
--declaration-indentation                       -di\fIn\fR      
--dont-break-function-decl-args                 -nbfda
--dont-break-function-decl-args-end             -nbfde
--dont-break-procedure-type                     -npsl           
--dont-cuddle-do-while                          -ncdw
--dont-cuddle-else                              -nce            
--dont-format-comments                          -nfca           
--dont-format-first-column-comments             -nfc1           
--dont-line-up-parentheses                      -nlp            
--dont-space-special-semicolon                  -nss
--dont-star-comments                            -nsc            
--else-endif-column                             -cp\fIn\fR
--format-all-comments                           -fca            
--format-first-column-comments                  -fc1            
--gnu-style                                     -gnu            
--honour-newlines                               -hnl
--ignore-newlines                               -nhnl
--ignore-profile                                -npro           
--indent-level                                  -i\fIn\fR       
--k-and-r-style                                 -kr             
--leave-optional-blank-lines                    -nsob           
--leave-preprocessor-space                      -lps
--line-comments-indentation                     -d\fIn\fR       
--line-length                                   -l\fIn\fR       
--no-blank-lines-after-commas                   -nbc            
--no-blank-lines-after-declarations             -nbad           
--no-blank-lines-after-procedures               -nbap           
--no-blank-lines-before-block-comments          -nbbb           
--no-comment-delimiters-on-blank-lines          -ncdb           
--no-space-after-casts                          -ncs            
--no-parameter-indentation                      -nip            
--no-space-after-for				-nsaf
--no-space-after-function-call-names            -npcs           
--no-space-after-if				-nsai
--no-space-after-parentheses                    -nprs
--no-space-after-while				-nsaw
--no-tabs                                       -nut
--no-verbosity                                  -nv             
--original                                      -orig
--parameter-indentation                         -ip\fIn\fR      
--paren-indentation                             -pi\fIn\fR
--preserve-mtime				-pmt
--procnames-start-lines                         -psl            
--space-after-cast                              -cs             
--space-after-for				-saf
--space-after-if				-sai
--space-after-parentheses                       -prs
--space-after-procedure-calls                   -pcs            
--space-after-while				-saw
--space-special-semicolon                       -ss             
--standard-output                               -st             
--start-left-side-of-comments                   -sc             
--struct-brace-indentation                      -sbi\fIn\fR
--swallow-optional-blank-lines                  -sob            
--tab-size                                      -ts\fIn\fR      
--use-tabs                                      -ut
--verbose                                       -v              
.in -5
.ad
.fi

.SH "RETURN VALUE"
Unknown
.SH FILES
.br
.nf
.\" set tabstop to longest possible filename, plus a wee bit
.ta \w'$HOME/.indent.pro   'u
\fI$HOME/.indent.pro\fR	holds default options for indent.
.SH "AUTHORS"
.br
Carlo Wood
.br
Joseph Arceneaux
.br
Jim Kingdon
.br
David Ingamells
.SH "HISTORY"
Derived from the UCB program "indent".
.SH "COPYING"
Copyright (C) 1989, 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc.
Copyright (C) 1995, 1996 Joseph Arceneaux.
Copyright (C) 1999 Carlo Wood.
Copyright (C) 2001 David Ingamells.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.