indent.tex

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

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename indent.info
@settitle @code{indent}:  Indent and Format C Program Source
@c %**end of header

@c ===> NOTE! <==
@c Determine the edition number in *three* places by hand:
@c      1. First ifinfo section  2. title page  3. top node
@c To find the locations, search for !!set

@c smallbook
@c Note: some of the long options are too long for the index in
@c       smallbook format.  This will need some thought.  --rjc

@finalout

@synindex cp ky
@setchapternewpage odd

@ifinfo
Copyright (C) 1989, 1992, 1993 Free Software Foundation, Inc.

@c !!set edition, date, version
This is Edition 1.00, Febrary 1992, of @cite{The @code{indent} Manual},
for Indent Version 1.7

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.

@ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU General Public License'' is included exactly as
in the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU General Public License'' may be
included in a translation approved by the author instead of in the
original English.
@end ignore
@end ifinfo

@titlepage
@title Indent
@subtitle Format C Code
@sp 1
@c !!set edition, version, date
@subtitle Edition 1.00, for Indent Version 1.7
@subtitle February 1993
@author Joseph Arceneaux
@author Jim Kingdon
@page
@vskip 0pt plus1filll
Copyright @copyright{} 1989, 1992, 1993 Free Software Foundation, Inc.

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.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end titlepage
@page

@c put the following line in the the file dir in the info directory
@c under wherever you have installed emacs (assuming that
@c the info file made from this file is in the file "indent")
@c * indent:(indent).  How to change the appearance of a C program.

@ifinfo
@node Top, Indent Program, (dir), (dir)
@top @code{indent}:  Indent and Format C Program Source

The @code{indent} program changes the appearance of a C program by
inserting or deleting whitespace.  

@comment !!set edition, version, date
This is Edition 1.00, Febrary 1993, of @cite{The @code{indent} Manual},
for Indent Version 1.7
@end ifinfo

@menu
* Indent Program::              The @code{indent} Program
* Option Summary::              Option Summary
* Index::                       Index
@end menu

@node Indent Program, Option Summary, Top, Top
@chapter The @code{indent} Program

@iftex
The @code{indent} program changes the appearance of a C program by
inserting or deleting whitespace.
@end iftex
@ifinfo
The @code{indent} program
@end ifinfo
@iftex
It
@end iftex
can be used to make code easier to read.  It can also convert from one
style of writing C to another.  

@code{indent} understands a substantial amount about the syntax of C,
but it also attempts to cope with incomplete and misformed syntax.

In version 1.2 and more recent versions, the GNU style of indenting is
the default.

@menu
* Invoking indent::             Invoking @code{indent}
* Backup files::                Backup Files
* Common styles::               Common styles
* Blank lines::                 Blank lines
* Comments::                    Comments
* Statements::                  Statements
* Declarations::                Declarations
* Indentation::                 Indentation
* Disabling Formatting::        Disabling Formating
* Miscellaneous options::       Miscellaneous options
* Bugs::                 	Bugs
* Copyright::                   Copyright
@end menu

@node Invoking indent, Backup files,  , Indent Program
@section Invoking @code{indent}
@cindex Invoking @code{indent}
@cindex Starting @code{indent}
@cindex Beginning @code{indent}

As of version 1.3, the format of the @code{indent} command is:

@example
@group
indent [@var{options}] [@var{input-files}]

indent [@var{options}] [@var{single-input-file}] [-o @var{output-file}]
@end group
@end example

This format is different from earlier versions and other versions of
@code{indent}.

In the first form, one or more input files are specified.  @code{indent}
makes a backup copy of each file, and the original file is replaced with
its indented version.  @xref{Backup files}, for an explanation of how
backups are made.

@cindex Output File Specification
@kindex -o
@kindex --output-file
In the second form, only one input file is specified.  In this case, or
when the standard input is used, you may specify an output file after
the @samp{-o} option.

@cindex Standard Output
@kindex -st
@kindex --standard-output
To cause @code{indent} to write to standard output, use the @samp{-st}
option.  This is only allowed when there is only one input file, or when
the standard input is used.

@cindex Using Standard Input
If no input files are named, the standard input is read for input.
Also, if a filename named @samp{-} is specified, then the standard input
is read.

As an example, each of the following commands will input the program
@file{slithy_toves.c} and write its indented text to
@file{slithy_toves.out}:

@example
@group
indent slithy_toves.c -o slithy_toves.out

indent -st slithy_toves.c > slithy_toves.out

cat slithy_toves.c | indent -o slithy_toves.out
@end group
@end example

@cindex Long options, use of
Most other options to @code{indent} control how programs are formatted.
As of version 1.2, @code{indent} also recognizes a long name for each
option name.  Long options are prefixed by either @samp{--} or
@samp{+}.@footnote{ @samp{+} is being superseded by @samp{--} to
maintain consistency with the POSIX standard.} In most of this document,
the traditional, short names are used for the sake of brevity.
@xref{Option Summary}, for a list of options, including both long and
short names.

Here is another example:

@example
indent -br test/metabolism.c -l85
@end example

This will indent the program @file{test/metabolism.c} using the
@samp{-br} and @samp{-l85} options, write the output back to
@file{test/metabolism.c}, and write the original contents of
@file{test/metabolism.c} to a backup file in the directory @file{test}.

Equivalent invocations using long option names for this example would
be:

@example
@group
indent --braces-on-if-line --line-length185 test/metabolism.c

indent +braces-on-if-line +line-length185 test/metabolism.c
@end group
@end example

@cindex @file{.indent.pro} file
@cindex Initialization file
@kindex -npro
@kindex --ignore-profile
If you find that you often use @code{indent} with the same options, you
may put those options into a file called @file{.indent.pro}.
@code{indent} will first look for @file{.indent.pro} in the current
directory and use that if found.  Otherwise, @code{indent} will search
your home directory for @file{.indent.pro} and use that file if it is
found.  This behaviour is different from that of other versions of
@code{indent}, which load both files if they both exist.

Command line switches are handled @emph{after} processing
@file{.indent.pro}.  Options specified later override arguments
specified earlier, with one exception: Explicitly specified options
always override background options (@pxref{Common styles}).  You can
prevent @code{indent} from reading an @file{.indent.pro} file by
specifying the @samp{-npro} option.@refill

@node Backup files, Common styles, Invoking indent, Indent Program
@comment  node-name,  next,  previous,  up
@section Backup Files

As of version 1.3, GNU @code{indent} makes GNU--style backup files, the
same way GNU Emacs does.  This means that either @dfn{simple} or
@dfn{numbered} backup filenames may be made.

Simple backup file names are generated by appending a suffix to the
original file name.  The default for the this suffix is the
one-character string @samp{~} (tilde).  Thus, the backup file for
@file{python.c} would be @file{python.c~}.

Instead of the default, you may specify any string as a suffix by
setting the environment variable @code{SIMPLE_BACKUP_SUFFIX} to
your preferred suffix.

Numbered backup versions of a file @file{momewraths} look like
@file{momewraths.c.~23~}, where 23 is the version of this particular
backup.  When making a numbered backup of the file @file{src/momewrath.c},
the backup file will be named @file{src/momewrath.c.~@var{V}~}, where
@var{V} is one greater than the highest version currently existing in
the directory @file{src}.

The type of backup file made is controlled by the value of the
environment variable @code{VERSION_CONTROL}.  If it is the string
@samp{simple}, then only simple backups will be made.  If its value is
the string @samp{numbered}, then numbered backups will be made.  If its
value is @samp{numbered-existing}, then numbered backups will be made if
there @emph{already exist} numbered backups for the file being indented;
otherwise, a simple backup is made.  If @code{VERSION_CONTROL} is not
set, then @code{indent} assumes the behaviour of
@samp{numbered-existing}.

Other versions of @code{indent} use the suffix @samp{.BAK} in naming
backup files.  This behaviour can be emulated by setting
@code{SIMPLE_BACKUP_SUFFIX} to @samp{.BAK}.

Note also that other versions of @code{indent} make backups in the
current directory, rather than in the directory of the source file as
GNU @code{indent} now does.

@node Common styles, Blank lines, Backup files, Indent Program
@comment  node-name,  next,  previous,  up
@section Common styles

There are several common styles of C code, including the GNU style, the
Kernighan & Ritchie style, and the original Berkeley style.  A style may
be selected with a single @dfn{background} option, which specifies a set
of values for all other options.  However, explicitly specified options
always override options implied by a background option.

@cindex GNU style
@kindex -gnu
@kindex --gnu-style
As of version 1.2, the default style of GNU @code{indent} is the GNU
style.  Thus, it is no longer neccessary to specify the option
@samp{-gnu} to obtain this format, although doing so will not cause an
error.  Option settings which correspond to the GNU style are:

@example
@group
-nbad -bap -nbbb -nbc -bl -bli2 -c33 -cd33 -ncdb -nce
-cli0 -cp1 -di2 -nfc1 -nfca -i2 -ip5 -lp -pcs -psl -cs
-nsc -nsob -nss -ts8 -d0 -ci0 -l78
@end group
@end example

The GNU coding style is that preferred by the GNU project.  It is the
style that the GNU Emacs C mode encourages and which is used in the C
portions of GNU Emacs.  (People interested in writing programs for
Project GNU should get a copy of @cite{The GNU Coding Standards}, which
also covers semantic and portability issues such as memory usage, the
size of integers, etc.)

@cindex Kernighan & Ritchie style
@kindex -kr
@kindex --k-and-r-style
@comment --kernighan-and-ritchie-style works, too, as does
@comment --kernighan-and-ritchie.  Which is most intuitive?
The Kernighan & Ritchie style is used throughout their well-known book
@cite{The C Programming Language}.  It is enabled with the @samp{-kr}
option.  The Kernighan & Ritchie style corresponds to the following set
of options:

@example
@group
-nbad -bap -nbbb -nbc -br -c33 -cd33 -ncdb -ce -ci4
-cli0 -cp33 -d0 -di1 -nfc1 -nfca -i4 -ip0 -l75 -lp
-npcs -npsl -nsc -nsob -nss -ts8 -cs
@end group
@end example

@noindent
Kernighan & Ritchie style does not put comments to the right of code in
the same column at all times (nor does it use only one space to the
right of the code), so for this style @code{indent} has arbitrarily
chosen column 33.

@cindex Berkeley style
@cindex Original Berkeley style
@kindex -orig
@kindex --original
The style of the original Berkeley @code{indent} may be obtained by
specifying @samp{-orig} (or by specifyfying @samp{--original}, using the
long option name).  This style is equivalent to the following settings:

@example
@group
-nbap -nbad -nbbb -bc -br -c33 -cd33 -cdb -ce -ci4
-cli0 -cp33 -d4 -di16 -fc1 -fca -i4 -ip4 -l75 -lp 
-npcs -psl -sc -nsob -nss -ts8 -ncs
@end group
@end example

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

Various programming styles use blank lines in different places.
@code{indent} has a number of options to insert or delete blank lines in
specific places.

The @samp{-bad} option causes @code{indent} to force a blank line after
every block of declarations.  The @samp{-nbad} option causes
@code{indent} not to force such blank lines.

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

@kindex -bbb
@kindex --blank-lines-after-block-comments
@kindex -nbbb
@kindex --no-blank-lines-after-block-comments
@comment DEFINE BLOCK COMMENT!!!
The @samp{-bbb} option forces a blank line before every block comment.