--- a/man/cc-mode.texi	Mon Aug 13 08:45:53 2007 +0200
+++ b/man/cc-mode.texi	Mon Aug 13 08:46:35 2007 +0200
@@ -17,12 +17,12 @@
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @comment 
 @comment texinfo manual for @file{cc-mode.el} version 4
-@comment manual version: 2.35
+@comment manual version: 2.55
 @comment generated from the original README file by Krishna Padmasola
 @comment <krishna@earth-gw.njit.edu>
 @comment 
 @comment Barry A. Warsaw <bwarsaw@cnri.reston.va.us>
-@comment Last modification: 1996/01/19 20:50:48
+@comment Last modification: 1996/08/21 19:29:16
 @comment 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
@@ -33,7 +33,7 @@
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 @ifinfo
-Copyright @copyright{} 1995 Free Software Foundation, Inc.
+Copyright @copyright{} 1995, 1996 Free Software Foundation, Inc.
 @end ifinfo
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@@ -50,8 +50,8 @@
 
 @center @titlefont{CC-MODE Version 4}
 @sp 2
-@center A GNU Emacs mode for editing C, C++, and Objective-C code.
-@center (manual revision: 2.35)
+@center A GNU Emacs mode for editing C, C++, Objective-C, and Java code.
+@center (manual revision: 2.55)
 @sp 2
 @center Barry A. Warsaw
 
@@ -84,14 +84,13 @@
 * Getting Connected::           
 * New Indentation Engine::
 * Minor Modes::
-* Indentation Commands::
+* Commands::
 * Customizing Indentation::
 * Syntactic Symbols::
 * Performance Issues::
 * Frequently Asked Questions::
 * Getting the latest cc-mode release::
 * Sample .emacs File::
-* Requirements::                
 * Limitations and Known Bugs::  
 * Mailing Lists and Submitting Bug Reports::  
 * Concept Index::               
@@ -123,7 +122,10 @@
 @dfn{ARM} @footnote{i.e. ``The Annotated C++ Reference Manual'', by
 Ellis and Stroustrup.} C++, Objective-C, and Java files.  In this way,
 you can easily set up consistent coding styles for use in editing all C,
-C++, Objective-C, and Java programs.
+C++, Objective-C, and Java programs. @code{cc-mode} does @emph{not}
+handle font-locking (a.k.a. syntax coloring, keyword highlighting) or
+anything of that nature, for any of the 4 modes.  Those are handled by
+other Emacs packages.
 
 This manual will describe the following:
 
@@ -143,34 +145,35 @@
 refer to the package as @code{cc-mode}, but there really is no top level
 @code{cc-mode} entry point.  I call it @code{cc-mode} simply to
 differentiate it from @file{c-mode.el}.  All of the variables, commands,
-and functions in @code{cc-mode} are prefixed with @code{c-<thing>}, and
-@code{c-mode}, @code{c++-mode}, @code{objc-mode}, and @code{java-mode}
-entry points are provided.  This file is intended to be a replacement
-for @file{c-mode.el} and @file{c++-mode.el}.
+and functions in @code{cc-mode} are prefixed with
+@code{c-@var{<thing>}}, and @code{c-mode}, @code{c++-mode},
+@code{objc-mode}, and @code{java-mode} entry points are provided.  This
+file is intended to be a replacement for @file{c-mode.el} and
+@file{c++-mode.el}.
 
 @findex c-version
 The major version number was incremented to 4 with the addition of
 @code{objc-mode}. To find the minor revision number of this release, use
-@kbd{M-x c-version RET}.  Work has already begun on @code{cc-mode}
-version 5, in which Emacs 18 will not be supported.
-
-As of this writing (19-Jan-1996), both Emacs 19.30 and XEmacs 19.13 are
-distributed with @code{cc-mode}.  Emacs 19.31 and XEmacs 19.14 will both
-contain the latest version of cc-mode when it is released.  If you are
-running older versions of these Emacsen, you may want to upgrade your
-copy of @code{cc-mode}.  See @ref{Getting the latest cc-mode release}.
+@kbd{M-x c-version RET}.
+
+As of this writing (20-Aug-1996), both Emacs 19.33 and XEmacs 19.14 are
+distributed with @code{cc-mode}, however neither have the very latest
+version.  In all likelihood, Emacs 19.34 and XEmacs 19.15 will contain
+the latest version of @code{cc-mode}.  You may therefore, want to
+upgrade your copy of @code{cc-mode}.  See @ref{Getting the latest
+cc-mode release}.
 
 @cindex @file{cc-compat.el} file
-This distribution also contains a file called @file{cc-compat.el}
-which should ease your transition from BOCM to @code{cc-mode}.  It
-currently comes unguaranteed and unsupported, but this may change for
-future versions.
+This distribution also contains a file called @file{cc-compat.el} which
+should ease your transition from BOCM to @code{cc-mode}.  It currently
+comes unguaranteed and unsupported, but this may change for future
+versions.  If you have a BOCM configuration you are really happy with,
+and want to postpone learning how to configure @code{cc-mode}, take a
+look at that file.  It maps BOCM configuration variables to
+@code{cc-mode}'s new indentation model.
 
 A special word of thanks goes to Krishna Padmasola for his work in
 converting the original @file{README} file to texinfo format.
-@code{cc-mode} users have been clamoring for a manual for a long time,
-and thanks to Krishna, it is now available <clap> <clap> <clap>!
-@code{:-)}
 
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@@ -183,17 +186,18 @@
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 @file{cc-mode.el} works well with the 2 main branches of Emacs 19:
-XEmacs and the Emacs 19 maintained by the FSF.  Emacs 19 users will want
-to use Emacs version 19.21 or better, XEmacs users will want 19.6 or
-better.  Earlier versions of these Emacsen have deficiencies and/or bugs
-which will adversely affect the performance and usability of
-@code{cc-mode}.
+XEmacs, maintained by @code{xemacs.org} and the Emacs 19 maintained by
+the Free Software Foundation.  Emacs 19 users will want to use Emacs
+version 19.21 or better, XEmacs users will want 19.6 or better.  Earlier
+versions of these Emacsen have deficiencies and/or bugs which will
+adversely affect the performance and usability of @code{cc-mode}.  You
+are better off just getting the latest version of Emacs or XEmacs.
 
 @cindex @file{cc-mode-18.el} file
-Similarly if you use the @file{cc-mode-18.el} compatibility file,
-@file{cc-mode.el} will work with Emacs 18, but only moderately well.  A
+@file{cc-mode.el} will work with Emacs 18 if you use the
+@file{cc-mode-18.el} compatibility file, but only moderately well.  A
 word of warning though, @emph{Emacs 18 lacks some fundamental
-functionality and that ultimately means using Emacs 18 is a losing
+functionality and ultimately, using Emacs 18 is a losing
 battle}.  Hence @code{cc-mode} under Emacs 18 is no longer supported and
 it is highly recommended that you upgrade to Emacs 19.  If you use
 @code{cc-mode} under Emacs 18, you're on your own.  With @code{cc-mode}
@@ -201,7 +205,9 @@
 
 Note that as of XEmacs 19.13 and Emacs 19.30, your Emacs already comes
 with @code{cc-mode} version 4 preconfigured for your use.  You should be
-able to safely skip the rest of the setup information in this chapter.
+able to safely skip the rest of the setup information in this chapter,
+unless you want to install the latest version of @code{cc-mode} into one
+of these Emacsen.
 
 @cindex @file{.emacs} file
 The first thing you will want to do is put @file{cc-mode.el} somewhere
@@ -290,7 +296,7 @@
 @end example
 
 Alternatively, if you want to make sure @code{cc-mode} is loaded when
-Emacs starts up, you could use this line instead of the three autoloads
+Emacs starts up, you could use this line instead of the autoloads
 above:
 @example
 
@@ -299,12 +305,12 @@
 @end example
 
 Next, you will want to set up Emacs so that it edits C files in
-@code{c-mode}, C++ files in @code{c++-mode}, and Objective-C files in
-@code{objc-mode}. All users should add the following to their
-@file{.emacs} file.  Note that this assumes you'll be editing @code{.h}
-and @code{.c} files as C, @code{.hh}, @code{.cc}, @code{.H}, and
-@code{.C} files as C++, @code{.m} files as Objective-C, and @code{.java}
-files as Java code. YMMV:
+@code{c-mode}, C++ files in @code{c++-mode}, Objective-C files in
+@code{objc-mode}, and Java files in @code{java-mode}. You should
+add the following to your @file{.emacs} file, which assumes
+you'll be editing @code{.h} and @code{.c} files as C, @code{.hh},
+@code{.cc}, @code{.H}, and @code{.C} files as C++, @code{.m} files as
+Objective-C, and @code{.java} files as Java code. YMMV:
 @example
 @group
 
@@ -326,7 +332,7 @@
 You may already have some or all of these settings on your
 @code{auto-mode-alist}, but it won't hurt to put them on there again.
 
-That's all you need -- I know, I know, it sounds like a lot @code{:-)},
+That's all you need --- I know, I know, it sounds like a lot @code{:-)},
 but after you've done all this, you should only need to quit and restart
 Emacs.  The next time you visit a C, C++, Objective-C, or Java file you
 should be using @code{cc-mode}.  You can check this easily by hitting
@@ -341,23 +347,16 @@
 @end example
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-@menu
-* Syntactic Analysis::
-* Indentation Calculation::
-@end menu
-
 @node     New Indentation Engine, Minor Modes, Getting Connected, Top
 @comment  node-name,              next,                    previous,up
 
 @chapter  New Indentation Engine
 @cindex   New Indentation Engine
-
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 @code{cc-mode} has a new indentation engine, providing a simplified, yet
 flexible and general mechanism for customizing indentation. It breaks
-indentation calculation into two steps. First for the line of code being
+indentation calculation into two steps. First, for the line of code being
 indented, @code{cc-mode} analyzes what kind of language construct it's
 looking at, then it applies user defined offsets to the current line
 based on this analysis.
@@ -367,12 +366,11 @@
 being used so that you will know how to customize @code{cc-mode} for
 your personal coding style.
 
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @menu
 * Syntactic Analysis::
 * Indentation Calculation::
 @end menu
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node  Syntactic Analysis, Indentation Calculation, , New Indentation Engine
@@ -429,7 +427,10 @@
 We can use the command @kbd{C-c C-s}
 (@code{c-show-syntactic-information}) to simply report what the
 syntactic analysis is for the current line.  Running this command on
-line 4 this example, we'd see in the echo area:
+line 4 this example, we'd see in the echo area@footnote{With a universal
+argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the
+buffer as a comment
+on the current line.}:
 @example
 
 ((statement . 35))
@@ -438,7 +439,7 @@
 
 This tells us that the line is a statement and it is indented relative
 to buffer position 35, which happens to be the @samp{i} in @code{int} on
-line 3.  If you were to move point to line 3 and hit @kbd{C-c C-s}, you
+line 3.  If you were to move Point to line 3 and hit @kbd{C-c C-s}, you
 would see:
 @example
 
@@ -504,7 +505,7 @@
 @end example
 
 @noindent
-Hitting @kbd{C-c C-s} on line 3 of example 3 gives us:
+Hitting @kbd{C-c C-s} on line 3 of this example gives:
 @example
 
 ((comment-intro) (defun-block-intro . 46))
@@ -512,7 +513,7 @@
 @end example
 
 @noindent
-so you can see that the syntactic component list contains two syntactic
+and you can see that the syntactic component list contains two syntactic
 components.  Also notice that the first component,
 @samp{(comment-intro)} has no relative buffer position.
 
@@ -533,7 +534,7 @@
 
 First, the syntactic symbols are looked up in the @code{c-offsets-alist}
 variable, which is an association list of syntactic symbols and the
-offsets to apply for those symbols.  These offsets are added to the
+offsets to apply for those symbols.  These offsets are added to a
 running total.
 
 Second, if the component has a relative buffer position, @code{cc-mode}
@@ -557,7 +558,7 @@
 @end example
 
 @kindex TAB
-Let's say point is on line 3 and we hit the @key{TAB} key to re-indent
+Let's say Point is on line 3 and we hit the @key{TAB} key to re-indent
 the line.  Remember that the syntactic component list for that
 line is:
 @example
@@ -573,7 +574,7 @@
 running total indentation of 4 spaces.
 
 Next @code{cc-mode} goes to buffer position 29 and asks for the current
-column.  Since the brace at buffer position 29 is in column zero, it
+column.  This brace is in column zero, so @code{cc-mode}
 adds @samp{0} to the running total.  Since there is only one syntactic
 component on the list for this line, indentation calculation is
 complete, and the total indentation for the line
@@ -628,7 +629,7 @@
 
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node  Minor Modes, Indentation Commands, New Indentation Engine, Top
+@node  Minor Modes, Commands, New Indentation Engine, Top
 @comment  node-name,              next,                    previous,up
 
 @chapter  Minor Modes
@@ -639,17 +640,16 @@
 find useful while you enter new C code.  The first is called
 @dfn{auto-newline} mode, and the second is called @dfn{hungry-delete}
 mode.  These minor modes can be toggled on and off independently, and
-@code{cc-mode} can be configured so that it comes up with any
+@code{cc-mode} can be configured so that it starts up with any
 combination of these minor modes.  By default, both of these minor modes
 are turned off.
 
 The state of the minor modes is always reflected in the minor mode list
 on the modeline of the @code{cc-mode} buffer.  When auto-newline mode is
 enabled, you will see @samp{C/a} on the mode line @footnote{Remember
-that the @samp{C} would be replaced with @samp{C++} or @samp{ObjC} if
-you were editing C++ or Objective-C code.}.  When hungry delete mode is
-enabled you would see @samp{C/h} and when both modes are enabled, you'd
-see @samp{C/ah}.
+that the @samp{C} could be replaced with @samp{C++}, @samp{ObjC}, or
+@samp{Java}.}.  When hungry delete mode is enabled you would see
+@samp{C/h} and when both modes are enabled, you'd see @samp{C/ah}.
 
 @kindex C-c C-a
 @kindex C-c C-d
@@ -661,12 +661,12 @@
 @findex toggle-auto-state (c-)
 @findex toggle-auto-hungry-state (c-)
 @code{cc-mode} provides keybindings which allow you to toggle the minor
-modes while editing code on the fly.  To toggle just the auto-newline
+modes on the fly while editing code.  To toggle just the auto-newline
 state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}).  When you do
 this, you should see the @samp{a} indicator either appear or disappear
 on the modeline.  Similarly, to toggle just the hungry-delete state, use
-@kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states
-together, use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}).
+@kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states,
+use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}).
 
 To set up the auto-newline and hungry-delete states to your preferred
 values, you would need to add some lisp to your @file{.emacs} file that
@@ -764,7 +764,7 @@
 add various newlines before and/or after the typed brace.
 Re-indentation occurs automatically whenever the electric behavior is
 enabled.  If the brace ends up on a line other than the one it was typed
-on, then that line is on is also indented according to
+on, then that line is also indented according to
 @code{c-offsets-alist}.
 
 @cindex class-open syntactic symbol
@@ -781,6 +781,8 @@
 @cindex block-close syntactic symbol
 @cindex substatement-open syntactic symbol
 @cindex statement-case-open syntactic symbol
+@cindex extern-lang-open syntactic symbol
+@cindex extern-lang-close syntactic symbol
 
 The insertion of newlines is controlled by the
 @code{c-hanging-braces-alist} variable.  This variable contains a
@@ -790,8 +792,10 @@
 @code{defun-close}, @code{inline-open}, @code{inline-close},
 @code{brace-list-open}, @code{brace-list-close},
 @code{brace-list-intro}, @code{brace-list-entry}, @code{block-open},
-@code{block-close}, @code{substatement-open}, and
-@code{statement-case-open}.  @xref{Syntactic Symbols} for a more
+@code{block-close}, @code{substatement-open}, 
+@code{statement-case-open},
+@code{extern-lang-open}, and @code{extern-lang-close}.
+@xref{Syntactic Symbols} for a more
 detailed description of these syntactic symbols.
 
 @cindex custom indentation function
@@ -800,8 +804,8 @@
 @xref{Custom Brace and Colon Hanging} for a more detailed discussion of
 using a function as a brace hanging @var{ACTION}.
 
-When @var{ACTION} is a list, it can contain any combination of the
-symbols @code{before} or @code{after}, directing @code{cc-mode} where to
+When the @var{ACTION} is a list, it can contain any combination of the
+symbols @code{before} and @code{after}, directing @code{cc-mode} where to
 put newlines in relationship to the brace being inserted.  Thus, if the
 list contains only the symbol @code{after}, then the brace is said to
 @dfn{hang} on the right side of the line, as in:
@@ -830,7 +834,8 @@
 
 (defvar c-hanging-braces-alist '((brace-list-open)
                                  (substatement-open after)
-                                 (block-close . c-snug-do-while)))
+                                 (block-close . c-snug-do-while)
+                                 (extern-lang-open after)))
 
 @end group
 @end example
@@ -838,10 +843,10 @@
 @noindent
 which says that @code{brace-list-open} braces should both hang on the
 right side, and allow subsequent text to follow on the same line as the
-brace.  Also, @code{substatement-open} braces should hang on the right
-side, but subsequent text should follow on the next line.  Here, in the
-@code{block-close} entry, you also see an example of using a function as
-an @var{ACTION}.
+brace.  Also, @code{substatement-open} and @code{extern-lang-open}
+braces should hang on the right side, but subsequent text should follow
+on the next line.  Here, in the @code{block-close} entry, you also see
+an example of using a function as an @var{ACTION}.
 
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@@ -859,9 +864,9 @@
 @code{c-hanging-colons-alist}.  The syntactic symbols appropriate for
 this assocation list are: @code{case-label}, @code{label},
 @code{access-label}, @code{member-init-intro}, and @code{inher-intro}.
-@xref{Hanging Braces} and @ref{Custom Brace and Colon Hanging} for
-details.  Note however, that @code{c-hanging-colons-alist} does not
-implement functions as @var{ACTION}s.
+Note however, that for @code{c-hanging-colons-alist} @var{ACTION}s as
+functions are not supported. See also @ref{Custom Brace and Colon
+Hanging} for details.
 
 @cindex clean-ups
 In C++, double-colons are used as a scope operator but because these
@@ -900,8 +905,8 @@
 @vindex electric-pound-behavior (c-)
 @vindex c-offsets-alist
 @vindex offsets-alist (c-)
-A few other keys also provide electric behavior.  For example the
-@kbd{#} key (@code{c-electric-pound}) is electric when it is typed as
+A few other keys also provide electric behavior.  For example
+@kbd{#} (@code{c-electric-pound}) is electric when typed as
 the first non-whitespace character on a line.  In this case, the
 variable @code{c-electric-pound-behavior} is consulted for the electric
 behavior.  This variable takes a list value, although the only element
@@ -914,7 +919,8 @@
 @findex electric-star (c-)
 @findex electric-slash (c-)
 @cindex comment-only line
-Stars and slashes (i.e. @kbd{*} and @kbd{/}) are also electric under
+Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and
+@code{c-electric-slash} respectively) are also electric under
 certain circumstances.  If a star is inserted as the second character of
 a C style block comment on a @dfn{comment-only} line, then the comment
 delimiter is indented as defined by @code{c-offsets-alist}.  A
@@ -939,6 +945,14 @@
 comment (also only on a comment-only line), then the line is indented as
 defined by @code{c-offsets-alist}.
 
+@findex c-electric-lt-gt
+@findex electric-lt-gt (c-)
+@kindex <
+@kindex >
+Less-than and greater-than signs (@code{c-electric-lt-gt}) are also
+electric, but only in C++ mode.  Hitting the second of two @kbd{<} or
+@kbd{>} keys re-indents the line if it is a C++ style stream operator.
+
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node  Clean-ups, , Other electric commands, Auto-newline insertion
@@ -972,7 +986,7 @@
 
 @itemize @bullet
 @item
-@code{brace-else-brace} -- cleans up @samp{@} else @{} constructs by
+@code{brace-else-brace} --- cleans up @samp{@} else @{} constructs by
 placing the entire construct on a single line.  Clean-up occurs when the
 open brace after the @samp{else} is typed.  So for example, this:
 @example
@@ -1004,7 +1018,7 @@
 @end example
 
 @item
-@code{empty-defun-braces} -- cleans up braces following a top-level
+@code{empty-defun-braces} --- cleans up braces following a top-level
 function or class definition that contains no body.  Clean up occurs
 when the closing brace is typed.  Thus the following:
 @example
@@ -1028,7 +1042,7 @@
 @end example
 
 @item
-@code{defun-close-semi} -- cleans up the terminating semi-colon on
+@code{defun-close-semi} --- cleans up the terminating semi-colon on
 top-level function or class definitions when they follow a close
 brace. Clean up occurs when the semi-colon is typed.
 So for example, the following:
@@ -1056,11 +1070,11 @@
 @end example
 
 @item
-@code{list-close-comma} -- cleans up commas following braces in array
+@code{list-close-comma} --- cleans up commas following braces in array
 and aggregate initializers.  Clean up occurs when the comma is typed.
 
 @item
-@code{scope-operator} -- cleans up double colons which may designate a
+@code{scope-operator} --- cleans up double colons which may designate a
 C++ scope operator split across multiple lines@footnote{Certain C++
 constructs introduce ambiguous situations, so @code{scope-operator}
 clean-ups may not always be correct.  This usually only occurs when
@@ -1108,19 +1122,32 @@
 
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node  Indentation Commands, Customizing Indentation, Minor Modes, Top
+@node  Commands, Customizing Indentation, Minor Modes, Top
 @comment  node-name,              next,                    previous,up
 
-@chapter  Indentation Commands
+@chapter  Commands
+@cindex   Commands
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@menu
+* Indentation Commands::
+* Other Commands::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node  Indentation Commands, Other Commands, , Commands
+@comment  node-name,              next,                    previous,up
+
+@section  Indentation Commands
 @cindex   Indentation Commands
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 @findex c-set-style
 @findex set-style (c-)
 Various commands are provided which allow you to conveniently re-indent
-C constructs, and these are outlined below.  There are several things to
+C constructs.  There are several things to
 note about these indentation commands.  First, when you
-change your programming style, either though @code{c-set-style} or some
+change your programming style, either interactively or through some
 other means, your file does @emph{not} automatically get re-indented.
 When you change style parameters, you will typically need to reformat
 the line, expression, or buffer to see the effects of your changes.
@@ -1129,26 +1156,25 @@
 @findex c-hanging-braces-alist
 @findex hanging-braces-alist (c-)
 Second, changing some variables have no effect on existing code, even
-when you do re-indent.  For example, the @code{c-hanging-*} variables and
-@code{c-cleanup-list} only affect newly entered code.  So for example,
-changing @code{c-hanging-braces-alist} and re-indenting the buffer will
-not adjust placement of braces already in the file.
+when you do re-indent.  For example, the @code{c-hanging-*} variables
+and @code{c-cleanup-list} only affect new code as it is typed in.  So
+for example, changing @code{c-hanging-braces-alist} and re-indenting the
+buffer will not adjust placement of braces already in the file.
 
 @vindex c-progress-interval
 @vindex progress-interval (c-)
 Third, re-indenting large portions of code is currently rather
 inefficient.  Improvements have been made since previous releases of
-@code{cc-mode}, and much more radical improvements will be made for the
-next release, but for now you need to be aware of this @footnote{In
-particular, I have had people complain about the speed that
-@code{cc-mode} re-indents @code{lex(1)} output.  Lex, yacc, and other
-code generators usually output some pretty perverse code.  @emph{Don't}
-try to indent this stuff with @code{cc-mode}!}.  Some provision has been
-made to at least inform you as to the progress of your large
-re-indentation command.  The variable @code{c-progress-interval}
-controls how often a progress message is displayed.  Set this variable
-to @code{nil} to inhibit progress messages.  Note that this feature only
-works with Emacs 19.
+@code{cc-mode}, and much more radical improvements are planned, but for
+now you need to be aware of this @footnote{In particular, I have had
+people complain about the speed that @code{cc-mode} re-indents
+@code{lex(1)} output.  Lex, yacc, and other code generators usually
+output some pretty perversely formatted code.  @emph{Don't} try to
+indent this stuff with @code{cc-mode}!}.  Some provision has been made
+to at least inform you as to the progress of the re-indentation.  The
+variable @code{c-progress-interval} controls how often a progress
+message is displayed.  Set this variable to @code{nil} to inhibit
+progress messages.  Note that this feature only works with Emacs 19.
 
 Also, except as noted below, re-indentation is always driven by the
 same mechanisms that control on-the-fly indentation of code.  @xref{New
@@ -1160,23 +1186,34 @@
 @vindex tab-always-indent (c-)
 @kindex TAB
 @cindex literal
+@vindex indent-tabs-mode
+@vindex c-insert-tab-function
+@vindex insert-tab-function (c-)
+@findex tab-to-tab-stop
 To indent a single line of code, use @kbd{TAB}
 (@code{c-indent-command}).  The behavior of this command is controlled
 by the variable @code{c-tab-always-indent}.  When this variable is
 @code{t}, @kbd{TAB} always just indents the current line.  When
-@code{nil}, the line is indented only if point is at the left
-margin, or on or before the first non-whitespace character on the line,
-otherwise a real tab character is inserted.  If this variable's value is
-something other that @code{t} or @code{nil} (e.g. @code{'other}), then a
-real tab character is inserted only when point is inside a
-literal (see @ref{Auto-newline insertion}), otherwise the line is
-indented.
+@code{nil}, the line is indented only if Point is at the left margin, or
+on or before the first non-whitespace character on the line, otherwise
+@emph{something else happens}@footnote{Actually what happens is that the
+function stored in the variable @code{c-insert-tab-function} is called.
+Normally this just inserts a real tab character, or the equivalent
+number of spaces, depending on the setting of the variable
+@code{indent-tabs-mode}.  If you preferred, you could set
+@code{c-insert-tab-function} to @code{tab-to-tab-stop} for example.}.
+If the value of @code{c-tab-always-indent} is something other than
+@code{t} or @code{nil} (e.g. @code{'other}), then a real tab
+character@footnote{The caveat about @code{indent-tabs-mode} in the
+previous footnote also applies here.}  is inserted only when Point is
+inside a literal (see @ref{Auto-newline insertion}), otherwise the line
+is indented.
 
 @kindex M-C-q
 @findex c-indent-exp
 @findex indent-exp (c-)
 To indent an entire balanced brace or parenthesis expression, use
-@kbd{M-C-q} (@code{c-indent-exp}).  Note that point should be on
+@kbd{M-C-q} (@code{c-indent-exp}).  Note that Point should be on
 the opening brace or parenthesis of the expression you want to indent.
 
 @kindex C-c C-q
@@ -1184,7 +1221,7 @@
 @findex indent-defun (c-)
 Another very convenient keystroke is @kbd{C-c C-q}
 (@code{c-indent-defun}) when re-indents the entire top-level function or
-class definition that encompases point.  It leaves point at the
+class definition that encompases Point.  It leaves Point at the
 same position within the buffer.
 
 @kindex M-C-\
@@ -1192,7 +1229,7 @@
 To indent any arbitrary region of code, use @kbd{M-C-\}
 (@code{indent-region}).   This is a standard Emacs command, specially
 tailored for C code in a @code{cc-mode} buffer.  Note that of course,
-point and mark must delineate the region you
+Point and Mark must delineate the region you
 want to indent.
 
 @kindex M-C-h
@@ -1202,9 +1239,108 @@
 (@code{c-mark-function}) is useful for marking the current top-level
 function or class definition as the current region.
 
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node  Other Commands, , Indentation Commands, Commands
+@comment  node-name,              next,                    previous,up
+
+@section  Other Commands
+@cindex   Other Commands
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@code{cc-mode} contains other useful command for moving around in C
+code.
+
+@table @code
+@item C-c C-u (c-up-conditional)
+@kindex C-c C-u
+@findex c-up-conditional
+@findex up-conditional (c-)
+Move Point back to the containing preprocessor conditional, leaving the
+Mark behind.  A prefix argument acts as a repeat count.  With a negative
+argument, move Point forward to the end of the containing
+preprocessor conditional.  When going backwards, @code{#elif} is treated
+like @code{#else} followed by @code{#if}.  When going forwards,
+@code{#elif} is ignored.@refill
+
+@item C-c C-p (c-backward-conditional)
+@kindex C-c C-p
+@findex c-backward-conditional
+@findex backward-conditional (c-)
+Move Point back over a preprocessor conditional, leaving Mark
+behind.  A prefix argument acts as a repeat count.  With a negative
+argument, move forward.
+
+@item C-c C-n (c-forward-conditional)
+@kindex C-c C-n
+@findex c-forward-conditional
+@findex forward-conditional (c-)
+Move Point forward across a preprocessor conditional, leaving Mark
+behind.  A prefix argument acts as a repeat count.  With a negative
+argument, move backward.
+
+@item M-a (c-beginning-of-statement)
+@kindex ESC a
+@findex c-beginning-of-statement
+@findex beginning-of-statement (c-)
+Move Point to the beginning of the innermost C statement.  If Point is
+already at the beginning of a statement, it moves to the beginning of
+the preceding statement.  With prefix argument @var{n}, move back
+@var{n} @minus{} 1 statements.
+
+If Point is within a string or comment, or next to a comment (only
+whitespace between them), this command moves by sentences instead of
+statements.
+
+When called from a program, this function takes two optional arguments:
+the numeric prefix argument, and a buffer position limit (don't move
+back before that place).
+
+@item M-e (c-end-of-statement)
+@kindex ESC e
+@findex c-end-of-statement
+@findex end-of-statement (c-)
+Move Point to the end of the innermost C statement.  If Point is at the
+end of a statement, move to the end of the next statement.  With prefix
+argument @var{n}, move forward @var{n} @minus{} 1 statements.
+
+If Point is within a string or comment, or next to a comment (only
+whitespace between them), this command moves by sentences instead of
+statements.
+
+When called from a program, this function takes two optional arguments:
+the numeric prefix argument, and a buffer position limit (don't move
+past that place).
+
+@item M-x c-forward-into-nomenclature
+@findex c-forward-into-nomenclature
+@findex forward-into-nomenclature (c-)
+A popular programming style, especially for object-oriented languages
+such as C++ is to write symbols in a mixed case format, where the first
+letter of each word is capitalized, and not separated by underscores.
+E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}.
+
+This command moves Point forward to end of a C++ nomenclature
+section or word.  With prefix argument @var{n}, move @var{n} times.
+
+@item M-x c-backward-into-nomenclature
+@findex c-backward-into-nomenclature
+@findex backward-into-nomenclature (c-)
+Move Point backward to beginning of a C++ nomenclature
+section or word.  With prefix argument @var{n}, move @var{n} times.  If
+@var{n} is negative, move forward.
+
+@kindex C-c :
+@findex c-scope-operator
+@findex scope-operator (c-)
+@item C-c : (c-scope-operator)
+In C++, it is also sometimes desirable to insert the double-colon scope
+operator without performing the electric behavior of colon insertion.
+@kbd{C-c :} does just this.
+
+@end table
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node     Customizing Indentation, Syntactic Symbols, Indentation Commands, Top
+@node     Customizing Indentation, Syntactic Symbols, Commands, Top
 @comment  node-name,              next,                    previous,up
 
 @chapter  Customizing Indentation
@@ -1226,33 +1362,33 @@
 @cindex c-basic-offset
 @cindex basic-offset (c-)
 As mentioned previously, the variable @code{c-offsets-alist} is an
-association list between syntactic symbols and the offsets to be applied
-for those symbols.  In fact, these offset values can be an integer, a
-function or variable name, or one of the following symbols: @code{+},
+association list of syntactic symbols and the offsets to be applied for
+those symbols.  In fact, these offset values can be any of an integer,
+a function or variable name, or one of the following symbols: @code{+},
 @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}.  These symbols
 describe offset in multiples of the value of the variable
 @code{c-basic-offset}.  By defining a style's indentation in terms of
 this fundamental variable, you can change the amount of whitespace given
 to an indentation level while leaving the same relationship between
-levels.  Here are multiples of @code{c-basic-offset} that the special
+levels.  Here are the values that the special
 symbols correspond to:
 
-@itemize @bullet
-
-@item
-@code{+ } =  @code{c-basic-offset} times 1
-@item
-@code{- } =  @code{c-basic-offset} times -1
-@item
-@code{++} =  @code{c-basic-offset} times 2
-@item
-@code{--} =  @code{c-basic-offset} times -2
-@item
-@code{* } =  @code{c-basic-offset} times 0.5
-@item
-@code{/ } =  @code{c-basic-offset} times -0.5
-
-@end itemize
+@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
 
 @noindent
 So, for example, because most of the default offsets are defined in
@@ -1278,6 +1414,22 @@
 
 int add( int val, int incr, int doit )
 @{
+  if( doit )
+    @{
+      return( val + incr );
+    @}
+  return( val );
+@}
+
+@end group
+@end example
+@noindent
+to
+@example
+@group
+
+int add( int val, int incr, int doit )
+@{
     if( doit )
         @{
             return( val + incr );
@@ -1288,22 +1440,6 @@
 @end group
 @end example
 
-@noindent
-to
-@example
-@group
-
-int add( int val, int incr, int doit )
-@{
-  if( doit )
-    @{
-      return( val + incr );
-    @}
-  return( val );
-@}
-
-@end group
-@end example
 
 To change indentation styles more radically, you will want to change the
 value associated with the syntactic symbols in the
@@ -1327,17 +1463,19 @@
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 As an example of how to customize indentation, let's change the
-style of example 2 above from:
+style of this example@footnote{In this an 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 );
+3:   if( doit )
+4:     @{
+5:       return( val + incr );
+6:     @}
+7:   return( val );
 8: @}
 
 @end group
@@ -1349,11 +1487,11 @@
 
 1: int add( int val, int incr, int doit )
 2: @{
-3:     if( doit )
-4:     @{
-5:         return( val + incr );
-6:     @}
-7:     return( val );
+3:   if( doit )
+4:   @{
+5:     return( val + incr );
+6:   @}
+7:   return( val );
 8: @}
 
 @end group
@@ -1363,11 +1501,11 @@
 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 component affect the offset calculations
+we need to see which syntactic components affect the offset calculations
 for that line.  Hitting @kbd{C-c C-s} on line 4 yields:
 @example
 
-((substatement-open . 46))
+((substatement-open . 44))
 
 @end example
 
@@ -1385,7 +1523,7 @@
 
 After you hit return, @code{cc-mode} will then prompt you for the new
 offset value, with the old value as the default.  The default in this
-case is @samp{+}, so hit backspace to delete the @samp{+}, then hit
+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} in the @code{c-offsets-alist}
 variable.
@@ -1401,11 +1539,11 @@
 
 1: int add( int val, int incr, int doit )
 2: @{
-3:     if( doit )
-4:     @{
-5:         return( val + incr );
-6:     @}
-7:     return( val );
+3:   if( doit )
+4:   @{
+5:     return( val + incr );
+6:   @}
+7:   return( val );
 8: @}
 
 @end group
@@ -1434,18 +1572,37 @@
 @vindex java-mode-hook
 @cindex hooks
 To make this change permanent, you need to add some lisp code to your
-@file{.emacs} file.  @code{cc-mode} provides four hooks that you can use
-to customize your language editing styles.  Four language specific hooks
-are provided, according to Emacs major mode conventions:
-@code{c-mode-hook}, @code{c++-mode-hook}, @code{objc-mode-hook}, and
-@code{java-mode-hook}.  These get run as the last thing when you enter
-@code{c-mode}, @code{c++-mode}, @code{objc-mode}, or
-@code{java-mode-hook} respectively.  @code{cc-mode} also provides a hook
-called @code{c-mode-common-hook} which is run by all three modes
-@emph{before} the language specific hook.  Thus, to make changes
-consistently across all supported @code{cc-mode} modes, use
-@code{c-mode-common-hook}.  Most of the examples in this section will
-assume you are using the common hook.
+@file{.emacs} file.  @code{cc-mode} provides several hooks that you can
+use to customize the mode according to your coding style.  Each language
+mode has its own hook, adhering to standard to Emacs major mode
+conventions.  There is also one general hook:
+
+@itemize @bullet
+
+@item
+@code{c-mode-hook} --- for C buffers only
+@item
+@code{c++-mode-hook} --- for C++ buffers only
+@item
+@code{objc-mode-hook} --- for Objective-C buffers only
+@item
+@code{java-mode-hook} --- for Java buffers only
+@item
+@code{c-mode-common-hook} --- common across all languages
+
+@end itemize
+
+The language hooks get run as the last thing when you enter that
+language-specific mode.  The @code{c-mode-common-hook} is run by all
+supported modes @emph{before} the language specific hook, and thus can
+contain customizations that are common across all languages.  Most of
+the examples in this section will assume you are using the common
+hook@footnote{The interaction between @code{java-mode} and the hook
+variables is slightly different than for the other modes.
+@code{java-mode} sets the style (see @ref{Styles}) of the buffer to
+@samp{java} @emph{before} running the @code{c-mode-common-hook} or
+@code{java-mode-hook}.  You need to be aware of this so any style
+settings in @code{c-mode-common-hook} doesn't clobber your Java style.}.
 
 Here's a simplified example of what you can add to your @file{.emacs}
 file to make the changes described in the previous section
@@ -1471,10 +1628,6 @@
 @emph{style} that groups all your customizations under a single
 name.
 
-The offset value can also be a function, and this is how power users
-gain enormous flexibility in customizing indentation. @xref{Advanced
-Customizations} for details.
-
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node     Styles, Advanced Customizations, Permanent Customization, Customizing Indentation
 @comment  node-name,              next,                    previous,up
@@ -1492,7 +1645,7 @@
 styles in use.  For this reason, @code{cc-mode} makes it convenient for
 you to set up logical groupings of customizations called @dfn{styles},
 associate a single name for any particular style, and pretty easily
-start editing new or existing code using these styles.  This chapter
+start editing new or existing code using these styles.  This section
 describes how to set up styles and how to edit your C code using styles.
 
 @menu
@@ -1517,30 +1670,29 @@
 @itemize @bullet
 @item
 @cindex GNU style
-@code{gnu} -- coding style blessed by the Free Software Foundation
+@code{gnu} --- coding style blessed by the Free Software Foundation
 for C code in GNU programs.
 
 @item
 @cindex K&R style
-@code{k&r} -- The classic Kernighan and Ritchie style for C code.
+@code{k&r} --- The classic Kernighan and Ritchie style for C code.
 
 @item
 @cindex BSD style
-@code{bsd} -- @strong{<TBD> Anybody know anything about the history of
-this style?}
+@code{bsd} --- Also known as ``Allman style'' after Eric Allman.
+
+@item
+@cindex Whitesmith style
+@code{whitesmith} --- Popularized by the examples that came with
+Whitesmiths C, an early commercial C compiler.
 
 @item
 @cindex Stroustrup style
-@code{stroustrup} -- The classic Stroustrup style for C++ code.
-
-@item
-@cindex Whitesmith style
-@code{whitesmith} -- @strong{<TBD> Anybody know anything about the history of
-this style?}
+@code{stroustrup} --- The classic Stroustrup style for C++ code.
 
 @item
 @cindex Ellemtel style
-@code{ellemtel} -- Popular C++ coding standards as defined by
+@code{ellemtel} --- Popular C++ coding standards as defined by
 ``Programming in C++, Rules and Recommendations'', Erik Nyquist and Mats
 Henricson, Ellemtel @footnote{This document is ftp'able from
 @code{euagate.eua.ericsson.se}}.
@@ -1548,14 +1700,9 @@
 @item
 @cindex Java style
 @cindex java-mode
-@code{java} -- The style for editing Java code.  Note that this style is
+@code{java} --- The style for editing Java code.  Note that this style is
 automatically installed when you enter @code{java-mode}.
 
-@item
-@cindex CC-MODE style
-@code{CC-MODE} -- Style that encapsulates the default values of the
-@code{cc-mode} variables.  See below for details.
-
 @end itemize
 
 @findex c-set-style
@@ -1574,17 +1721,17 @@
 
 Setting a style in this way does @emph{not} automatically re-indent your
 file.  For commands that you can use to view the effect of your changes,
-see @ref{Indentation Commands}.
+see @ref{Commands}.
 
 Once you find a built-in style you like, you can make the change
 permanent by adding a call to your @file{.emacs} file.  Let's say for
-example that you want to use the @code{ellemtel} style in all your
+example that you want to use the @samp{ellemtel} style in all your
 files.  You would add this:
 @example
 @group
 
 (defun my-c-mode-common-hook ()
-  ;; use Ellemtel style for all C, C++, and Objective-C code
+  ;; use Ellemtel style for all C like languages
   (c-set-style "ellemtel")
   ;; other customizations can go here
   )
@@ -1593,18 +1740,18 @@
 @end group
 @end example
 
-There is one other special style you can use, called @code{CC-MODE}.
-This is a style that is calculated by @code{cc-mode} when it starts up.
-The @code{CC-MODE} style is also special because all other styles
-implicitly inherit from it; in other words, whenever you set a style,
-@code{cc-mode} first re-instates the @code{CC-MODE} style, then applies
-your new style configurations.
-
-The @code{CC-MODE} style exists because once @code{cc-mode} initializes,
-it institutes the @code{gnu} style for compatibility with BOCM's
-defaults.  Any customizations you make in mode hooks will be based on
-the @code{gnu} style, unless you first do a @code{c-set-style} to
-@code{CC-MODE} or some other built-in style.
+There is one other special style you can use, called @samp{cc-mode}
+style.  This style is special because all other styles implicitly
+inherit from it; in other words, whenever you set a style,
+@samp{cc-mode} is applied before the one you selected.  This means
+your style need only define the differences between it and
+@samp{cc-mode} style.
+
+Note that for BOCM compatibility, @samp{gnu} is the default
+style, and any non-style based customizations you make (i.e. in
+@code{c-mode-common-hook} in your
+@file{.emacs} file) will be based on @samp{gnu} style unless you do
+a @code{c-set-style} as the first thing in your hook.
 
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@@ -1620,17 +1767,18 @@
 @findex c-add-style
 @findex add-style (c-)
 If none of the built-in styles is appropriate, you'll probably want to
-add a new style definition.  Styles are kept in the @code{c-style-alist}
-variable, but you probably won't want to modify this variable directly.
-@code{cc-mode} provides a function, called @code{c-add-style}, that you
-can use to easily add new styles or update existing styles.  This
-function takes two arguments, a @var{stylename} string, and an
-association list @var{description} of style customizations.  If
-@var{stylename} is not already in @code{c-style-alist}, the new style is
-added, otherwise the style already associated with @var{stylename} is
-changed to the new @var{description}.  This function also takes an
-optional third argument, which if non-@code{nil}, automatically
-institutes the new style in the current buffer.
+add a new @dfn{style definition}.  Styles are kept in the
+@code{c-style-alist} variable, but you should never modify this variable
+directly.  Instead, @code{cc-mode} provides the function
+@code{c-add-style} that you can use to easily add new styles or change
+existing styles.  This function takes two arguments, a @var{stylename}
+string, and an association list @var{description} of style
+customizations.  If @var{stylename} is not already in
+@code{c-style-alist}, the new style is added, otherwise the style is
+changed to the new @var{description}.
+This function also takes an optional third argument, which if
+non-@code{nil}, automatically applies the new style to the current
+buffer.
 
 The sample @file{.emacs} file provides a concrete example of how a new
 style can be added and automatically set.  @xref{Sample .emacs File}.
@@ -1656,10 +1804,9 @@
 @vindex c-file-offsets
 @vindex file-offsets (c-)
 
-The variable @code{c-file-style} can be set to a style name string as
-described in @ref{Built-in Styles}.  When the file is visited,
-@code{cc-mode} will automatically set the file's style to this style
-using @code{c-set-style}.
+The variable @code{c-file-style} can be set to a style name string.
+When the file is visited, @code{cc-mode} will automatically set the
+file's style to this style using @code{c-set-style}.
 
 @vindex c-offsets-alist
 @vindex offsets-alist (c-)
@@ -1671,7 +1818,9 @@
 @code{c-set-offset}.
 
 Note that file style settings (i.e. @code{c-file-style}) are applied
-before file offset settings (i.e. @code{c-file-offsets}).
+before file offset settings (i.e. @code{c-file-offsets})@footnote{File
+styles are only supported since XEmacs 19.12 and Emacs 19.29.  They work
+via the standard Emacs hook variable @code{hack-local-variables-hook}.}.
 
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@@ -1687,15 +1836,15 @@
 @vindex c-basic-offset
 @vindex basic-offset (c-)
 For most users, @code{cc-mode} will support their coding styles with
-very little need for customizations.  Usually, one of the standard
-styles defined in @code{c-style-alist} will do the trick.  At most,
-perhaps one of the syntactic symbol offsets will need to be tweaked
-slightly, or maybe @code{c-basic-offset} will need to be changed.
-However, some styles require a more advanced ability for customization,
-and one of the real strengths of @code{cc-mode} is that the syntactic
-analysis model provides a very flexible framework for customizing
-indentation. This allows you to perform special indentation calculations
-for situations not handled by the mode directly.
+very little need for more advanced customizations.  Usually, one of the
+standard styles defined in @code{c-style-alist} will do the trick.  At
+most, perhaps one of the syntactic symbol offsets will need to be
+tweaked slightly, or maybe @code{c-basic-offset} will need to be
+changed.  However, some styles require a more flexible framework for
+customization, and one of the real strengths of @code{cc-mode} is that
+the syntactic analysis model provides just such a framework. This allows
+you to implement special indentation calculations for situations not
+handled by the mode directly.
 
 @menu
 * Custom Indentation Functions::
@@ -1733,14 +1882,14 @@
 @end example
 
 In this example, lines 4 through 6 are assigned the @code{stream-op}
-syntactic symbol.  If @code{stream-op} had an offset of @code{+}, and
-@code{c-basic-offset} was 2, lines 4 through 6 would simply be indented
-two spaces to the right of line 3.  But perhaps we'd like @code{cc-mode}
-to be a little more intelligent so that it offsets the stream operators
-under the operator in line 3.  To do this, we have to write a custom
-indentation function which finds the column of first stream operator on
-the first line of the statement.  Here is the lisp code (from the
-@file{cc-mode.el} source file) that implements this:
+syntactic symbol.  Here, @code{stream-op} has an offset of @code{+}, and
+with a @code{c-basic-offset} of 2, you can see that lines 4 through 6
+are simply indented two spaces to the right of line 3.  But perhaps we'd
+like @code{cc-mode} to be a little more intelligent so that it lines up
+all the @samp{<<} symbols in lines 3 through 6.  To do this, we have
+to write a custom indentation function which finds the column of first
+stream operator on the first line of the statement.  Here is the lisp
+code (from the @file{cc-mode.el} source file) that implements this:
 @example
 @group
 
@@ -1760,7 +1909,7 @@
 Custom indent functions take a single argument, which is a syntactic
 component cons cell (see @ref{Syntactic Analysis}).  The
 function returns an integer offset value that will be added to the
-running total indentation for the lne.  Note that what actually gets
+running total indentation for the line.  Note that what actually gets
 returned is the difference between the column that the first stream
 operator is on, and the column of the buffer relative position passed in
 the function's argument.  Remember that @code{cc-mode} automatically
@@ -1802,7 +1951,90 @@
 @vindex offsets-alist (c-)
 Custom indentation functions can be as simple or as complex as you like,
 and any syntactic symbol that appears in @code{c-offsets-alist} can have
-a custom indentation function associated with it.
+a custom indentation function associated with it.  @code{cc-mode} comes
+with several standard custom indentation functions, not all of which are
+used by the default styles.
+
+@itemize @bullet
+@item
+@findex c-lineup-arglist
+@findex lineup-arglist (c-)
+@code{c-lineup-arglist} --- lines up function argument lines under the
+argument on the previous line.
+
+@item
+@findex c-lineup-arglist-intro-after-paren
+@findex lineup-arglist-intro-after-paren (c-)
+@code{c-lineup-arglist-intro-after-paren} --- similar to
+@code{c-lineup-arglist}, but works for argument lists that begin with an
+open parenthesis followed by a newline.
+
+@item
+@findex c-lineup-arglist-close-under-paren
+@findex lineup-arglist-close-under-paren (c-)
+@code{c-lineup-arglist-close-under-paren} --- set your
+@code{arglist-close} syntactic symbol to this line-up function so that
+parentheses that close argument lists will line up under the parenthesis
+that opened the argument list.
+
+@item
+@findex c-lineup-streamop
+@findex lineup-streamop (c-)
+@code{c-lineup-streamop} --- lines up C++ stream operators
+(e.g. @samp{<<} and @samp{>>}).
+
+@item
+@findex c-lineup-multi-inher
+@findex lineup-multi-inher (c-)
+@code{c-lineup-multi-inher} --- lines up multiple inheritance lines.
+
+@item
+@findex c-lineup-C-comments
+@findex lineup-C-comments (c-)
+@code{c-lineup-C-comments} --- lines up C block comment continuation
+lines.
+
+@item
+@findex c-lineup-comment
+@findex lineup-comment (c-)
+@vindex c-comment-only-line-offset
+@vindex comment-only-line-offset (c-)
+@code{c-lineup-comment} --- implements the old comment line up behavior
+specified by the variable @code{c-comment-only-line-offset}.
+
+@item
+@findex c-lineup-runin-statements
+@findex lineup-runin-statements (c-)
+@code{c-lineup-runin-statements} --- lines up @code{statement}s for coding
+standards which place the first statement in a block on the same line as
+the block opening brace.
+
+@item
+@findex c-lineup-math
+@findex lineup-math (c-)
+@code{c-lineup-math} --- lines up math @code{statement-cont} lines under
+the previous line after the equals sign.
+
+@item
+@findex c-lineup-ObjC-method-call
+@findex lineup-ObjC-method-call (c-)
+@code{c-lineup-ObjC-method-call} --- for Objective-C code, lines up
+selector arguments just after the message receiver.
+
+@item
+@findex c-lineup-ObjC-method-args
+@findex lineup-ObjC-method-args (c-)
+@code{c-lineup-ObjC-method-args} --- for Objective-C code, lines up the
+colons that separate arguments by aligning colons vertically.
+
+@item
+@findex c-lineup-ObjC-method-args-2
+@findex lineup-ObjC-method-args-2 (c-)
+@code{c-lineup-ObjC-method-args-2} --- similar to
+@code{c-lineup-ObjC-method-args} but lines up the colon on the current
+line with the colon on the previous line.
+
+@end itemize
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node     Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations
@@ -1816,7 +2048,7 @@
 @vindex hanging-braces-alist (c-)
 Syntactic symbols aren't the only place where you can customize
 @code{cc-mode} with the lisp equivalent of callback functions.  Brace
-hanginess can also be determined by custom functions associated with
+``hanginess'' can also be determined by custom functions associated with
 syntactic symbols on the @code{c-hanging-braces-alist} variable.
 Remember that @var{ACTION}'s are typically a list containing some
 combination of the symbols @code{before} and @code{after} (see
@@ -1830,10 +2062,10 @@
 brace was inserted.  The @var{ACTION} function is expected to return a
 list containing some combination of @code{before} and @code{after}.  The
 function can also return @code{nil}.  This return value has the normal
-brace hanging semantics described in @ref{Hanging Braces}.
+brace hanging semantics.
 
 As an example, @code{cc-mode} itself uses this feature to dynamically
-determine the hanginess of braces which close @samp{do-while}
+determine the hanginess of braces which close ``do-while''
 constructs:
 @example
 @group
@@ -1842,7 +2074,7 @@
 @{
     int i=0;
     do @{
-        handle_string( atleast_one_string( i ));
+        handle_string( atleast_one_string[i] );
         i++;
     @} while( i < count );
 @}
@@ -1855,7 +2087,7 @@
 @code{cc-mode} assigns the @code{block-close} syntactic symbol to the
 brace that closes the @code{do} construct, and normally we'd like the
 line that follows a @code{block-close} brace to begin on a separate
-line.  However, with @samp{do-while} constructs, we want the
+line.  However, with ``do-while'' constructs, we want the
 @code{while} clause to follow the closing brace.  To do this, we
 associate the @code{block-close} symbol with the @var{ACTION} function
 @code{c-snug-do-while}:
@@ -1881,10 +2113,10 @@
 
 @end example
 
-This function simply looks to see if the brace closes a @samp{do-while}
-clause and if so, returns the list @samp{@code{(before)}} indicating
+This function simply looks to see if the brace closes a ``do-while''
+clause and if so, returns the list @samp{(before)} indicating
 that a newline should be inserted before the brace, but not after it.
-In all other cases, it returns the list @samp{@code{(before after)}} so
+In all other cases, it returns the list @samp{(before after)} so
 that the brace appears on a line by itself.
 
 @vindex c-syntactic-context
@@ -1920,15 +2152,15 @@
 
 @itemize @bullet
 @item
-non-@code{nil} -- A newline is inserted, and no more functions from the
+non-@code{nil} --- A newline is inserted, and no more functions from the
 list are called.
 
 @item
-@code{stop} -- No more functions from the list are called, but no
+@code{stop} --- No more functions from the list are called, but no
 newline is inserted.
 
 @item
-@code{nil} -- No determination is made, and the next function in the
+@code{nil} --- No determination is made, and the next function in the
 list is called.
 
 @end itemize
@@ -1939,6 +2171,25 @@
 semi-colons which do not appear inside parenthesis lists (i.e. those
 that separate @code{for}-clause statements).
 
+Here's an example of a criteria function that will prevent newlines from
+being inserted after semicolons when there is a non-blank following
+line.  Otherwise, it makes no determination:
+
+@example
+@group
+
+(defun my-semicolon-criteria ()
+  (save-excursion
+    (if (and (= last-command-char ?\;)
+             (zerop (forward-line 1))
+             (not (looking-at "^[ \t]*$")))
+        'stop
+      nil)))
+
+@end group
+@end example
+
+
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node     Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations
 @comment  node-name,              next,                    previous,up
@@ -1947,6 +2198,14 @@
 @cindex   Customizing Semi-colons and Commas
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
+@vindex c-label-minimum-indentation
+@vindex label-minimum-indentation (c-)
+In @samp{gnu} style (see @ref{Built-in Styles}), a minimum indentation
+is imposed on lines with @code{label} or @code{case-label} syntax.  This
+minimum indentation is controlled by the variable
+@code{c-label-minimum-indentation}.  The default value for this variable
+is 1.
+
 @vindex c-special-indent-hook
 @vindex special-indent-hook (c-)
 One other customization variable is available in @code{cc-mode}:
@@ -1955,10 +2214,18 @@
 to do any special indentation or line adjustments your style dictates,
 such as adding extra indentation to constructors or destructor
 declarations in a class definition, etc.  Note however, that you should
-not change point or mark inside your @code{c-special-indent-hook}
+not change Point or Mark inside your @code{c-special-indent-hook}
 functions (i.e. you'll probably want to wrap your function in a
 @code{save-excursion}).
 
+Setting @code{c-special-indent-hook} in your style definition is handled
+slightly differently than other variables.  In your style definition,
+you should set the value for
+@code{c-special-indent-hook} to a function or list of functions, which
+will be appended to @code{c-special-indent-hook} using @code{add-hook}.
+That way, the current setting for the buffer local value of
+@code{c-special-indent-hook} won't be overridden.
+
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node  Syntactic Symbols, Performance Issues, Customizing Indentation, Top
@@ -1970,9 +2237,120 @@
 
 @vindex c-offsets-alist
 @vindex offsets-alist (c-)
-The complete list of recognized syntactic symbols is described in the
-@code{c-offsets-alist} variable.  This chapter will provide some
-examples to help clarify these symbols.
+
+Here is a complete list of the recognized syntactic symbols as described
+in the @code{c-offsets-alist} variable, along with a brief description.
+More detailed descriptions follow below.
+
+@itemize @bullet
+@item
+@code{string} --- inside multi-line string
+@item
+@code{c} --- inside a multi-line C style block comment
+@item
+@code{defun-open} --- brace that opens a function definition
+@item
+@code{defun-close} --- brace that closes a function definition
+@item
+@code{defun-block-intro} --- the first line in a top-level defun
+@item
+@code{class-open} --- brace that opens a class definition
+@item
+@code{class-close} --- brace that closes a class definition
+@item
+@code{inline-open} --- brace that opens an in-class inline method
+@item
+@code{inline-close} --- brace that closes an in-class inline method
+@item
+@code{ansi-funcdecl-cont} --- the nether region between an ANSI function
+declaration and the defun opening brace
+@item
+@code{knr-argdecl-intro} --- first line of a K&R C argument declaration
+@item
+@code{knr-argdecl} --- subsequent lines in a K&R C argument declaration
+@item
+@code{topmost-intro} --- the first line in a topmost construct definition
+@item
+@code{topmost-intro-cont} --- topmost definition continuation lines
+@item
+@code{member-init-intro} --- first line in a member initialization list
+@item
+@code{member-init-cont} --- subsequent member initialization list lines
+@item
+@code{inher-intro} --- first line of a multiple inheritance list
+@item
+@code{inher-cont} --- subsequent multiple inheritance lines
+@item
+@code{block-open} --- statement block open brace
+@item
+@code{block-close} --- statement block close brace
+@item
+@code{brace-list-open} --- open brace of an enum or static array list
+@item
+@code{brace-list-close} --- close brace of an enum or static array list
+@item
+@code{brace-list-intro} --- first line in an enum or static array list
+@item
+@code{brace-list-entry} --- subsequent lines in an enum or static array list
+@item
+@code{statement} --- a C (or like) statement
+@item
+@code{statement-cont} --- a continuation of a C (or like) statement
+@item
+@code{statement-block-intro} --- the first line in a new statement block
+@item
+@code{statement-case-intro} --- the first line in a case `block'
+@item
+@code{statement-case-open} --- the first line in a case block starting
+with brace
+@item
+@code{substatement} --- the first line after an if/while/for/do/else
+@item
+@code{substatement-open} --- the brace that opens a substatement block
+@item
+@code{case-label} --- a case or default label
+@item
+@code{access-label} --- C++ private/protected/public access label
+@item
+@code{label} --- any non-special C (or like) label
+@item
+@code{do-while-closure} --- the `while' that ends a do/while construct
+@item
+@code{else-clause} --- the `else' of an if/else construct
+@item
+@code{comment-intro} --- a line containing only a comment introduction
+@item
+@code{arglist-intro} --- the first line in an argument list
+@item
+@code{arglist-cont} --- subsequent argument list lines when no arguments
+follow on the same line as the the arglist opening paren
+@item
+@code{arglist-cont-nonempty} --- subsequent argument list lines when at
+least one argument follows on the same line as the arglist opening paren
+@item
+@code{arglist-close} --- the solo close paren of an argument list
+@item
+@code{stream-op} --- lines continuing a stream operator construct
+@item
+@code{inclass} --- the construct is nested inside a class definition
+@item
+@code{cpp-macro} --- the start of a cpp macro
+@item
+@code{friend} --- a C++ friend declaration
+@item
+@code{objc-method-intro} --- the first line of an Objective-C method definition
+@item
+@code{objc-method-args-cont} --- lines continuing an Objective-C method
+definition 
+@item
+@code{objc-method-call-cont} --- lines continuing an Objective-C method call
+@item
+@code{extern-lang-open} --- brace that opens an external language block
+@item
+@code{extern-lang-close} --- brace that closes an external language block
+@item
+@code{inextern-lang} --- analogous to `inclass' syntactic symbol
+@end itemize
 
 @cindex -open syntactic symbols
 @cindex -close syntactic symbols
@@ -2009,6 +2387,11 @@
 @end group
 @end example
 
+@cindex topmost-intro syntactic symbol
+@cindex topmost-intro-cont syntactic symbol
+@cindex defun-open syntactic symbol
+@cindex defun-close syntactic symbol
+@cindex defun-block-intro syntactic symbol
 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
@@ -2019,6 +2402,8 @@
 the first line of a brace-block, which happens to be enclosed in a
 top-level function definition.
 
+@cindex statement syntactic symbol
+@cindex statement-cont syntactic symbol
 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
@@ -2045,35 +2430,63 @@
   14:         dString.tune( 'D' );
   15:         gString.tune( 'G' );
   16:     @}
-  17: @}
+  17:     friend class Luthier;
+  18: @}
 
 @end group
 @end example
 
+@cindex class-open syntactic symbol
+@cindex class-close syntactic symbol
 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++, 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 three languages are
-syntactically equivalent to classes.  Note however that the keyword
-@code{class} is meaningless in C and Objective-C.}.  Similarly, line 17
-is assigned @code{class-close} syntax.
-
+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.
+
+@cindex inher-intro syntactic symbol
+@cindex inher-cont syntactic symbol
 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.
 
-Things get interesting at line 5.  The primary syntactic symbol for this
-line is @code{access-label} since this a label keyword that specifies
-access protection in C++.  However, this line actually shows two
-syntactic symbols when you hit @kbd{C-c C-s}.  This is because it is
-also a top-level construct inside a class definition.  Thus the other
-syntactic symbol assigned to this line is @code{inclass}.  Similarly,
-line 6 is given both @code{inclass} and @code{topmost-intro} syntax.
-
+@cindex access-label syntactic symbol
+@cindex inclass syntactic symbol
+Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
+
+@example
+@group
+
+@code{((inclass . 1) (access-label . 67))}
+
+@end group
+@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
+@group
+
+@code{((inclass . 58) (topmost-intro . 60))}
+
+@end group
+@end example
+
+@cindex member-init-intro syntactic symbol
+@cindex member-init-cont syntactic symbol
 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
@@ -2082,14 +2495,27 @@
 list started on line 7.
 
 @cindex in-class inline methods
-Line 11 is assigned @code{inline-open} 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.  For example, if the definition of the
-@code{Bass} constructor appeared outside the class definition, line 11
-would be given the @code{defun-open} syntax, even if the keyword
-@code{inline} appeared before the method name, as in:
+@cindex inline-open syntactic symbol
+@cindex inline-close syntactic symbol
+But the line 11's analysis is a bit more complicated:
+
+@example
+@group
+
+@code{((inclass . 1) (inline-open))}
+
+@end group
+@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.
+For example, if the definition of the @code{Bass} constructor appeared
+outside the class definition, line 11 would be given the
+@code{defun-open} syntax, even if the keyword @code{inline} appeared
+before the method name, as in:
 @example
 @group
 
@@ -2117,11 +2543,21 @@
 @end group
 @end example
 
-@noindent
-Similarly, line 16 is given @code{inline-close} syntax.
-
-As in the first example above, line 12 is given @code{defun-block-open}
-syntax and lines 13 through 15 are all given @code{statement} syntax.
+@cindex friend syntactic symbol
+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 it's syntactic analysis list contains three
+elements:
+
+@example
+
+@code{((friend) (inclass . 58) (topmost-intro . 380))}
+
+@end example
+
+The @code{friend} syntactic symbol is a modifier that typically does not
+have a relative buffer position.
 
 Here is another (totally contrived) example which illustrates how syntax
 is assigned to various conditional constructs:
@@ -2152,25 +2588,32 @@
 @noindent
 Only the lines that illustrate new syntactic symbols will be discussed.
 
+@cindex substatement-open syntactic symbol
+@cindex substatement-block-intro syntactic symbol
+@cindex block-close syntactic symbol
 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{substatement-block-intro} syntax.  Lines 6 and 7 are assigned
 similar syntax.  Line 8 contains the brace that closes the inner
-substatement block.  It is given the generic syntax @code{block-close},
+substatement block.  It is given the syntax @code{block-close},
 as are lines 11 and 14.
 
-Line 9 is a little different -- since it contains the keyword
-@code{else} matching the @code{if} statement introduced on line 5; it is
+@cindex else-clause syntactic symbol
+@cindex substatement syntactic symbol
+Line 9 is a little different --- since it contains the keyword
+@code{else} matching the @code{if} statement introduced on line 5, it is
 given the @code{else-clause} syntax.  Note also that line 10 is slightly
 different too.  Because @code{else} is considered a conditional
 introducing keyword @footnote{The list of conditional keywords are (in
-C, Objective-C and C++): @code{for}, @code{if}, @code{do}, @code{else},
-@code{while}, and @code{switch}.  C++ has two additional conditional
-keywords: @code{try} and @code{catch}.}, and because the following
-substatement is not a brace block, line 10 is assigned the
+C, C++, Objective-C, and Java): @code{for}, @code{if}, @code{do},
+@code{else}, @code{while}, and @code{switch}.  C++ and Java have two
+additional conditional keywords: @code{try} and @code{catch}.  Java also
+has the @code{finally} and @code{synchronized} keywords.}, and because
+the following substatement is not a brace block, line 10 is assigned the
 @code{substatement} syntax.
 
+@cindex do-while-closure syntactic symbol
 One other difference is seen on line 15.  The @code{while} construct
 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
@@ -2202,10 +2645,13 @@
 @end group
 @end example
 
+@cindex case-label syntactic symbol
+@cindex statement-case-intro syntactic symbol
+@cindex statement-case-open syntactic symbol
 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.
+block --- it is given @code{statement-case-open} syntax.
 
 @cindex brace lists
 There are a set of syntactic symbols that are used to recognize
@@ -2225,6 +2671,10 @@
 @end group
 @end example
 
+@cindex brace-list-open syntactic symbol
+@cindex brace-list-intro syntactic symbol
+@cindex brace-list-close syntactic symbol
+@cindex brace-list-entry syntactic symbol
 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
@@ -2232,6 +2682,30 @@
 @code{brace-list-entry} syntax, as would all subsequent lines in this
 initializer list.
 
+External language definition blocks also have their own syntactic
+symbols.  In this example:
+@example
+@group
+
+   1: extern "C" 
+   2: @{
+   3:     int thing_one( int );
+   4:     int thing_two( double );
+   5: @}
+
+@end group
+@end example
+
+@cindex extern-lang-open syntactic symbol
+@cindex extern-lang-close syntactic symbol
+@cindex inextern-lang syntactic symbol
+@cindex inclass syntactic symbol
+@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:
+@code{((inextern-lang) (topmost-intro . 14))}, where
+@code{inextern-lang} is a modifier similar in purpose to @code{inclass}.
+
 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:
@@ -2260,20 +2734,25 @@
 @end group
 @end example
 
+@cindex arglist-intro syntactic symbol
+@cindex arglist-close syntactic symbol
 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.
 
-The other lines with relevant syntactic symbols include lines 2 and 17
-which are assigned @code{arglist-cont-nonempty} syntax.  What this means
+@cindex arglist-cont-nonempty syntactic symbol
+@cindex arglist-cont syntactic symbol
+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{non-empty} following the open
+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 @footnote{The
 need for this somewhat confusing arrangement is that the typical
-indentation desired for these lines is calculated very differently.
+indentation desired for these lines is calculated differently.
 This should be simplified in version 5 of @code{cc-mode}, along with the
 added distinction between argument lists in function declarations, and
 argument lists in function calls.}.
@@ -2315,18 +2794,21 @@
 
 @itemize @bullet
 
+@cindex ansi-funcdecl-cont syntactic symbol
 @item
-line 2 which is assigned the @code{ansi-funcdecl-cont} syntax;
-
+line 2, assigned the @code{ansi-funcdecl-cont} syntax;
+
+@cindex comment-intro syntactic symbol
 @item
-line 4 which is assigned both @code{defun-block-intro} @emph{and}
+line 4, assigned both @code{defun-block-intro} @emph{and}
 @code{comment-intro} syntax @footnote{The @code{comment-intro} syntactic
-symbol is known generically as a @dfn{modifier} since it always appears
-on a syntactic analysis list with other symbols, and never has a
-relative buffer position.};
-
+symbol is is another example of a @dfn{modifier} since it always appears
+on a syntactic analysis list with other symbols, and rarely has an
+associated relative buffer position.};
+
+@cindex c syntactic symbol
 @item
-line 5 which is assigned @code{c} syntax;
+line 5, assigned @code{c} syntax;
 
 @item
 @cindex syntactic whitespace
@@ -2334,23 +2816,28 @@
 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 essentially ignored when analyzing
+@dfn{syntactic whitespace}, which are ignored when analyzing
 code;
 
+@cindex string syntactic symbol
 @item
-line 8 which is assigned @code{string} syntax;
-
+line 8, assigned @code{string} syntax;
+
+@cindex label syntactic symbol
 @item
-line 10 which is assigned @code{label} syntax;
-
+line 10, assigned @code{label} syntax;
+
+@cindex block-open syntactic symbol
 @item
-line 11 which is assigned @code{block-open} syntax;
-
+line 11, assigned @code{block-open} syntax;
+
+@cindex cpp-macro syntactic symbol
 @item
-lines 12 and 14 which are assigned @code{cpp-macro} syntax;
-
+lines 12 and 14, assigned @code{cpp-macro} syntax;
+
+@cindex stream-op syntactic symbol
 @item
-line 17 which is assigned @code{stream-op} syntax @footnote{In C++ only.}.
+line 17, assigned @code{stream-op} syntax @footnote{In C++ only.}.
 
 @end itemize
 
@@ -2371,14 +2858,35 @@
 @end group
 @end example
 
+@cindex objc-method-intro syntactic symbol
+@cindex objc-method-args-cont syntactic symbol
+@cindex objc-method-call-cont syntactic symbol
 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.
 
-Other syntactic symbols may be recognized by @code{cc-mode}, but these
-are more obscure and so I haven't included examples of them.  These
-include: @code{knr-argdecl-intro}, @code{knr-argdecl}, and the
-@code{friend} modifier.
+@cindex knr-argdecl-intro
+@cindex 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
+@group
+
+  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 group
+@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  Performance Issues, Frequently Asked Questions, Syntactic Symbols, Top
@@ -2390,16 +2898,16 @@
 
 C and it's derivative languages are highly complex creatures.  Often,
 ambiguous code situations arise that require @code{cc-mode} to scan
-large portions of the buffer to determine syntactic context.  Some
-pathological code can cause @code{cc-mode} to slow down considerably.
+large portions of the buffer to determine syntactic context.  Such
+pathological code@footnote{such as the output of @code{lex(1)}!}
+can cause @code{cc-mode} to perform fairly badly.
 This section identifies some of the coding styles to watch out for, and
 suggests some workarounds that you can use to improve performance.
 
 Note that this is an area that will get a lot of attention in
 @code{cc-mode} version 5.  The mode should end up being much faster, at
 the expense of dropping Emacs 18 support, owing to the implementation of
-syntactic analysis caching.  This is the last release of @code{cc-mode}
-that will be compatible with Emacs 18.
+syntactic analysis caching.
 
 Because @code{cc-mode} has to scan the buffer backwards from the current
 insertion point, and because C's syntax is fairly difficult to parse in
@@ -2422,26 +2930,26 @@
 reasonable'' is difficult to define, so @code{cc-mode} doesn't do it
 for you.
 
-@cindex @file{cc-lobotomy.el} file
 You will probably notice pathological behavior from @code{cc-mode} when
 working in files containing large amounts of cpp macros.  This is
-because @code{cc-mode} cannot quickly skip backwards over these lines,
-which do not contribute to the syntactic calculations.  You'll probably
-also have problems if you are editing ``K&R'' C code, i.e. C code that
-does not use function prototypes.  This is because there are ambiguities
-in the C syntax when K&R style argument lists are used, and
-@code{cc-mode} has to use a slower scan to determine what it's looking
-at.
+because @code{cc-mode} cannot quickly skip backwards over these lines.
 
 @vindex c-recognize-knr-p
 @vindex recognize-knr-p (c-)
-For the latter problem, I would suggest converting to ANSI style
-protocols, and turning the variable @code{c-recognize-knr-p} to
-@code{nil} (this is it's default value for all modes).
-
+Previous versions of @code{cc-mode} had potential performance problems
+when recognizing ``K&R'' style function argument declarations.  This was
+because there are ambiguities in the C syntax when K&R style argument
+lists are used (it is hard to distinguish them from top-level
+declarations).  @code{cc-mode} has adopted BOCM's convention for
+limiting the search: it assumes that argdecls are indented at least one
+space, and that the function headers are not indented at all.  With
+current versions of @code{cc-mode},
+@code{c-recognize-knr-p} is deprecated.
+
+@cindex @file{cc-lobotomy.el} file
 @vindex cc-lobotomy-pith-list
-For the former problem, you might want to investigate some of the
-speed-ups provided for you in the file @file{cc-lobotomy.el}, which
+You might want to investigate some of the
+speed-ups contained in the file @file{cc-lobotomy.el}, which
 is part of the canonical @code{cc-mode} distribution.  As mentioned
 previous, @code{cc-mode} always trades accuracy for speed, however it is
 recognized that sometimes you need speed and can sacrifice some accuracy
@@ -2458,6 +2966,7 @@
 
 @chapter  Frequently Asked Questions
 @cindex   Frequently Asked Questions
+@comment FAQ
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 @kindex C-x h
@@ -2475,21 +2984,21 @@
 
 @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole
 buffer. Then hit @kbd{@key{ESC} C-\}.
-@sp 2
+@sp 1
 
 @strong{Q.} @emph{How do I re-indent the entire function?
 @kbd{@key{ESC} C-x} doesn't work.}
 
 @strong{A.} @kbd{@key{ESC} C-x} is reserved for future Emacs use.
 To re-indent the entire function hit @kbd{C-c C-q}.
-@sp 2
+@sp 1
 
 @strong{Q.} @emph{How do I re-indent the current block?}
 
 @strong{A.} First move to the brace which opens the block with
 @kbd{@key{ESC} C-u}, then re-indent that expression with
 @kbd{@key{ESC} C-q}.
-@sp 2
+@sp 1
 
 @strong{Q.} @emph{Why doesn't the @key{RET} key indent the line to
 where the new text should go after inserting the newline?}
@@ -2507,7 +3016,7 @@
 
 This is a very common question. @code{:-)} If you want this to be the
 default behavior, don't lobby me, lobby RMS!
-@sp 2
+@sp 1
 
 @strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)}
 in my @file{.emacs} file but I get an error saying that
@@ -2528,12 +3037,24 @@
 See the sample @file{.emacs} file @ref{Sample .emacs File} for
 details.
 
+@sp 1
 @strong{Q.} @emph{How do I make strings, comments, keywords, and other
 constructs appear in different colors, or in bold face, etc.?}
 
 @strong{A.} ``Syntax Colorization'' is an Emacs 19 feature, controlled
 by @code{font-lock-mode}.  It is not part of @code{cc-mode}.
 
+@sp 1
+@strong{Q.} @emph{I @code{setq} @code{c-basic-offset} to 4 in my
+@file{.emacs} file, but why does everything still get indented with only
+2 spaces?}
+
+@strong{A.} It's because @code{c-basic-offset} is now a ``buffer local
+variable'', meaning its value is unique to each buffer.  The prefered
+way to customize this is to change its value in a ``mode hook'' (most
+likely @code{c-mode-common-hook}.  Alternatively you can use
+@code{setq-default} to change its value globally.
+
 @end quotation
 
 
@@ -2547,16 +3068,26 @@
 
 @code{cc-mode} is now distributed with both Emacs 19 and XEmacs 19, so
 you would typically just use the version that comes with your Emacs.
-Users of older versions of Emacs can get the latest release from this
-URL:
+These may be slightly out of date due to release schedule skew, so you
+should always check the canonical site for the latest version.
 
 @example
-
-    @code{ftp://ftp.python.org/pub/emacs/cc-mode.tar.gz}
-
+@group
+
+    World Wide Web:
+
+        @code{http://www.python.org/ftp/emacs/}
+
+    Anonymous FTP:
+
+        @code{ftp://ftp.python.org/pub/emacs/}
+
+@end group
 @end example
 
-Note that this is a ``gzipped'' tar file.
+There are many files under these directories; you can pick up the entire
+distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of
+the individual files, including PostScript documentation.
 
 If you do not have anonymous ftp access, you can get the distribution
 through an anonymous ftp-to-mail gateway, such as the one run by DEC at
@@ -2574,10 +3105,12 @@
 @end example
 @noindent
 or just send the message "help" for more information on ftpmail.
-Response times will vary with the number of requests in the queue.
+Response times will vary with the number of requests in the queue.  I am
+in no way connected to this service, so I make no claims or guarantees
+about its availability!
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node  Sample .emacs File, Requirements, Getting the latest cc-mode release, Top
+@node  Sample .emacs File, Limitations and Known Bugs, Getting the latest cc-mode release, Top
 @comment  node-name,              next,                    previous,up
 
 @chapter  Sample @file{.emacs} file
@@ -2623,8 +3156,9 @@
         indent-tabs-mode nil)
   ;; we like auto-newline and hungry-delete
   (c-toggle-auto-hungry-state 1)
-  ;; keybindings for C, C++, and Objective-C.  We can put these in
-  ;; c-mode-map because c++-mode-map and objc-mode-map inherit it
+  ;; keybindings for all supported languages.  We can put these in
+  ;; c-mode-map because c++-mode-map, objc-mode-map, and java-mode-map
+  ;; inherit from it.
   (define-key c-mode-map "\C-m" 'newline-and-indent)
   )
 
@@ -2634,34 +3168,7 @@
 @end example
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node  Requirements, Limitations and Known Bugs, Sample .emacs File, Top
-@comment  node-name,              next,                    previous,up
-@chapter  Requirements
-@cindex   Requirements
-@comment * Requirements
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-@cindex reporter.el
-@file{cc-mode.el} requires @file{reporter.el} for submission of bug
-reports.  @file{reporter.el} is distributed with the latest Emacs 19s.
-Here is the Emacs Lisp Archive anonymous ftp'ing record for those of you
-who are using older Emacsen.
-
-@comment * Here's the Emacs Lisp Archive information for @file{reporter.el}:
-@example
-
-         GNU Emacs Lisp Code Directory Apropos -- "reporter"
-"~/" refers to archive.cis.ohio-state.edu:/pub/gnu/emacs/elisp-archive/
-
-reporter (2.12)       06-Jul-1994
-     Barry A. Warsaw, <bwarsaw@@cnri.reston.va.us>
-     ~/misc/reporter.el.Z
-     Customizable bug reporting of lisp programs.
-
-@end example
-
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node  Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Requirements, Top
+@node  Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Sample .emacs File, Top
 @comment  node-name,              next,                    previous,up
 @chapter  Limitations and Known Bugs
 @cindex   Limitations and Known Bugs
@@ -2681,14 +3188,17 @@
 
 @item
 There is still some weird behavior when filling C block comments.
-My suggestion is to check out add-on fill packages such as
-@code{filladapt}, available at the elisp archive.
-
-@cindex inline-close
-@kindex TAB
+My suggestion is to check out separate fill packages such as
+@code{filladapt} or @code{adaptive-fill-mode}.  These can do a much
+better job of filling comment regions.
+
+@cindex c-indent-exp
+@cindex indent-exp (c-)
 @item
-Lines following @code{inline-close} braces which hang ``after'' do not
-line up correctly.  Hit @kbd{TAB} to reindent the line.
+@code{c-indent-exp} has not been fully optimized.  It essentially
+equivalent to hitting @kbd{TAB} (@code{c-indent-command}) on every
+line.  Some information is cached from line to line, but such caching
+invariable causes inaccuracies in analysis in some bizarre situations.
 
 @end itemize
 
@@ -2710,17 +3220,16 @@
 Please try to boil your example down to just the essential code needed
 to reproduce the problem, and include an exact recipe of steps needed to
 expose the bug.  Be especially sure to include any code that appears
-@emph{before} your bug example.
-
-Bug reports are now to be sent to @code{bug-gnu-emacs@@prep.ai.mit.edu}
-which is mirrored on the Usenet newsgroup @code{gnu.emacs.bug}.  Other
-questions and suggestions should be mailed to
-@code{help-gnu-emacs@@prep.ai.mit.edu} which is mirrored on
+@emph{before} your bug example, if you think it might affect my ability
+to reproduce it.
+
+Bug reports are now sent to the following email addresses:
+@code{cc-mode-help@@python.org} and
+@code{bug-gnu-emacs@@prep.ai.mit.edu}; the latter is mirrored on the Usenet
+newsgroup @code{gnu.emacs.bug}.  Other questions and suggestions should
+be mailed to @code{help-gnu-emacs@@prep.ai.mit.edu} which is mirrored on
 @code{gnu.emacs.help}.
 
-Note that the @code{cc-mode} Majordomo mailing lists have been
-disbanded!  With the inclusion of @code{cc-mode} in both of the latest
-flavors of Emacs 19, the need for them has ended.
 
 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node    Concept Index, Command Index,  Mailing Lists and Submitting Bug Reports, Top
@@ -2741,8 +3250,8 @@
 
 @end ifinfo
 Since all @code{cc-mode} commands are prepended with the string
-@samp{c-}, each appears under its @code{c-<thing>} name and its
-@code{<thing> (c-)} name.
+@samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
+@code{@var{<thing>} (c-)} name.
 @iftex
 @sp 2
 @end iftex
@@ -2768,8 +3277,8 @@
 
 @end ifinfo
 Since all @code{cc-mode} variables are prepended with the string
-@samp{c-}, each appears under its @code{c-<thing>} name and its
-@code{<thing> (c-)} name.
+@samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
+@code{@var{<thing>} (c-)} name.
 @iftex
 @sp 2
 @end iftex