+@noindent
+and you can see that the syntactic context contains two syntactic
+elements. Notice that the first element, @samp{(comment-intro)}, has no
+anchor position.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics
+@comment node-name, next, previous, up
+@section Syntactic Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex syntactic symbols, brief list
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+This section is a complete list of the syntactic symbols which appear
+in the @code{c-offsets-alist} style variable, along with brief
+descriptions. The previous section (@pxref{Syntactic Analysis})
+states what syntactic symbols are and how the indentation engine uses
+them.
+
+More detailed descriptions of these symbols, together with snippets of
+source code to which they apply, appear in the examples in the
+subsections below. Note that, in the interests of brevity, the anchor
+position associated with most syntactic symbols is @emph{not}
+specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent
+line---this highlights the anchor position.
+
+@ssindex -open symbols
+@ssindex -close symbols
+@ssindex -block-intro symbols
+The syntactic symbols which indicate brace constructs follow a general
+naming convention. When a line begins with an open or close brace,
+its syntactic symbol will contain the suffix @code{-open} or
+@code{-close} respectively. The first line within the brace block
+construct will contain the suffix @code{-block-intro}.
+
+@ssindex -intro symbols
+@ssindex -cont symbols
+In constructs which can span several lines, a distinction is usually
+made between the first line that introduces the construct and the
+lines that continue it. The syntactic symbols that indicate these
+lines will contain the suffixes @code{-intro} or @code{-cont}
+respectively.
+
+The best way to understand how all this works is by looking at some
+examples. Remember that you can see the syntax of any source code
+line by using @kbd{C-c C-s}.
+
+@table @code
+@item string
+Inside a multiline string. @ref{Literal Symbols}.
+@item c
+Inside a multiline C style block comment. @ref{Literal Symbols}.
+@item defun-open
+Brace that opens a top-level function definition. @ref{Function
+Symbols}.
+@item defun-close
+Brace that closes a top-level function definition. @ref{Function
+Symbols}.
+@item defun-block-intro
+The first line in a top-level defun. @ref{Function Symbols}.
+@item class-open
+Brace that opens a class definition. @ref{Class Symbols}.
+@item class-close
+Brace that closes a class definition. @ref{Class Symbols}.
+@item inline-open
+Brace that opens an in-class inline method. @ref{Class Symbols}.
+@item inline-close
+Brace that closes an in-class inline method. @ref{Class Symbols}.
+@item func-decl-cont
+The region between a function definition's argument list and the
+function opening brace (excluding K&R argument declarations). In C,
+you cannot put anything but whitespace and comments in this region,
+however in C++ and Java, @code{throws} declarations and other things
+can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not
+@c go somewhere better?}
+@item knr-argdecl-intro
+First line of a K&R C argument declaration. @ref{K&R Symbols}.
+@item knr-argdecl
+Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}.
+@item topmost-intro
+The first line in a ``topmost'' definition. @ref{Function Symbols}.
+@item topmost-intro-cont
+Topmost definition continuation lines. This is only used in the parts
+that aren't covered by other symbols such as @code{func-decl-cont} and
+@code{knr-argdecl}. @ref{Function Symbols}.
+@item member-init-intro
+First line in a member initialization list. @ref{Class Symbols}.
+@item member-init-cont
+Subsequent member initialization list lines. @ref{Class Symbols}.
+@item inher-intro
+First line of a multiple inheritance list. @ref{Class Symbols}.
+@item inher-cont
+Subsequent multiple inheritance lines. @ref{Class Symbols}.
+@item block-open
+Statement block open brace. @ref{Literal Symbols}.
+@item block-close
+Statement block close brace. @ref{Conditional Construct Symbols}.
+@item brace-list-open
+Open brace of an enum or static array list. @ref{Brace List Symbols}.
+@item brace-list-close
+Close brace of an enum or static array list. @ref{Brace List Symbols}.
+@item brace-list-intro
+First line in an enum or static array list. @ref{Brace List Symbols}.
+@item brace-list-entry
+Subsequent lines in an enum or static array list. @ref{Brace List
+Symbols}.
+@item brace-entry-open
+Subsequent lines in an enum or static array list where the line begins
+with an open brace. @ref{Brace List Symbols}.
+@item statement
+A statement. @ref{Function Symbols}.
+@item statement-cont
+A continuation of a statement. @ref{Function Symbols}.
+@item statement-block-intro
+The first line in a new statement block. @ref{Conditional Construct
+Symbols}.
+@item statement-case-intro
+The first line in a case block. @ref{Switch Statement Symbols}.
+@item statement-case-open
+The first line in a case block that starts with a brace. @ref{Switch
+Statement Symbols}.
+@item substatement
+The first line after a conditional or loop construct.
+@ref{Conditional Construct Symbols}.
+@item substatement-open
+The brace that opens a substatement block. @ref{Conditional Construct
+Symbols}.
+@item substatement-label
+The first line after a conditional or loop construct if it's a label.
+@ref{Conditional Construct Symbols}.
+@item case-label
+A label in a @code{switch} block. @ref{Switch Statement Symbols}.
+@item access-label
+C++ access control label. @ref{Class Symbols}.
+@item label
+Any other label. @ref{Literal Symbols}.
+@item do-while-closure
+The @code{while} line that ends a @code{do}-@code{while} construct.
+@ref{Conditional Construct Symbols}.
+@item else-clause
+The @code{else} line of an @code{if}-@code{else} construct.
+@ref{Conditional Construct Symbols}.
+@item catch-clause
+The @code{catch} or @code{finally} (in Java) line of a
+@code{try}-@code{catch} construct. @ref{Conditional Construct
+Symbols}.
+@item comment-intro
+A line containing only a comment introduction. @ref{Literal Symbols}.
+@item arglist-intro
+The first line in an argument list. @ref{Paren List Symbols}.
+@item arglist-cont
+Subsequent argument list lines when no arguments follow on the same
+line as the arglist opening paren. @ref{Paren List Symbols}.
+@item arglist-cont-nonempty
+Subsequent argument list lines when at least one argument follows on
+the same line as the arglist opening paren. @ref{Paren List Symbols}.
+@item arglist-close
+The solo close paren of an argument list. @ref{Paren List Symbols}.
+@item stream-op
+Lines continuing a stream operator (C++ only). @ref{Literal
+Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?}
+@item inclass
+The line is nested inside a class definition. @ref{Class Symbols}.
+@item cpp-macro
+The start of a preprocessor macro definition. @ref{Literal Symbols}.
+@item cpp-define-intro
+The first line inside a multiline preprocessor macro if
+@code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro
+Symbols}.
+@item cpp-macro-cont
+All lines inside multiline preprocessor macros if
+@code{c-syntactic-indentation-in-macros} is @code{nil}.
+@ref{Multiline Macro Symbols}.
+@item friend
+A C++ friend declaration. @ref{Class Symbols}.
+@item objc-method-intro
+The first line of an Objective-C method definition. @ref{Objective-C
+Method Symbols}.
+@item objc-method-args-cont
+Lines continuing an Objective-C method definition. @ref{Objective-C
+Method Symbols}.
+@item objc-method-call-cont
+Lines continuing an Objective-C method call. @ref{Objective-C Method
+Symbols}.
+@item extern-lang-open
+Brace that opens an @code{extern} block (e.g. @code{extern "C"
+@{...@}}). @ref{External Scope Symbols}.
+@item extern-lang-close
+Brace that closes an @code{extern} block. @ref{External Scope
+Symbols}.
+@item inextern-lang
+Analogous to @code{inclass} syntactic symbol, but used inside
+@code{extern} blocks. @ref{External Scope Symbols}.
+@item namespace-open
+@itemx namespace-close
+@itemx innamespace
+These are analogous to the three @code{extern-lang} symbols above, but
+are returned for C++ namespace blocks. @ref{External Scope Symbols}.
+@item module-open
+@itemx module-close
+@itemx inmodule
+Analogous to the above, but for CORBA IDL @code{module} blocks.
+@ref{External Scope Symbols}.
+@item composition-open
+@itemx composition-close
+@itemx incomposition
+Analogous to the above, but for CORBA CIDL @code{composition} blocks.
+@ref{External Scope Symbols}.
+@item template-args-cont
+C++ template argument list continuations. @ref{Class Symbols}.
+@item inlambda
+Analogous to @code{inclass} syntactic symbol, but used inside lambda
+(i.e. anonymous) functions. Only used in Pike mode. @ref{Statement
+Block Symbols}.
+@item lambda-intro-cont
+Lines continuing the header of a lambda function, i.e. between the
+@code{lambda} keyword and the function body. Only used in Pike mode.
+@ref{Statement Block Symbols}.
+@item inexpr-statement
+A statement block inside an expression. The gcc C and C++ extension
+for this is recognized. It's also used for the special functions that
+take a statement block as an argument in Pike. @ref{Statement Block
+Symbols}.
+@item inexpr-class
+A class definition inside an expression. This is used for anonymous
+classes in Java. It's also used for anonymous array initializers in
+Java. @ref{Anonymous Class Symbol}.
+@end table
+
+@menu
+* Function Symbols::
+* Class Symbols::
+* Conditional Construct Symbols::
+* Switch Statement Symbols::
+* Brace List Symbols::
+* External Scope Symbols::
+* Paren List Symbols::
+* Literal Symbols::
+* Multiline Macro Symbols::
+* Objective-C Method Symbols::
+* Anonymous Class Symbol::
+* Statement Block Symbols::
+* K&R Symbols::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Function Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This example shows a typical function declaration.
+
+@example
+ 1: void
+ 2: swap( int& a, int& b )
+ 3: @{
+ 4: int tmp = a;
+ 5: a = b;
+ 6: b = tmp;
+ 7: int ignored =
+ 8: a + b;
+ 9: @}
+@end example
+
+@ssindex topmost-intro
+@ssindex topmost-intro-cont
+@ssindex defun-open
+@ssindex defun-close
+@ssindex defun-block-intro
+Line 1 shows a @code{topmost-intro} since it is the first line that
+introduces a top-level construct. Line 2 is a continuation of the
+top-level construct introduction so it has the syntax
+@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
+the brace that opens a top-level function definition. Line 9 is the
+corresponding
+@code{defun-close} since it contains the brace that closes the top-level
+function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
+the first line of a brace-block, enclosed in a
+top-level function definition.
+
+@ssindex statement
+@ssindex statement-cont
+Lines 5, 6, and 7 are all given @code{statement} syntax since there
+isn't much special about them. Note however that line 8 is given
+@code{statement-cont} syntax since it continues the statement begun
+on the previous line.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Class related Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Here's an example which illustrates some C++ class syntactic symbols:
+
+@example
+ 1: class Bass
+ 2: : public Guitar,
+ 3: public Amplifiable
+ 4: @{
+ 5: public:
+ 6: Bass()
+ 7: : eString( new BassString( 0.105 )),
+ 8: aString( new BassString( 0.085 )),
+ 9: dString( new BassString( 0.065 )),
+10: gString( new BassString( 0.045 ))
+11: @{
+12: eString.tune( 'E' );
+13: aString.tune( 'A' );
+14: dString.tune( 'D' );
+15: gString.tune( 'G' );
+16: @}
+17: friend class Luthier;
+18: @};
+@end example
+
+@ssindex class-open
+@ssindex class-close
+As in the previous example, line 1 has the @code{topmost-intro} syntax.
+Here however, the brace that opens a C++ class definition on line 4 is
+assigned the @code{class-open} syntax. Note that in C++, classes,
+structs, and unions are essentially equivalent syntactically (and are
+very similar semantically), so replacing the @code{class} keyword in the
+example above with @code{struct} or @code{union} would still result in a
+syntax of @code{class-open} for line 4 @footnote{This is the case even
+for C and Objective-C. For consistency, structs in all supported
+languages are syntactically equivalent to classes. Note however that
+the keyword @code{class} is meaningless in C and Objective-C.}.
+Similarly, line 18 is assigned @code{class-close} syntax.
+
+@ssindex inher-intro
+@ssindex inher-cont
+Line 2 introduces the inheritance list for the class so it is assigned
+the @code{inher-intro} syntax, and line 3, which continues the
+inheritance list is given @code{inher-cont} syntax.
+
+@ssindex access-label
+@ssindex inclass
+Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
+
+@example
+((inclass 58) (access-label 58))
+@end example
+
+@noindent
+The primary syntactic symbol for this line is @code{access-label} as
+this a label keyword that specifies access protection in C++. However,
+because this line is also a top-level construct inside a class
+definition, the analysis actually shows two syntactic symbols. The
+other syntactic symbol assigned to this line is @code{inclass}.
+Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
+syntax:
+
+@example
+((inclass 58) (topmost-intro 60))
+@end example
+
+@ssindex member-init-intro
+@ssindex member-init-cont
+Line 7 introduces a C++ member initialization list and as such is given
+@code{member-init-intro} syntax. Note that in this case it is
+@emph{not} assigned @code{inclass} since this is not considered a
+top-level construct. Lines 8 through 10 are all assigned
+@code{member-init-cont} since they continue the member initialization
+list started on line 7.
+
+@cindex in-class inline methods
+@ssindex inline-open
+@ssindex inline-close
+Line 11's analysis is a bit more complicated:
+
+@example
+((inclass 58) (inline-open))
+@end example
+
+This line is assigned a syntax of both @code{inline-open} and
+@code{inclass} because it opens an @dfn{in-class} C++ inline method
+definition. This is distinct from, but related to, the C++ notion of an
+inline function in that its definition occurs inside an enclosing class
+definition, which in C++ implies that the function should be inlined.
+However, if the definition of the @code{Bass} constructor appeared
+outside the class definition, the construct would be given the
+@code{defun-open} syntax, even if the keyword @code{inline} appeared
+before the method name, as in:
+
+@example
+ 1: class Bass
+ 2: : public Guitar,
+ 3: public Amplifiable
+ 4: @{
+ 5: public:
+ 6: Bass();
+ 7: @};
+ 8:
+ 9: inline
+10: Bass::Bass()
+11: : eString( new BassString( 0.105 )),
+12: aString( new BassString( 0.085 )),
+13: dString( new BassString( 0.065 )),
+14: gString( new BassString( 0.045 ))
+15: @{
+16: eString.tune( 'E' );
+17: aString.tune( 'A' );
+18: dString.tune( 'D' );
+19: gString.tune( 'G' );
+20: @}
+@end example
+
+@ssindex friend
+Returning to the previous example, line 16 is given @code{inline-close}
+syntax, while line 12 is given @code{defun-block-open} syntax, and lines
+13 through 15 are all given @code{statement} syntax. Line 17 is
+interesting in that its syntactic analysis list contains three
+elements:
+
+@example
+((inclass 58) (topmost-intro 380) (friend))
+@end example
+
+The @code{friend} and @code{inline-open} syntactic symbols are
+modifiers that do not have anchor positions.
+
+@ssindex template-args-cont
+Template definitions introduce yet another syntactic symbol:
+
+@example
+ 1: ThingManager <int,
+ 2: Framework::Callback *,
+ 3: Mutex> framework_callbacks;
+@end example
+
+Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
+are both analyzed as @code{template-args-cont} lines.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Conditional Construct Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Here is a (totally contrived) example which illustrates how syntax is
+assigned to various conditional constructs:
+
+@example
+ 1: void spam( int index )
+ 2: @{
+ 3: for( int i=0; i<index; i++ )
+ 4: @{
+ 5: if( i == 10 )
+ 6: do_something_special();
+ 7: else
+ 8: silly_label:
+ 9: do_something( i );
+10: @}
+11: do @{
+12: another_thing( i-- );
+13: @}
+14: while( i > 0 );
+15: @}
+@end example
+
+Only the lines that illustrate new syntactic symbols will be discussed.
+
+@ssindex substatement-open
+@ssindex statement-block-intro
+@ssindex block-close
+Line 4 has a brace which opens a conditional's substatement block. It
+is thus assigned @code{substatement-open} syntax, and since line 5 is
+the first line in the substatement block, it is assigned
+@code{statement-block-intro} syntax. Line 10 contains the brace
+that closes the inner substatement block, and is therefore given the
+syntax @code{block-close}@footnote{@code{block-open} is used only for
+``free-standing'' blocks, and is somewhat rare (@pxref{Literal
+Symbols} for an example.)}. Line 13 is treated the same way.
+
+@ssindex substatement
+Lines 6 and 9 are also substatements of conditionals, but since they
+don't start blocks they are given @code{substatement} syntax
+instead of @code{substatement-open}.
+
+@ssindex substatement-label
+Line 8 contains a label, which is normally given @code{label} syntax.
+This one is however a bit special since it's between a conditional and
+its substatement. It's analyzed as @code{substatement-label} to let you
+handle this rather odd case differently from normal labels.
+
+@ssindex else-clause
+@ssindex catch-clause
+Line 7 start with an @code{else} that matches the @code{if} statement on
+line 5. It is therefore given the @code{else-clause} syntax and is
+anchored on the matching @code{if}. The @code{try}-@code{catch}
+constructs in C++ and Java are treated this way too, except that
+@code{catch} and (in Java) @code{finally}, are marked with
+@code{catch-clause}.
+
+@ssindex do-while-closure
+The @code{while} construct on line 14 that closes a @code{do}
+conditional is given the special syntax @code{do-while-closure} if it
+appears on a line by itself. Note that if the @code{while} appeared on
+the same line as the preceding close brace, that line would still have
+@code{block-close} syntax.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Switch Statement Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Switch statements have their own set of syntactic symbols. Here's an
+example:
+
+@example
+ 1: void spam( enum Ingredient i )
+ 2: @{
+ 3: switch( i ) @{
+ 4: case Ham:
+ 5: be_a_pig();
+ 6: break;
+ 7: case Salt:
+ 8: drink_some_water();
+ 9: break;
+10: default:
+11: @{
+12: what_is_it();
+13: break;
+14: @}
+15: @}
+14: @}
+@end example
+
+@ssindex case-label
+@ssindex statement-case-intro
+@ssindex statement-case-open
+Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
+while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
+is treated slightly differently since it contains a brace that opens a
+block --- it is given @code{statement-case-open} syntax.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Brace List Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex brace lists
+There are a set of syntactic symbols that are used to recognize
+constructs inside of brace lists. A brace list is defined as an
+@code{enum} or aggregate initializer list, such as might statically
+initialize an array of structs. The three special aggregate constructs
+in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
+brace lists too. An example:
+
+@example
+ 1: static char* ingredients[] =
+ 2: @{
+ 3: "Ham",
+ 4: "Salt",
+ 5: NULL
+ 6: @};
+@end example
+
+@ssindex brace-list-open
+@ssindex brace-list-intro
+@ssindex brace-list-close
+@ssindex brace-list-entry
+Following convention, line 2 in this example is assigned
+@code{brace-list-open} syntax, and line 3 is assigned
+@code{brace-list-intro} syntax. Likewise, line 6 is assigned
+@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
+@code{brace-list-entry} syntax, as would all subsequent lines in this
+initializer list.
+
+@ssindex brace-entry-open
+Your static initializer might be initializing nested structures, for
+example:
+
+@example
+ 1: struct intpairs[] =
+ 2: @{
+ 3: @{ 1, 2 @},
+ 4: @{
+ 5: 3,
+ 6: 4
+ 7: @}
+ 8: @{ 1,
+ 9: 2 @},
+10: @{ 3, 4 @}
+11: @};
+@end example
+
+Here, you've already seen the analysis of lines 1, 2, 3, and 11. On
+line 4, things get interesting; this line is assigned
+@code{brace-entry-open} syntactic symbol because it's a bracelist entry
+line that starts with an open brace. Lines 5 and 6 (and line 9) are
+pretty standard, and line 7 is a @code{brace-list-close} as you'd
+expect. Once again, line 8 is assigned as @code{brace-entry-open} as is
+line 10.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection External Scope Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+External language definition blocks also have their own syntactic
+symbols. In this example:
+
+@example
+ 1: extern "C"
+ 2: @{
+ 3: int thing_one( int );
+ 4: int thing_two( double );
+ 5: @}
+@end example
+
+@ssindex extern-lang-open
+@ssindex extern-lang-close
+@ssindex inextern-lang
+@ssindex inclass
+@noindent
+line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
+the @code{extern-lang-close} syntax. The analysis for line 3 yields:
+
+@example
+((inextern-lang) (topmost-intro 14))
+@end example
+
+@noindent
+where @code{inextern-lang} is a modifier similar in purpose to
+@code{inclass}.
+
+There are various other top level blocks like @code{extern}, and they
+are all treated in the same way except that the symbols are named after
+the keyword that introduces the block. E.g. C++ namespace blocks get
+the three symbols @code{namespace-open}, @code{namespace-close} and
+@code{innamespace}. The currently recognized top level blocks are:
+
+@table @asis
+@item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
+@code{extern} blocks in C and C++.@footnote{These should logically be
+named @code{extern-open}, @code{extern-close} and @code{inextern}, but
+that isn't the case for historical reasons.}
+
+@item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
+@ssindex namespace-open
+@ssindex namespace-close
+@ssindex innamespace
+@code{namespace} blocks in C++.
+
+@item @code{module-open}, @code{module-close}, @code{inmodule}
+@ssindex module-open
+@ssindex module-close
+@ssindex inmodule
+@code{module} blocks in CORBA IDL.
+
+@item @code{composition-open}, @code{composition-close}, @code{incomposition}
+@ssindex composition-open
+@ssindex composition-close
+@ssindex incomposition
+@code{composition} blocks in CORBA CIDL.
+@end table
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Parenthesis (Argument) List Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+A number of syntactic symbols are associated with parenthesis lists,
+a.k.a argument lists, as found in function declarations and function
+calls. This example illustrates these:
+
+@example
+ 1: void a_function( int line1,
+ 2: int line2 );
+ 3:
+ 4: void a_longer_function(
+ 5: int line1,
+ 6: int line2
+ 7: );
+ 8:
+ 9: void call_them( int line1, int line2 )
+10: @{
+11: a_function(
+12: line1,
+13: line2
+14: );
+15:
+16: a_longer_function( line1,
+17: line2 );
+18: @}
+@end example
+
+@ssindex arglist-intro
+@ssindex arglist-close
+Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
+the first line following the open parenthesis, and lines 7 and 14 are
+assigned @code{arglist-close} syntax since they contain the parenthesis
+that closes the argument list.
+
+@ssindex arglist-cont-nonempty
+@ssindex arglist-cont
+Lines that continue argument lists can be assigned one of two syntactic
+symbols. For example, Lines 2 and 17
+are assigned @code{arglist-cont-nonempty} syntax. What this means
+is that they continue an argument list, but that the line containing the
+parenthesis that opens the list is @emph{not empty} following the open
+parenthesis. Contrast this against lines 6 and 13 which are assigned
+@code{arglist-cont} syntax. This is because the parenthesis that opens
+their argument lists is the last character on that line.
+
+Syntactic elements with @code{arglist-intro},
+@code{arglist-cont-nonempty}, and @code{arglist-close} contain two
+buffer positions: the anchor position (the beginning of the
+declaration or statement) and the position of the open parenthesis.
+The latter position can be used in a line-up function (@pxref{Line-Up
+Functions}).
+
+Note that there is no @code{arglist-open} syntax. This is because any
+parenthesis that opens an argument list, appearing on a separate line,
+is assigned the @code{statement-cont} syntax instead.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Comment String Label and Macro Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+A few miscellaneous syntactic symbols that haven't been previously
+covered are illustrated by this C++ example:
+
+@example
+ 1: void Bass::play( int volume )
+ 2: const
+ 3: @{
+ 4: /* this line starts a multiline
+ 5: * comment. This line should get `c' syntax */
+ 6:
+ 7: char* a_multiline_string = "This line starts a multiline \
+ 8: string. This line should get `string' syntax.";
+ 9:
+10: note:
+11: @{
+12: #ifdef LOCK
+13: Lock acquire();
+14: #endif // LOCK
+15: slap_pop();
+16: cout << "I played "
+17: << "a note\n";
+18: @}
+19: @}
+@end example
+
+The lines to note in this example include:
+
+@itemize @bullet
+@item
+@ssindex func-decl-cont
+Line 2 is assigned the @code{func-decl-cont} syntax.
+
+@item
+@ssindex comment-intro
+Line 4 is assigned both @code{defun-block-intro} @emph{and}
+@code{comment-intro} syntax. A syntactic element with
+@code{comment-intro} has no anchor point --- It is always accompanied
+by another syntactic element which does have one.
+
+@item
+@ssindex c
+Line 5 is assigned @code{c} syntax.
+
+@item
+@cindex syntactic whitespace
+Line 6 which, even though it contains nothing but whitespace, is
+assigned @code{defun-block-intro}. Note that the appearance of the
+comment on lines 4 and 5 do not cause line 6 to be assigned
+@code{statement} syntax because comments are considered to be
+@dfn{syntactic whitespace}, which are ignored when analyzing
+code.
+
+@item
+@ssindex string
+Line 8 is assigned @code{string} syntax.
+
+@item
+@ssindex label
+Line 10 is assigned @code{label} syntax.
+
+@item
+@ssindex block-open
+Line 11 is assigned @code{block-open} as well as @code{statement}
+syntax. A @code{block-open} syntactic element doesn't have an anchor
+position, since it always appears with another syntactic element which
+does have one.
+
+@item
+@ssindex cpp-macro
+Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
+normal syntactic symbols (@code{statement-block-intro} and
+@code{statement}, respectively). Normally @code{cpp-macro} is
+configured to cancel out the normal syntactic context to make all
+preprocessor directives stick to the first column, but that's easily
+changed if you want preprocessor directives to be indented like the rest
+of the code. Like @code{comment-intro}, a syntactic element with
+@code{cpp-macro} doesn't contain an anchor position.
+
+@item
+@ssindex stream-op
+Line 17 is assigned @code{stream-op} syntax.
+@end itemize
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Multiline Macro Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex multiline macros
+@cindex syntactic whitespace
+@ssindex cpp-define-intro
+@ssindex cpp-macro-cont
+Multiline preprocessor macro definitions are normally handled just like
+other code, i.e. the lines inside them are indented according to the
+syntactic analysis of the preceding lines inside the macro. The first
+line inside a macro definition (i.e. the line after the starting line of
+the cpp directive itself) gets @code{cpp-define-intro}. In this example:
+
+@example
+ 1: #define LIST_LOOP(cons, listp) \
+ 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
+ 3: if (!CONSP (cons)) \
+ 4: signal_error ("Invalid list format", listp); \
+ 5: else
+@end example
+
+@noindent
+line 1 is given the syntactic symbol @code{cpp-macro}. The first line
+of a cpp directive is always given that symbol. Line 2 is given
+@code{cpp-define-intro}, so that you can give the macro body as a whole
+some extra indentation. Lines 3 through 5 are then analyzed as normal
+code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause}
+on line 5.
+
+The syntactic analysis inside macros can be turned off with
+@code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In
+that case, lines 2 through 5 would all be given @code{cpp-macro-cont}
+with an anchor position pointing to the @code{#} which starts the cpp
+directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed
+macros.}.
+
+@xref{Custom Macros}, for more info about the treatment of macros.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Objective-C Method Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+In Objective-C buffers, there are three additional syntactic symbols
+assigned to various message calling constructs. Here's an example
+illustrating these:
+
+@example
+ 1: - (void)setDelegate:anObject
+ 2: withStuff:stuff
+ 3: @{
+ 4: [delegate masterWillRebind:self
+ 5: toDelegate:anObject
+ 6: withExtraStuff:stuff];
+ 7: @}
+@end example
+
+@ssindex objc-method-intro
+@ssindex objc-method-args-cont
+@ssindex objc-method-call-cont
+Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
+assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
+assigned @code{objc-method-call-cont} syntax.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Anonymous Class Symbol (Java)
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Java has a concept of anonymous classes which can look something like
+this:
+
+@example
+ 1: public void watch(Observable o) @{
+ 2: o.addObserver(new Observer() @{
+ 3: public void update(Observable o, Object arg) @{
+ 4: history.addElement(arg);
+ 5: @}
+ 6: @});
+ 7: @}
+@end example
+
+@ssindex inexpr-class
+The brace following the @code{new} operator opens the anonymous class.
+Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the
+@code{inclass} symbol used in normal classes. Thus, the class will be
+indented just like a normal class, with the added indentation given to
+@code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't
+have an anchor position.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Statement Block Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+There are a few occasions where a statement block might be used inside
+an expression. One is in C or C++ code using the gcc extension for
+this, e.g:
+
+@example
+ 1: int res = (@{
+ 2: int y = foo (); int z;
+ 3: if (y > 0) z = y; else z = - y;
+ 4: z;
+ 5: @});
+@end example
+
+@ssindex inexpr-statement
+Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
+symbols they'd get in a normal block. Therefore, the indentation put on
+@code{inexpr-statement} is added to the normal statement block
+indentation. An @code{inexpr-statement} syntactic element doesn't
+contain an anchor position.
+
+In Pike code, there are a few other situations where blocks occur inside
+statements, as illustrated here:
+
+@example
+ 1: array itgob()
+ 2: @{
+ 3: string s = map (backtrace()[-2][3..],
+ 4: lambda
+ 5: (mixed arg)
+ 6: @{
+ 7: return sprintf ("%t", arg);
+ 8: @}) * ", " + "\n";
+ 9: return catch @{
+10: write (s + "\n");
+11: @};
+12: @}
+@end example
+
+@ssindex inlambda
+@ssindex lambda-intro-cont
+Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
+by the @code{lambda} keyword. If the function argument list is put
+on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
+syntax. The function body is handled as an inline method body, with the
+addition of the @code{inlambda} syntactic symbol. This means that line
+6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
+@code{inline-close}@footnote{You might wonder why it doesn't get
+@code{inlambda} too. It's because the closing brace is relative to the
+opening brace, which stands on its own line in this example. If the
+opening brace was hanging on the previous line, then the closing brace
+would get the @code{inlambda} syntax too to be indented correctly.}.
+
+@ssindex inexpr-statement
+On line 9, @code{catch} is a special function taking a statement block
+as its argument. The block is handled as an in-expression statement
+with the @code{inexpr-statement} syntax, just like the gcc extended C
+example above. The other similar special function, @code{gauge}, is
+handled like this too.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node K&R Symbols, , Statement Block Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection K&R Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ssindex knr-argdecl-intro
+@ssindex knr-argdecl
+Two other syntactic symbols can appear in old style, non-prototyped C
+code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
+
+@example
+ 1: int add_three_integers(a, b, c)
+ 2: int a;
+ 3: int b;
+ 4: int c;
+ 5: @{
+ 6: return a + b + c;
+ 7: @}
+@end example
+
+Here, line 2 is the first line in an argument declaration list and so is
+given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
+(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
+syntax.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics
+@comment node-name, next, previous, up
+@section Indentation Calculation
+@cindex indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Indentation for a line is calculated from the syntactic context
+(@pxref{Syntactic Analysis}).
+
+First, a buffer position is found whose column will be the base for the
+indentation calculation. It's the anchor position in the first
+syntactic element that provides one that is used. If no syntactic
+element has an anchor position then column zero is used.
+
+Second, the syntactic symbols in each syntactic element are looked up
+in the @code{c-offsets-alist} style variable
+(@pxref{c-offsets-alist}), which is an association list of syntactic
+symbols and the offsets to apply for those symbols. These offsets are
+added together with the base column to produce the new indentation
+column.
+
+Let's use our two code examples above to see how this works. Here is
+our first example again:
+
+@example
+ 1: void swap( int& a, int& b )
+ 2: @{
+ 3: int tmp = a;
+ 4: a = b;
+ 5: b = tmp;
+ 6: @}
+@end example
+
+Let's say point is on line 3 and we hit the @key{TAB} key to reindent
+the line. The syntactic context for that line is:
+
+@example
+((defun-block-intro 29))
+@end example
+
+@noindent
+Since buffer position 29 is the first and only anchor position in the
+list, @ccmode{} goes there and asks for the current column. This brace
+is in column zero, so @ccmode{} uses @samp{0} as the base column.
+
+Next, @ccmode{} looks up @code{defun-block-intro} in the
+@code{c-offsets-alist} style variable. Let's say it finds the value
+@samp{4}; it adds this to the base column @samp{0}, yielding a running
+total indentation of 4 spaces.
+
+Since there is only one syntactic element on the list for this line,
+indentation calculation is complete, and the total indentation for the
+line is 4 spaces.
+
+Here's another example:
+
+@example
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+@end example
+
+If we were to hit @kbd{TAB} on line 4 in the above example, the same
+basic process is performed, despite the differences in the syntactic
+context. The context for this line is:
+
+@example
+((substatement-open 46))
+@end example
+
+Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in
+@code{if} on line 3. This character is in the fourth column on that
+line so the base column is @samp{4}. Then @ccmode{} looks up the
+@code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it
+finds the value @samp{4}. It's added with the base column and yields an
+indentation for the line of 8 spaces.
+
+Simple, huh?
+
+Actually, it's a bit more complicated than that since the entries on
+@code{c-offsets-alist} can be much more than plain offsets.
+@xref{c-offsets-alist}, for the full story.
+
+Anyway, the mode usually just does The Right Thing without you having to
+think about it in this much detail. But when customizing indentation,
+it's helpful to understand the general indentation model being used.
+
+As you configure @ccmode{}, you might want to set the variable
+@code{c-echo-syntactic-information-p} to non-@code{nil} so that the
+syntactic context and calculated offset always is echoed in the
+minibuffer when you hit @kbd{TAB}.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top
+@comment node-name, next, previous, up
+@chapter Customizing Indentation
+@cindex customization, indentation
+@cindex indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The principal variable for customizing indentation is the style
+variable @code{c-offsets-alist}, which gives an @dfn{offset} (an
+indentation rule) for each syntactic symbol. Its structure and
+semantics are completely described in @ref{c-offsets-alist}. The
+various ways you can set the variable, including the use of the
+@ccmode{} style system, are described in @ref{Config Basics} and its
+sections, in particular @ref{Style Variables}.
+
+The simplest and most used kind of ``offset'' setting in
+@code{c-offsets-alist} is in terms of multiples of
+@code{c-basic-offset}:
+
+@defopt c-basic-offset
+@vindex basic-offset (c-)
+This style variable holds the basic offset between indentation levels.
+It's factory default is 4, but all the built-in styles set it
+themselves, to some value between 2 (for @code{gnu} style) and 8 (for
+@code{bsd}, @code{linux}, and @code{python} styles).
+@end defopt
+
+The most flexible ``offset'' setting you can make in
+@code{c-offsets-alist} is a line-up function (or even a list of them),
+either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one
+you write yourself (@pxref{Custom Line-Up}).
+
+Finally, in @ref{Other Indentation} you'll find the tool of last
+resort: a hook which is called after a line has been indented. You
+can install functions here to make ad-hoc adjustments to any line's
+indentation.
+
+@menu
+* c-offsets-alist::
+* Interactive Customization::
+* Line-Up Functions::
+* Custom Line-Up::
+* Other Indentation::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation
+@comment node-name, next, previous, up
+@section c-offsets-alist
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This section explains the structure and semantics of the style
+variable @code{c-offset-alist}, the principal variable for configuring
+indentation. Details of how to set it up, and its relationship to
+@ccmode{}'s style system are given in @ref{Style Variables}.
+
+@defopt c-offsets-alist
+@vindex offsets-alist (c-)
+This is an alist which associates an offset with each syntactic
+symbol. This @dfn{offset} is a rule specifying how to indent a line
+whose syntactic context matches the symbol. @xref{Syntactic
+Analysis}.
+
+Note that the buffer-local binding of this alist in a @ccmode{} buffer
+contains an entry for @emph{every} syntactic symbol. Its global
+binding and its settings within style specifications usually contain
+only a few entries. @xref{Style Variables}.
+
+The offset specification associated with any particular syntactic
+symbol can be an integer, a variable name, a vector, a function or
+lambda expression, a list, or one of the following special symbols:
+@code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The
+meanings of these values are described in detail below.
+
+Here is an example fragment of a @code{c-offsets-alist}, showing some
+of these kinds of offsets:
+
+@example
+((statement . 0)
+ (substatement . +)
+ (cpp-macro . [0])
+ (topmost-intro-cont . c-lineup-topmost-intro-cont)
+ (statement-block-intro . (add c-lineup-whitesmith-in-block
+ c-indent-multi-line-block))
+ @dots{}
+@*)
+@end example
+@end defopt
+
+@deffn Command c-set-offset (@kbd{C-c C-o})
+@findex set-offset (c-)
+@kindex C-c C-o
+This command changes the entry for a syntactic symbol in the current
+binding of @code{c-offsets-alist}, or it inserts a new entry if there
+isn't already one for that syntactic symbol.
+
+You can use @code{c-set-offsets} interactively within a @ccmode{}
+buffer to make experimental changes to your indentation settings.
+@kbd{C-c C-o} prompts you for the syntactic symbol to change
+(defaulting to that of the current line) and the new offset
+(defaulting to the current offset).
+
+@code{c-set-offsets} takes two arguments when used programmatically:
+@var{symbol}, the syntactic element symbol to change and @var{offset},
+the new offset for that syntactic element. You can call the command
+in your @file{.emacs} to change the global binding of
+@code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a
+hook function to make changes from the current style. @ccmode{}
+itself uses this function when initializing styles.
+@end deffn
+
+@cindex offset specification
+The ``offset specifications'' in @code{c-offsets-alist} can be any of
+the following:
+
+@table @asis
+@item An integer
+The integer specifies a relative offset. All relative
+offsets@footnote{The syntactic context @code{@w{((defun-block-intro
+2724) (comment-intro))}} would likely have two relative offsets.} will
+be added together and used to calculate the indentation relative to an
+anchor position earlier in the buffer. @xref{Indentation
+Calculation}, for details. Most of the time, it's probably better to
+use one of the special symbols like @code{+} than an integer (apart
+from zero).
+
+@item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}
+These special symbols describe a relative offset in multiples of
+@code{c-basic-offset}:
+
+By defining a style's indentation in terms of @code{c-basic-offset},
+you can change the amount of whitespace given to an indentation level
+while maintaining the same basic shape of your code. Here are the
+values that the special symbols correspond to:
+
+@table @code
+@item +
+@code{c-basic-offset} times 1
+@item -
+@code{c-basic-offset} times -1
+@item ++
+@code{c-basic-offset} times 2
+@item --
+@code{c-basic-offset} times -2
+@item *
+@code{c-basic-offset} times 0.5
+@item /
+@code{c-basic-offset} times -0.5
+@end table
+
+@item A vector
+The first element of the vector, an integer, sets the absolute
+indentation column. This will override any previously calculated
+indentation, but won't override relative indentation calculated from
+syntactic elements later on in the syntactic context of the line being
+indented. @xref{Indentation Calculation}. Any elements in the vector
+beyond the first will be ignored.
+
+@item A function or lambda expression
+The function will be called and its return value will in turn be
+evaluated as an offset specification. Functions are useful when more
+context than just the syntactic symbol is needed to get the desired
+indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for
+details about them.
+
+@item A symbol with a variable binding
+If the symbol also has a function binding, the function takes
+precedence over the variable. Otherwise the value of the variable is
+used. It must be an integer (which is used as relative offset) or a
+vector (an absolute offset).
+
+@item A list
+The offset can also be a list containing several offset
+specifications; these are evaluated recursively and combined. A list
+is typically only useful when some of the offsets are line-up
+functions. A common strategy is calling a sequence of functions in
+turn until one of them recognizes that it is appropriate for the
+source line and returns a non-@code{nil} value.
+
+@code{nil} values are always ignored when the offsets are combined.
+The first element of the list specifies the method of combining the
+non-@code{nil} offsets from the remaining elements:
+
+@table @code
+@item first
+Use the first offset that doesn't evaluate to @code{nil}. Subsequent
+elements of the list don't get evaluated.
+@item min
+Use the minimum of all the offsets. All must be either relative or
+absolute - they can't be mixed.
+@item max
+Use the maximum of all the offsets. All must be either relative or
+absolute - they can't be mixed.
+@item add
+Add all the evaluated offsets together. Exactly one of them may be
+absolute, in which case the result is absolute. Any relative offsets
+that preceded the absolute one in the list will be ignored in that case.
+@end table
+
+As a compatibility measure, if the first element is none of the above
+then it too will be taken as an offset specification and the whole list
+will be combined according to the method @code{first}.
+@end table
+
+@vindex c-strict-syntax-p
+@vindex strict-syntax-p (c-)
+If an offset specification evaluates to @code{nil}, then a relative
+offset of 0 (zero) is used@footnote{There is however a variable
+@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
+error to be signaled in that case. It's now considered obsolete since
+it doesn't work well with some of the alignment functions that returns
+@code{nil} instead of zero. You should therefore leave
+@code{c-strict-syntax-p} set to @code{nil}.}.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation
+@comment node-name, next, previous, up
+@section Interactive Customization
+@cindex customization, interactive
+@cindex interactive customization
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+As an example of how to customize indentation, let's change the
+style of this example@footnote{In this and subsequent examples, the
+original code is formatted using the @samp{gnu} style unless otherwise
+indicated. @xref{Styles}.}:
+
+@example
+@group
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+@end group
+@end example
+
+@noindent
+to:
+
+@example
+@group
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+@end group
+@end example
+
+In other words, we want to change the indentation of braces that open a
+block following a condition so that the braces line up under the
+conditional, instead of being indented. Notice that the construct we
+want to change starts on line 4. To change the indentation of a line,
+we need to see which syntactic symbols affect the offset calculations
+for that line. Hitting @kbd{C-c C-s} on line 4 yields:
+
+@example
+((substatement-open 44))
+@end example
+
+@noindent
+so we know that to change the offset of the open brace, we need to
+change the indentation for the @code{substatement-open} syntactic
+symbol.
+
+To do this interactively, just hit @kbd{C-c C-o}. This prompts
+you for the syntactic symbol to change, providing a reasonable default.
+In this case, the default is @code{substatement-open}, which is just the
+syntactic symbol we want to change!
+
+After you hit return, @ccmode{} will then prompt you for the new
+offset value, with the old value as the default. The default in this
+case is @samp{+}, but we want no extra indentation so enter
+@samp{0} and @kbd{RET}. This will associate the offset 0 with the
+syntactic symbol @code{substatement-open}.
+
+To check your changes quickly, just hit @kbd{C-c C-q}
+(@code{c-indent-defun}) to reindent the entire function. The example
+should now look like:
+
+@example
+@group
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+@end group
+@end example
+
+Notice how just changing the open brace offset on line 4 is all we
+needed to do. Since the other affected lines are indented relative to
+line 4, they are automatically indented the way you'd expect. For more
+complicated examples, this might not always work. The general approach
+to take is to always start adjusting offsets for lines higher up in the
+file, then reindent and see if any following lines need further
+adjustments.
+
+@c Move this bit to "Styles" (2005/10/7)
+@deffn Command c-set-offset symbol offset
+@findex set-offset (c-)
+@kindex C-c C-o
+This is the command bound to @kbd{C-c C-o}. It provides a convenient
+way to set offsets on @code{c-offsets-alist} both interactively (see
+the example above) and from your mode hook.
+
+It takes two arguments when used programmatically: @var{symbol} is the
+syntactic element symbol to change and @var{offset} is the new offset
+for that syntactic element.
+@end deffn
+@c End of MOVE THIS BIT.