emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] Changes to emacs/man/cc-mode.texi [gnus-5_10-branch]


From: Miles Bader
Subject: [Emacs-diffs] Changes to emacs/man/cc-mode.texi [gnus-5_10-branch]
Date: Sat, 04 Sep 2004 08:15:13 -0400

Index: emacs/man/cc-mode.texi
diff -c /dev/null emacs/man/cc-mode.texi:1.24.2.1
*** /dev/null   Sat Sep  4 12:02:50 2004
--- emacs/man/cc-mode.texi      Sat Sep  4 12:01:14 2004
***************
*** 0 ****
--- 1,5726 ----
+ \input texinfo
+ 
+ @c Notes to self regarding line handling:
+ @c
+ @c Empty lines are often significant before @end directives; avoid them.
+ @c
+ @c Empty lines before and after @example directives are significant in
+ @c info output but not in TeX.  Empty lines inside @example directives
+ @c are significant.
+ 
+ @c Conventions for formatting examples:
+ @c o  If the example contains empty lines then put the surrounding empty
+ @c    lines inside the @example directives.  Put them outside otherwise.
+ @c o  Use @group inside the example only if it shows indentation where
+ @c    the relation between lines inside is relevant.
+ @c o  Format line number columns like this:
+ @c     1: foo
+ @c     2: bar
+ @c       ^ one space
+ @c    ^^ two columns, right alignment
+ @c o  Check line lengths in TeX output; they can typically be no longer
+ @c    than 70 chars, 60 if the paragraph is indented.
+ 
+ @comment TBD: Document the finer details of statement anchoring?
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @comment %**start of header (This is for running Texinfo on a region)
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @comment No overfull hbox marks in the dvi file.
+ @finalout
+ 
+ @setfilename  ../info/ccmode
+ @settitle     CC Mode Manual
+ @footnotestyle end
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @comment @setchapternewpage odd !! we don't want blank pages !!
+ @comment %**end of header (This is for running Texinfo on a region)
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @comment 
+ @comment Texinfo manual for CC Mode
+ @comment Generated from the original README file by Krishna Padmasola
+ @comment <address@hidden>
+ @comment
+ @comment Authors:
+ @comment Barry A. Warsaw
+ @comment Martin Stjernholm
+ @comment
+ @comment Maintained by Martin Stjernholm <address@hidden>
+ @comment 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @comment Define an index for syntactic symbols.
+ @defindex ss
+ 
+ @comment Combine key, syntactic symbol and concept indices into one.
+ @syncodeindex ss cp
+ @syncodeindex ky cp
+ 
+ @copying
+ This manual is for CC Mode in Emacs.
+ 
+ Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+ 2003 Free Software Foundation, Inc.
+ 
+ @quotation
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1 or
+ any later version published by the Free Software Foundation; with the
+ Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
+ ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
+ Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
+ license is included in the section entitled ``GNU Free Documentation
+ License'' in the Emacs manual.
+ 
+ (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+ this GNU Manual, like GNU software.  Copies published by the Free
+ Software Foundation raise funds for GNU development.''
+ 
+ This document is part of a collection distributed under the GNU Free
+ Documentation License.  If you want to distribute this document
+ separately from the collection, you can do so by adding a copy of the
+ license to the document, as described in section 6 of the license.
+ @end quotation
+ @end copying
+ 
+ @comment Info directory entry for use by install-info. The indentation
+ @comment here is by request from the FSF folks.
+ @dircategory Emacs
+ @direntry
+ * CC Mode: (ccmode).    Emacs mode for editing C, C++, Objective-C,
+                         Java, Pike, AWK, and CORBA IDL code.
+ @end direntry
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @comment TeX title page
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @titlepage
+ @sp 10
+ 
+ @center @titlefont{CC Mode 5.30}
+ @sp 2
+ @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
+ @sp 2
+ @center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie (AWK support)
+ 
+ @page
+ @vskip 0pt plus 1filll
+ @insertcopying
+ @end titlepage
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @comment The Top node contains the master menu for the Info file.
+ @comment This appears only in the Info file, not the printed manual.
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @node    Top, Introduction, (dir), (dir)
+ @comment node-name, next, previous, up
+ 
+ @macro ccmode
+ CC Mode
+ @end macro
+ 
+ @ifinfo
+ @top @ccmode{}
+ 
+ @ccmode{} is a GNU Emacs mode for editing files containing C, C++,
+ Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
+ code and to a certain extent, AWK code @xref{AWK Mode}.  It provides
+ syntax-based indentation, font locking, and has several handy commands
+ and some minor modes to make the editing easier.  It does not provide
+ tools to look up and navigate between functions, classes etc - there are
+ other packages for that.
+ @end ifinfo
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @menu
+ * Introduction::
+ * Getting Connected::
+ * Indentation Engine::
+ * Minor Modes::
+ * Text Filling and Line Breaking::
+ * Macro Handling::
+ * Font Locking::
+ * Commands::
+ * Customizing Indentation::
+ * Syntactic Symbols::
+ * Indentation Functions::
+ * AWK Mode::
+ * Odds and Ends::
+ * Performance Issues::
+ * Limitations and Known Bugs::
+ * Frequently Asked Questions::
+ * Getting the Latest CC Mode Release::
+ * Mailing Lists and Submitting Bug Reports::
+ * Sample .emacs File::
+ 
+  --- Indices ---
+ 
+ * Command and Function Index::
+ * Variable Index::
+ * Concept Index::
+ 
+ @detailmenu
+  --- The Detailed Node Listing ---
+ 
+ Indentation Engine
+ 
+ * Syntactic Analysis::
+ * Indentation Calculation::
+ 
+ Minor Modes
+ 
+ * Auto-newline Insertion::
+ * Hungry-deletion of Whitespace::
+ 
+ Font Locking
+ 
+ * Font Locking Preliminaries::
+ * Faces::
+ * Documentation Comments::
+ 
+ Auto-newline Insertion
+ 
+ * Hanging Braces::
+ * Hanging Colons::
+ * Hanging Semicolons and Commas::
+ * Other Electric Commands::
+ * Clean-ups::
+ 
+ Commands
+ 
+ * Indentation Commands::
+ * Movement Commands::
+ * Other Commands::
+ 
+ Customizing Indentation
+ 
+ * Interactive Customization::
+ * Permanent Customization::
+ * Hooks::
+ * Styles::
+ * Advanced Customizations::
+ 
+ Styles
+ 
+ * Built-in Styles::
+ * Choosing a Style::
+ * Adding Styles::
+ * File Styles::
+ 
+ Advanced Customizations
+ 
+ * Custom Indentation Functions::
+ * Custom Brace and Colon Hanging::
+ * Customizing Semicolons and Commas::
+ * Other Special Indentations::
+ 
+ AWK Mode
+ 
+ * Initialising AWK Mode::
+ * AWK Mode Font Locking::
+ * AWK Mode Defuns::
+ @end detailmenu
+ @end menu
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Introduction, Getting Connected, Top, Top
+ @comment node-name, next, previous, up
+ @chapter Introduction
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @cindex BOCM
+ 
+ Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
+ C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
+ CIDL), Pike and to a certain extent, AWK code (@pxref{AWK Mode}).  This
+ incarnation of the mode is descended from @file{c-mode.el} (also called
+ ``Boring Old C Mode'' or BOCM @t{:-)}, and @file{c++-mode.el} version 2,
+ which Barry has been maintaining since 1992.  Late in 1997, Martin
+ joined the @ccmode{} Maintainers Team, and implemented the Pike support.
+ As of 2000 Martin has taken over as the sole maintainer.  @ccmode{} did
+ not originally contain the font lock support for its languages --- that
+ was added in version 5.30.  AWK support was also added in 5.30 by Alan
+ Mackenzie.
+ 
+ This manual describes @ccmode{}
+ @comment The following line must appear on its own, so that the automated
+ version 5.30.
+ @comment Release.py script can update the version number automatically
+ 
+ @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
+ Java, CORBA's Interface Definition Language, address@hidden C-like
+ scripting language with its roots in the LPC language used in some MUD
+ engines.  See @uref{http://pike.ida.liu.se/}.} and AWK files.  In this
+ way, you can easily set up consistent font locking and coding styles for
+ use in editing all of these languages, although AWK is not yet as
+ uniformly integrated as the other languages.
+ 
+ @findex c-mode
+ @findex c++-mode
+ @findex objc-mode
+ @findex java-mode
+ @findex idl-mode
+ @findex pike-mode
+ @findex awk-mode
+ Note that the name of this package is address@hidden,'' but there is no top
+ level @code{cc-mode} entry point.  All of the variables, commands, and
+ functions in @ccmode{} are prefixed with @address@hidden, and
+ @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
+ @code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
+ provided.  This package is intended to be a replacement for
+ @file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.
+ 
+ @c @cindex @file{cc-compat.el} file
+ @c This distribution also contains a file
+ @c called @file{cc-compat.el} which should ease your transition from BOCM
+ @c to @ccmode{}.  If you have a BOCM configuration you are really happy
+ @c with, and want to postpone learning how to configure @ccmode{}, take a
+ @c look at that file.  It maps BOCM configuration variables to @ccmode{}'s
+ @c indentation model.  It is not actively supported so for the long run,
+ @c you should learn how to customize @ccmode{} to support your coding
+ @c style.
+ 
+ A special word of thanks goes to Krishna Padmasola for his work in
+ converting the original @file{README} file to Texinfo format.  I'd also
+ like to thank all the @ccmode{} victims who help enormously during the
+ early beta stages of @ccmode{}'s development.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Getting Connected, Indentation Engine, Introduction, Top
+ @comment node-name, next, previous, up
+ @chapter Getting Connected
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ If you got this version of @ccmode{} with Emacs or XEmacs, it should
+ work just fine right out of the box.  Note however that you may not have
+ the latest @ccmode{} release and may want to upgrade your copy.
+ 
+ If you are upgrading an existing @ccmode{} installation, please see the
+ @file{README} file for installation details.  @ccmode{} may not work
+ with older versions of Emacs or XEmacs.  See the @ccmode{} release notes
+ at @uref{http://cc-mode.sourceforge.net} for the latest information on
+ Emacs version and package compatibility (@pxref{Getting the Latest CC
+ Mode Release}).
+ 
+ @deffn Command c-version
+ @findex version (c-)
+ You can find out what version of @ccmode{} you are using by visiting a C
+ file and entering @kbd{M-x c-version RET}.  You should see this message in
+ the echo area:
+ 
+ @example
+ Using CC Mode version 5.XX
+ @end example
+ 
+ @noindent
+ where @samp{XX} is the minor release number.
+ @end deffn
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Indentation Engine, Minor Modes, Getting Connected, Top
+ @comment node-name, next, previous, up
+ @chapter Indentation Engine
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @ccmode{} has an indentation engine that provides a flexible and general
+ mechanism for customizing indentation. It separates indentation
+ calculation into two steps: first, @ccmode{} analyzes the line of code
+ being indented to determine the kind of language construct it's looking
+ at, then it applies user defined offsets to the current line based on
+ this analysis.
+ 
+ This section will briefly cover how indentation is calculated in
+ @ccmode{}. It is important to understand the indentation model being
+ used so that you will know how to customize @ccmode{} for your personal
+ coding style.  All the details are in @ref{Customizing Indentation}, and
+ later chapters.
+ 
+ @defopt c-syntactic-indentation
+ @vindex syntactic-indentation (c-)
+ Syntactic analysis for indentation is done when this is address@hidden
+ (which is the default).  When it's @code{nil} every line is just
+ indented to the same level as the previous one, and @kbd{TAB}
+ (@code{c-indent-command}) adjusts the indentation in steps of
+ @code{c-basic-offset}.  The indentation style has no effect, nor any of
+ the indentation associated variables, e.g., @code{c-special-indent-hook}.
+ @end defopt
+ 
+ @menu
+ * Syntactic Analysis::
+ * Indentation Calculation::
+ @end menu
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Syntactic Analysis, Indentation Calculation, , Indentation Engine
+ @comment node-name, next, previous, up
+ @section Syntactic Analysis
+ @cindex syntactic analysis
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @cindex relative buffer position
+ @cindex syntactic symbols
+ @cindex syntactic component
+ @cindex syntactic component list
+ The first thing @ccmode{} does when indenting a line of code, is to
+ analyze the line, determining the @dfn{syntactic component list} of the
+ construct on that line.  A syntactic component consists of a pair of
+ elements (in lisp parlance, a @emph{cons cell}), the first being
+ a @dfn{syntactic symbol}, the second being a @dfn{relative
+ buffer position}.  Syntactic symbols describe elements of C code
+ @footnote{Unless otherwise noted, the term ``C code'' refers to all
+ the C-like languages.}, e.g., @code{statement}, @code{substatement},
+ @code{class-open}, @code{class-close}, etc.  @xref{Syntactic Symbols},
+ for a complete list of currently recognized syntactic symbols and their
+ semantics.  The style variable @code{c-offsets-alist} also contains the
+ list of currently supported syntactic symbols.
+ 
+ Conceptually, a line of C code is always indented relative to the
+ indentation of some line higher up in the buffer.  This is represented
+ by the relative buffer position in the syntactic component.
+ 
+ Here is an example.  Suppose we had the following code as the only thing
+ in a C++ buffer @footnote{The line numbers in this and future examples
+ don't actually appear in the buffer, of course!}:
+ 
+ @example
+  1: void swap( int& a, int& b )
+  2: @{
+  3:     int tmp = a;
+  4:     a = b;
+  5:     b = tmp;
+  6: @}
+ @end example
+ 
+ @kindex C-c C-s
+ @findex c-show-syntactic-information
+ @findex show-syntactic-information (c-)
+ We can use the command @kbd{C-c C-s} (bound to
+ @code{c-show-syntactic-information}) to simply report what the
+ syntactic analysis is for the current line.  Running this command on
+ line 4 of this example, we'd see in the echo address@hidden 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))
+ @end example
+ 
+ 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
+ would see:
+ 
+ @example
+ ((defun-block-intro 29))
+ @end example
+ 
+ This indicates that the @samp{int} line is the first statement in a top
+ level function block, and is indented relative to buffer position 29,
+ which is the brace just after the function header.
+ 
+ Here's another example:
+ 
+ @example
+  1: int add( int val, int incr, int doit )
+  2: @{
+  3:     if( doit )
+  4:         @{
+  5:             return( val + incr );
+  6:         @}
+  7:     return( val );
+  8: @}
+ @end example
+ 
+ @noindent
+ Hitting @kbd{C-c C-s} on line 4 gives us:
+ 
+ @example
+ ((substatement-open 46))
+ @end example
+ 
+ @cindex substatement
+ @cindex substatement block
+ @noindent
+ which tells us that this is a brace that @emph{opens} a substatement
+ block. @footnote{A @dfn{substatement} is the line after a
+ conditional statement, such as @code{if}, @code{else}, @code{while},
+ @code{do}, @code{switch}, etc.  A @dfn{substatement
+ block} is a brace block following one of these conditional statements.}
+ 
+ @cindex comment-only line
+ Syntactic component lists can contain more than one component, and
+ individual syntactic components need not have relative buffer positions.
+ The most common example of this is a line that contains a @dfn{comment
+ only line}.
+ 
+ @example
+  1: void draw_list( List<Drawables>& drawables )
+  2: @{
+  3:         // call the virtual draw() method on each element in list
+  4:     for( int i=0; i < drawables.count(), ++i )
+  5:     @{
+  6:         drawables[i].draw();
+  7:     @}
+  8: @}
+ @end example
+ 
+ @noindent
+ Hitting @kbd{C-c C-s} on line 3 of this example gives:
+ 
+ @example
+ ((comment-intro) (defun-block-intro 46))
+ @end example
+ 
+ @noindent
+ 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.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Indentation Calculation, , Syntactic Analysis, Indentation Engine
+ @comment node-name, next, previous, up
+ @section Indentation Calculation
+ @cindex indentation
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Indentation for a line is calculated using the syntactic
+ component list derived in step 1 above (@pxref{Syntactic Analysis}).
+ Each component contributes to the final total indentation of the line in
+ two ways.
+ 
+ First, the syntactic symbols are looked up in the @code{c-offsets-alist}
+ style variable, which is an association list of syntactic symbols and
+ the offsets to apply for those symbols.  These offsets are added to a
+ running total.
+ 
+ Second, if the component has a relative buffer position, @ccmode{}
+ adds the column number of that position to the running total.  By adding
+ up the offsets and columns for every syntactic component on the list,
+ the final total indentation for the current line is computed.
+ 
+ Let's use our two code examples above to see how this works.  Here is
+ our first example again:
+ 
+ @example
+  1: void swap( int& a, int& b )
+  2: @{
+  3:     int tmp = a;
+  4:     a = b;
+  5:     b = tmp;
+  6: @}
+ @end example
+ 
+ Let's say point is on line 3 and we hit the @kbd{TAB} key to reindent
+ the line.  Remember that the syntactic component list for that
+ line is:
+ 
+ @example
+ ((defun-block-intro 29))
+ @end example
+ 
+ @noindent
+ @ccmode{} looks up @code{defun-block-intro} in the
+ @code{c-offsets-alist} style variable.  Let's say it finds the value
+ @samp{4}; it adds this to the running total (initialized to zero),
+ yielding a running total indentation of 4 spaces.
+ 
+ Next @ccmode{} goes to buffer position 29 and asks for the current
+ column.  This brace is in column zero, so @ccmode{}
+ 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
+ is 4 spaces.
+ 
+ Here's another example:
+ 
+ @example
+  1: int add( int val, int incr, int doit )
+  2: @{
+  3:     if( doit )
+  4:         @{
+  5:             return( val + incr );
+  6:         @}
+  7:     return( val );
+  8: @}
+ @end example
+ 
+ If we were to hit @kbd{TAB} on line 4 in the above example, the same
+ basic process is performed, despite the differences in the syntactic
+ component list.  Remember that the list for this line is:
+ 
+ @example
+ ((substatement-open 46))
+ @end example
+ 
+ Here, @ccmode{} first looks up the @code{substatement-open} symbol
+ in @code{c-offsets-alist}. Let's say it finds the value @samp{4}.  This
+ yields a running total of 4.  @ccmode{} then goes to
+ buffer position 46, which is the @samp{i} in @code{if} on line 3.  This
+ character is in the fourth column on that line so adding this to the
+ running total yields an indentation for the line of 8 spaces.
+ 
+ Simple, huh?
+ 
+ Actually, the mode usually just does The Right Thing without you having
+ to think about it in this much detail.  But when customizing
+ indentation, it's helpful to understand the general indentation model
+ being used.
+ 
+ As you configure @ccmode{}, you might want to set the variable
+ @code{c-echo-syntactic-information-p} to address@hidden so that the
+ syntactic component list and calculated offset will always be echoed in
+ the minibuffer when you hit @kbd{TAB}.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Minor Modes, Text Filling and Line Breaking, Indentation Engine, Top
+ @comment node-name, next, previous, up
+ @chapter Minor Modes
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @ccmode{} contains two minor-mode-like features that you should
+ find useful while entering 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
+ @ccmode{} 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 @ccmode{} buffer.  When auto-newline mode is
+ enabled, you will see @samp{C/a} on the mode address@hidden @samp{C}
+ would be replaced with the name of the language in question for the
+ other languages @ccmode{} supports.}.  When hungry delete mode is
+ enabled you will see @samp{C/h} and if both modes were enabled, you'd
+ see @samp{C/ah}.
+ 
+ @kindex C-c C-a
+ @kindex C-c C-d
+ @kindex C-c C-t
+ @findex c-toggle-hungry-state
+ @findex c-toggle-auto-state
+ @findex c-toggle-auto-hungry-state
+ @findex toggle-hungry-state (c-)
+ @findex toggle-auto-state (c-)
+ @findex toggle-auto-hungry-state (c-)
+ @ccmode{} provides key bindings which allow you to toggle the minor
+ modes on the fly while editing code.  To toggle just the auto-newline
+ state, hit @kbd{C-c C-a} (bound to @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, 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
+ called one of the @code{c-toggle-*-state} functions directly.  When
+ called programmatically, each function takes a numeric value, where
+ a positive number enables the minor mode, a negative number disables the
+ mode, and zero toggles the current state of the mode.
+ 
+ So for example, if you wanted to enable both auto-newline and
+ hungry-delete for all your C file editing, you could add the following
+ to your @file{.emacs} file:
+ 
+ @example
+ (add-hook 'c-mode-common-hook
+           (lambda () (c-toggle-auto-hungry-state 1)))
+ @end example
+ 
+ @menu
+ * Auto-newline Insertion::
+ * Hungry-deletion of Whitespace::
+ @end menu
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Auto-newline Insertion, Hungry-deletion of Whitespace, , Minor Modes
+ @comment node-name, next, previous, up
+ @section Auto-newline Insertion
+ @cindex auto-newline
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @cindex electric characters
+ Auto-newline minor mode works by enabling certain @dfn{electric
+ characters}.  Special characters such as the left and right braces,
+ colons, semicolons, etc., have been made electric to perform some
+ magic formatting in addition to inserting the typed character.  As a
+ general rule, electric characters are only electric when the following
+ conditions apply:
+ 
+ @itemize @bullet
+ @item
+ Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or
+ @samp{C/ah} indicator on the modeline.
+ 
+ @item
+ @cindex literal
+ @cindex syntactic whitespace
+ The character was not typed inside of a literal @footnote{A
+ @dfn{literal} is defined as any comment, string, or preprocessor macro
+ definition.  These constructs are also known as @dfn{syntactic
+ whitespace} since they are usually ignored when scanning C code.}.
+ 
+ @item
+ No numeric argument was supplied to the command (i.e., it was typed as
+ normal, with no @kbd{C-u} prefix).
+ @end itemize
+ 
+ @menu
+ * Hanging Braces::
+ * Hanging Colons::
+ * Hanging Semicolons and Commas::
+ * Other Electric Commands::
+ * Clean-ups::
+ @end menu
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Hanging Braces, Hanging Colons, , Auto-newline Insertion
+ @comment node-name, next, previous, up
+ @subsection Hanging Braces
+ @cindex hanging braces
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @findex c-electric-brace
+ @findex electric-brace (c-)
+ @kindex @{
+ @kindex @}
+ 
+ When you type either an open or close brace (i.e., @address@hidden or 
@address@hidden),
+ the electric command @code{c-electric-brace} gets run.  This command has
+ two electric formatting behaviors.  First, it will perform some
+ reindentation of the line the brace was typed on, and second, it will
+ add various newlines before and/or after the typed brace.
+ Reindentation 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 also reindented.
+ 
+ The default in auto-newline mode is to insert newlines both before and
+ after a brace, but that can be controlled by the
+ @code{c-hanging-braces-alist} style variable.
+ 
+ @defopt c-hanging-braces-alist
+ @vindex hanging-braces-alist (c-)
+ 
+ This variable contains a mapping between syntactic symbols related to
+ braces, and a list of places to insert a newline.  The syntactic symbols
+ that are useful for this list are @code{brace-list-intro},
+ @code{statement-cont}, @code{inexpr-class-open},
+ @code{inexpr-class-close}, and all the @code{*-open} and @code{*-close}
+ symbols.  @xref{Syntactic Symbols}, for a more detailed description of
+ these syntactic symbols, except for @code{inexpr-class-open} and
+ @code{inexpr-class-close}, which aren't actual syntactic symbols.
+ 
+ The braces of anonymous inner classes in Java are given the special
+ symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that
+ they can be distinguished from the braces of normal address@hidden
+ braces of anonymous classes produce a combination of
+ @code{inexpr-class}, and @code{class-open} or @code{class-close} in
+ normal indentation analysis.}.
+ 
+ Note that the aggregate constructs in Pike mode, @samp{(@{}, 
@address@hidden)},
+ @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace
+ lists in this regard, even though they do for normal indentation
+ purposes.  It's currently not possible to set automatic newlines on
+ these constructs.
+ 
+ The value associated with each syntactic symbol in this association list
+ is called an @var{action}, which can be either a function or a list.
+ @xref{Custom Brace and Colon Hanging}, for a more detailed discussion of
+ using a function as a brace hanging @var{action}.
+ 
+ When the @var{action} is a list, it can contain any combination of the
+ symbols @code{before} and @code{after}, directing @ccmode{} 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:
+ 
+ @example
+ // here, open braces always `hang'
+ void spam( int i ) @{
+     if( i == 7 ) @{
+         dosomething(i);
+     @}
+ @}
+ @end example
+ 
+ When the list contains both @code{after} and @code{before}, the braces
+ will appear on a line by themselves, as shown by the close braces in the
+ above example.  The list can also be empty, in which case no newlines
+ are added either before or after the brace.
+ 
+ If a syntactic symbol is missing entirely from
+ @code{c-hanging-braces-alist}, it's treated in the same way as an
+ @var{action} with a list containing @code{before} and @code{after}, so
+ that braces by default end up on their own line.
+ 
+ For example, the default value of @code{c-hanging-braces-alist} is:
+ 
+ @example
+ ((brace-list-open)
+  (brace-entry-open)
+  (statement-cont)
+  (substatement-open after)
+  (block-close . c-snug-do-while)
+  (extern-lang-open after)
+  (inexpr-class-open after)
+  (inexpr-class-close before))
+ @end example
+ 
+ @noindent which says that @code{brace-list-open},
+ @code{brace-entry-open} and @address@hidden lists
+ inside statements, such as initializers for static array variables
+ inside functions in C, are recognized as @code{statement-cont}.  All
+ normal substatement blocks are recognized with other symbols.} 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},
+ @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang
+ on the right side, but subsequent text should follow on the next line.
+ The opposite holds for @code{inexpr-class-close} braces; they won't
+ hang, but the following text continues on the same line.  Here, in the
+ @code{block-close} entry, you also see an example of using a function as
+ an @var{action}.  In all other cases, braces are put on a line by
+ themselves.
+ @end defopt
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, 
Auto-newline Insertion
+ @comment node-name, next, previous, up
+ @subsection Hanging Colons
+ @cindex hanging colons
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Using a mechanism similar to brace hanging (@pxref{Hanging Braces}),
+ colons can also be made to hang using the style variable
+ @code{c-hanging-colons-alist}.
+ 
+ @defopt c-hanging-colons-alist
+ @vindex hanging-colons-alist (c-)
+ 
+ The syntactic symbols appropriate for this association list are:
+ @code{case-label}, @code{label}, @code{access-label},
+ @code{member-init-intro}, and @code{inher-intro}.  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.
+ 
+ In C++, double-colons are used as a scope operator but because these
+ colons always appear right next to each other, newlines before and after
+ them are controlled by a different mechanism, called @dfn{clean-ups} in
+ @ccmode{}.  @xref{Clean-ups}, for details.
+ @end defopt
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Hanging Semicolons and Commas, Other Electric Commands, Hanging 
Colons, Auto-newline Insertion
+ @comment node-name, next, previous, up
+ @subsection Hanging Semicolons and Commas
+ @cindex hanging semicolons
+ @cindex hanging commas
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Semicolons and commas are also electric in @ccmode{}, but since
+ these characters do not correspond directly to syntactic symbols, a
+ different mechanism is used to determine whether newlines should be
+ automatically inserted after these characters.  @xref{Customizing
+ Semicolons and Commas}, for details.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Other Electric Commands, Clean-ups, Hanging Semicolons and Commas, 
Auto-newline Insertion
+ @comment node-name, next, previous, up
+ @subsection Other Electric Commands
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ A few other keys also provide electric behavior, often only to reindent
+ the line.  Common to all of them is that they only reindent if used in
+ normal code (as opposed to in a string literal or comment), and
+ @code{c-syntactic-indentation} isn't @code{nil}.  They are:
+ 
+ @table @kbd
+ @item #
+ @kindex #
+ @findex c-electric-pound
+ @findex electric-pound (c-)
+ @vindex c-electric-pound-behavior
+ @vindex electric-pound-behavior (c-)
+ Pound (bound to @code{c-electric-pound}) is electric when typed as the
+ first non-whitespace character on a line and not within a macro
+ definition.  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 currently defined is @code{alignleft},
+ which tells this command to force the @samp{#} character into column
+ zero.  This is useful for entering preprocessor macro definitions.
+ 
+ Pound is not electric in AWK buffers, where @samp{#} starts a comment,
+ and is bound to @code{self-insert-command} like any typical printable
+ character.
+ 
+ @item *
+ @kindex *
+ @itemx /
+ @kindex /
+ @findex c-electric-star
+ @findex electric-star (c-)
+ @findex c-electric-slash
+ @findex electric-slash (c-)
+ Stars and slashes (bound to @code{c-electric-star} and
+ @code{c-electric-slash} respectively) are also electric under certain
+ circumstances.  If a @samp{*} is inserted as the second character of a C
+ style block comment on a comment-only line, then the comment delimiter
+ is indented as defined by @code{c-offsets-alist}.  A comment-only line
+ is defined as a line which contains only a comment, as in:
+ 
+ @example
+ @group
+ void spam( int i )
+ @{
+     // this is a comment-only line...
+     if( i == 7 )                // but this is not
+     @{
+         dosomething(i);
+     @}
+ @}
+ @end group
+ @end example
+ 
+ Likewise, if a @samp{/} is inserted as the second slash in a C++ style
+ line comment (also only on a comment-only line), then the line is
+ indented as defined by @code{c-offsets-alist}.
+ 
+ In AWK mode, @samp{*} and @samp{/} do not delimit comments and are
+ bound to @code{self-insert-command}.
+ 
+ @item <
+ @kindex <
+ @itemx >
+ @kindex >
+ @findex c-electric-lt-gt
+ @findex electric-lt-gt (c-)
+ Less-than and greater-than signs (bound to @code{c-electric-lt-gt}) are
+ electric, but only in C++ mode.  Hitting the second of two @kbd{<} or
+ @kbd{>} keys reindents the line if it is a C++ style stream operator.
+ 
+ @item (
+ @kindex (
+ @itemx )
+ @kindex )
+ @findex c-electric-paren
+ @findex electric-paren (c-)
+ The normal parenthesis characters @samp{(} and @samp{)} reindent the
+ current line.  This is useful for getting the closing parenthesis of an
+ argument list aligned automatically.
+ @end table
+ 
+ @deffn Command c-electric-continued-statement
+ @findex electric-continued-statement (c-)
+ 
+ Certain keywords, depending on language, are electric to cause
+ reindentation when they are preceded only by whitespace on the line.
+ The keywords are those that continue an earlier statement instead of
+ starting a new one: @code{else}, @code{while}, @code{catch} (only in C++
+ and Java) and @code{finally} (only in Java).
+ 
+ An example:
+ 
+ @example
+ @group
+ for (i = 0; i < 17; i++)
+   if (a[i])
+     res += a[i]->offset;
+ else
+ @end group
+ @end example
+ 
+ Here, the @code{else} should be indented like the preceding @code{if},
+ since it continues that statement. @ccmode{} will automatically reindent
+ it after the @code{else} has been typed in full, since it's not until
+ then it's possible to decide whether it's a new statement or a
+ continuation of the preceding @code{if}.
+ 
+ @vindex abbrev-mode
+ @findex abbrev-mode
+ @cindex Abbrev mode
+ @ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, emacs, The Emacs Editor})
+ to accomplish this. It's therefore turned on by default in all language
+ modes except IDL mode, since CORBA IDL doesn't have any statements.
+ @end deffn
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Clean-ups, , Other Electric Commands, Auto-newline Insertion
+ @comment node-name, next, previous, up
+ @subsection Clean-ups
+ @cindex clean-ups
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @dfn{Clean-ups} are mechanisms complementary to colon and brace hanging.
+ On the surface, it would seem that clean-ups overlap the functionality
+ provided by the @code{c-hanging-*-alist} variables.  Clean-ups are
+ however used to adjust code ``after-the-fact,'' i.e., to adjust the
+ whitespace in constructs after they are typed.
+ 
+ Most of the clean-ups are only applicable to counteract automatically
+ inserted newlines, and will therefore only have any effect if the
+ auto-newline minor mode is turned on.  Others will work all the time.
+ 
+ @defopt c-cleanup-list
+ @vindex cleanup-list (c-)
+ @cindex literal
+ 
+ You can configure @ccmode{}'s clean-ups by setting the style variable
+ @code{c-cleanup-list}, which is a list of clean-up symbols.  By default,
+ @ccmode{} cleans up only the @code{scope-operator} construct, which is
+ necessary for proper C++ support.  Note that clean-ups are only
+ performed when the construct does not occur within a literal
+ (@pxref{Auto-newline Insertion}), and when there is nothing but
+ whitespace appearing between the individual components of the construct.
+ @end defopt
+ 
+ These are the clean-ups that are only active in the auto-newline minor
+ mode:
+ 
+ @c TBD: Would like to use some sort of @deffoo here; @table indents a
+ @c bit too much in dvi output.
+ @table @code
+ @item brace-else-brace
+ Clean up @address@hidden 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
+ @group
+ void spam(int i)
+ @{
+     if( i==7 ) @{
+         dosomething();
+     @}
+     else
+     @{
+ @end group
+ @end example
+ 
+ @noindent
+ appears like this after the last open brace is typed:
+ 
+ @example
+ @group
+ void spam(int i)
+ @{
+     if( i==7 ) @{
+         dosomething();
+     @} else @{
+ @end group
+ @end example
+ 
+ @item brace-elseif-brace
+ Similar to the @code{brace-else-brace} clean-up, but this cleans up
+ @address@hidden else if (...) @{} constructs.  For example:
+ 
+ @example
+ @group
+ void spam(int i)
+ @{
+     if( i==7 ) @{
+         dosomething();
+     @}
+     else if( i==3 )
+     @{
+ @end group
+ @end example
+ 
+ @noindent
+ appears like this after the last open parenthesis is typed:
+ 
+ @example
+ @group
+ void spam(int i)
+ @{
+     if( i==7 ) @{
+         dosomething();
+     @} else if( i==3 )
+     @{
+ @end group
+ @end example
+ 
+ @noindent
+ and like this after the last open brace is typed:
+ 
+ @example
+ @group
+ void spam(int i)
+ @{
+     if( i==7 ) @{
+         dosomething();
+     @} else if( i==3 ) @{
+ @end group
+ @end example
+ 
+ @item brace-catch-brace
+ Analogous to @code{brace-elseif-brace}, but cleans up @address@hidden catch
+ (...) @{} in C++ and Java mode.
+ 
+ @item empty-defun-braces
+ Clean 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
+ @group
+ class Spam
+ @{
+ @}
+ @end group
+ @end example
+ 
+ @noindent
+ is transformed into this when the close brace is typed:
+ 
+ @example
+ @group
+ class Spam
+ @address@hidden
+ @end group
+ @end example
+ 
+ @item defun-close-semi
+ Clean up the terminating semicolon on top-level function or class
+ definitions when they follow a close brace.  Clean up occurs when the
+ semicolon is typed.  So for example, the following:
+ 
+ @example
+ @group
+ class Spam
+ @{
+ @}
+ ;
+ @end group
+ @end example
+ 
+ @noindent
+ is transformed into this when the semicolon is typed:
+ 
+ @example
+ @group
+ class Spam
+ @{
+ @};
+ @end group
+ @end example
+ 
+ @item list-close-comma
+ Clean up commas following braces in array and aggregate initializers.
+ Clean up occurs when the comma is typed.
+ 
+ @item scope-operator
+ Clean up double colons which may designate a C++ scope operator split
+ across multiple address@hidden C++ constructs introduce
+ ambiguous situations, so @code{scope-operator} clean-ups may not always
+ be correct.  This usually only occurs when scoped identifiers appear in
+ switch label tags.}.  Clean up occurs when the second colon is typed.
+ You will always want @code{scope-operator} in the @code{c-cleanup-list}
+ when you are editing C++ code.
+ @end table
+ 
+ The following clean-ups are always active when they occur on
+ @code{c-cleanup-list}, and are thus not affected by the auto-newline
+ minor mode:
+ 
+ @table @code
+ @item space-before-funcall
+ Insert a space between the function name and the opening parenthesis of
+ a function call.  This produces function calls in the style mandated by
+ the GNU coding standards, e.g., @samp{signal (SIGINT, SIG_IGN)} and
+ @samp{abort ()}.  Clean up occurs when the opening parenthesis is typed.
+ 
+ @item compact-empty-funcall
+ Clean up any space between the function name and the opening parenthesis
+ of a function call that has no arguments.  This is typically used
+ together with @code{space-before-funcall} if you prefer the GNU function
+ call style for functions with arguments but think it looks ugly when
+ it's only an empty parenthesis pair.  I.e., you will get @samp{signal
+ (SIGINT, SIG_IGN)}, but @samp{abort()}.  Clean up occurs when the
+ closing parenthesis is typed.
+ @end table
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Hungry-deletion of Whitespace, , Auto-newline Insertion, Minor Modes
+ @comment node-name, next, previous, up
+ @section Hungry-deletion of Whitespace
+ @cindex hungry-deletion
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Hungry deletion of whitespace, or as it more commonly called,
+ @dfn{hungry-delete mode}, is a simple feature that some people find
+ extremely useful.  In fact, you might find yourself wanting
+ hungry-delete in @strong{all} your editing modes!
+ 
+ @kindex DEL
+ @kindex C-d
+ 
+ In a nutshell, when hungry-delete mode is enabled, hitting the @kbd{DEL}
+ or @kbd{C-d} keys will consume all preceding or following whitespace,
+ including newlines and tabs.  This can really cut down on the number of
+ times you have to hit these keys if, for example, you made a mistake on
+ the preceding line.
+ 
+ @deffn Command c-electric-backspace
+ @findex electric-backspace (c-)
+ This command is run by default when you hit the @kbd{DEL} key.  It
+ deletes any amount of whitespace in the backwards direction if
+ hungry-delete mode is enabled.  When it's disabled, or when used with
+ a prefix argument or in a literal (@pxref{Auto-newline Insertion}),
+ the function contained in the @code{c-backspace-function} variable is
+ called with the prefix argument.
+ @end deffn
+ 
+ @defvar c-backspace-function
+ @vindex backspace-function (c-)
+ @findex backward-delete-char-untabify
+ Hook that gets called by @code{c-electric-backspace} when it doesn't
+ do an ``electric'' deletion of the preceding whitespace.  The default
+ value is @code{backward-delete-char-untabify}.
+ @end defvar
+ 
+ @deffn Command c-electric-delete-forward
+ @findex electric-delete-forward (c-)
+ This function, which is bound to @kbd{C-d} by default, works just like
+ @code{c-electric-backspace} but in the forward direction.  When it
+ doesn't do an ``electric'' deletion of the following whitespace, it
+ calls the function in @code{c-delete-function} with its prefix
+ argument.
+ @end deffn
+ 
+ @defvar c-delete-function
+ @vindex delete-function (c-)
+ @findex delete-char
+ Hook that gets called by @code{c-electric-delete-forward} when it
+ doesn't do an ``electric'' deletion of the following whitespace.  The
+ default value is @code{delete-char}.
+ @end defvar
+ 
+ Above we have only talked about the @kbd{DEL} and @kbd{C-d} key events,
+ without connecting them to the physical keys commonly known as
+ @key{Backspace} and @key{Delete}.  The default behavior of those two
+ depends on the flavor of (X)Emacs you are using.
+ 
+ @findex c-electric-delete
+ @findex electric-delete (c-)
+ @vindex delete-key-deletes-forward
+ 
+ In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to
+ @code{c-electric-backspace} and the @key{Delete} key is bound to
+ @code{c-electric-delete}.  You control the direction it deletes in by
+ setting the variable @code{delete-key-deletes-forward}, a standard
+ XEmacs variable.  When this variable is address@hidden,
+ @code{c-electric-delete} will do forward deletion with
+ @code{c-electric-delete-forward}, otherwise it does backward deletion
+ with @code{c-electric-backspace}.
+ 
+ In other Emacs versions, @ccmode{} doesn't bind either @key{Backspace}
+ or @key{Delete}.  In XEmacs 19 and Emacs prior to 21 that means that
+ it's up to you to fix them.  Emacs 21 automatically binds them as
+ appropriate to @kbd{DEL} and @kbd{C-d}.
+ 
+ Another way to use hungry deletion is to bind
+ @code{c-hungry-backspace} and @code{c-hungry-delete-forward} directly
+ to keys, and not use the mode toggling.  For example @kbd{C-c C-d} and
+ @kbd{C-c DEL} to match plain @kbd{C-d} and @kbd{DEL},
+ 
+ @example
+ (add-hook
+  'c-mode-common-hook
+  (lambda ()
+    (define-key c-mode-base-map
+                [?\C-c ?\d] 'c-hungry-backspace)
+    (define-key c-mode-base-map
+                [?\C-c ?\C-d] 'c-hungry-delete-forward)))
+ @end example
+ 
+ @deffn Command c-hungry-backspace
+ @findex hungry-backspace (c-)
+ Delete any amount of whitespace in the backwards direction (regardless
+ whether hungry-delete mode is enabled or not).
+ @end deffn
+ 
+ @deffn Command c-hungry-delete-forward
+ @findex hungry-delete-forward (c-)
+ Delete any amount of whitespace in the forward direction (regardless
+ whether hungry-delete mode is enabled or not).
+ @end deffn
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Text Filling and Line Breaking, Macro Handling, Minor Modes, Top
+ @comment node-name, next, previous, up
+ @chapter Text Filling and Line Breaking
+ @cindex text filling
+ @cindex line breaking
+ @cindex comment handling
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Since there's a lot of normal text in comments and string literals,
+ @ccmode{} provides features to edit these like in text mode.  The goal
+ is to do it as seamlessly as possible, i.e., you can use auto fill mode,
+ sentence and paragraph movement, paragraph filling, adaptive filling etc
+ wherever there's a piece of normal text without having to think much
+ about it.  @ccmode{} should keep the indentation, fix the comment line
+ decorations, and so on, for you.  It does that by hooking in on the
+ different line breaking functions and tuning relevant variables as
+ necessary.
+ 
+ @vindex c-comment-prefix-regexp
+ @vindex comment-prefix-regexp (c-)
+ @cindex comment line prefix
+ @vindex comment-start
+ @vindex comment-end
+ @vindex comment-start-skip
+ @vindex paragraph-start
+ @vindex paragraph-separate
+ @vindex paragraph-ignore-fill-prefix
+ @vindex adaptive-fill-mode
+ @vindex adaptive-fill-regexp
+ @vindex adaptive-fill-first-line-regexp
+ To make Emacs recognize comments and treat text in them as normal
+ paragraphs, @ccmode{} makes several standard
+ address@hidden@code{comment-start}, @code{comment-end},
+ @code{comment-start-skip}, @code{paragraph-start},
+ @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix},
+ @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and
+ @code{adaptive-fill-first-line-regexp}.} buffer local and modifies them
+ according to the language syntax and the comment line prefix.
+ 
+ @defopt c-comment-prefix-regexp
+ @vindex comment-prefix-regexp (c-)
+ This style variable contains the regexp used to recognize the
+ @dfn{comment line prefix}, which is the line decoration that starts
+ every line in a comment.  The default is @samp{//+\\|\\**}, which
+ matches C++ style line comments like
+ 
+ @example
+ // blah blah
+ @end example
+ 
+ @noindent
+ with two or more slashes in front of them, and C style block comments
+ like
+ 
+ @example
+ @group
+ /*
+  * blah blah
+  */
+ @end group
+ @end example
+ 
+ @noindent
+ with zero or more stars at the beginning of every line.  If you change
+ this variable, please make sure it still matches the comment starter
+ (i.e., @code{//}) of line comments @emph{and} the line prefix inside
+ block comments.
+ 
+ @findex c-setup-paragraph-variables
+ @findex setup-paragraph-variables (c-)
+ Also note that since @ccmode{} uses the value of
+ @code{c-comment-prefix-regexp} to set up several other variables at mode
+ initialization, there won't be any effect if you just change it inside a
+ @ccmode{} buffer.  You need to call the command
+ @code{c-setup-paragraph-variables} too, to update those other variables with
+ the new value.  That's also the case if you modify this variable in a
+ mode hook, since @ccmode{} sets up all variables before calling them.
+ @end defopt
+ 
+ @findex auto-fill-mode
+ @cindex Auto Fill mode
+ @cindex paragraph filling
+ Line breaks are by default handled (almost) the same regardless whether
+ they are made by auto fill mode (@pxref{Auto Fill,,, emacs, The Emacs
+ Editor}), paragraph filling (e.g., with @kbd{M-q}), or explicitly with
+ @kbd{M-j} or similar methods.  In string literals, the new line gets the
+ same indentation as the previous nonempty line (may be changed with the
+ @code{string} syntactic symbol).  In comments, @ccmode{} uses
+ @code{c-comment-prefix-regexp} to adapt the line prefix from the other
+ lines in the comment.
+ 
+ @vindex adaptive-fill-mode
+ @cindex Adaptive Fill mode
+ @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, The
+ Emacs Editor}) to make Emacs correctly keep the line prefix when filling
+ paragraphs.  That also makes Emacs preserve the text indentation
+ @emph{inside} the comment line prefix.  e.g., in the following comment,
+ both paragraphs will be filled with the left margins of the texts kept
+ intact:
+ 
+ @example
+ @group
+ /* Make a balanced b-tree of the nodes in the incoming
+  * stream.  But, to quote the famous words of Donald E.
+  * Knuth,
+  *
+  *     Beware of bugs in the above code; I have only
+  *     proved it correct, not tried it.
+  */
+ @end group
+ @end example
+ 
+ @findex c-setup-filladapt
+ @findex setup-filladapt (c-)
+ @findex filladapt-mode
+ @vindex filladapt-mode
+ @cindex Filladapt mode
+ It's also possible to use other adaptive filling packages, notably Kyle
+ E. Jones' Filladapt address@hidden's available from
+ @uref{http://www.wonderworks.com/}.  As of version 2.12, it does however
+ lack a feature that makes it work suboptimally when
+ @code{c-comment-prefix-regexp} matches the empty string (which it does
+ by default).  A patch for that is available from
+ @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},
+ which handles things like bulleted lists nicely.  There's a convenience
+ function @code{c-setup-filladapt} that tunes the relevant variables in
+ Filladapt for use in @ccmode{}.  Call it from a mode hook, e.g., with
+ something like this in your @file{.emacs}:
+ 
+ @example
+ (defun my-c-mode-common-hook ()
+   (c-setup-filladapt)
+   (filladapt-mode 1))
+ (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+ @end example
+ 
+ @defopt c-block-comment-prefix
+ @vindex block-comment-prefix (c-)
+ @vindex c-comment-continuation-stars
+ @vindex comment-continuation-stars (c-)
+ Normally the comment line prefix inserted for a new line inside a
+ comment is deduced from other lines in it.  However there's one
+ situation when there's no hint about what the prefix should look like,
+ namely when a block comment is broken for the first time.  This style
+ address@hidden versions before 5.26, this variable was called
+ @code{c-comment-continuation-stars}.  As a compatibility measure,
+ @ccmode{} still uses the value on that variable if it's set.} is used
+ then as the comment prefix.  It defaults to @samp{*
+ address@hidden, this default setting of
+ @code{c-block-comment-prefix} typically gets overriden by the default
+ style @code{gnu}, which sets it to blank.  You can see the line
+ splitting effect described here by setting a different style,
+ e.g. @code{k&r} @xref{Choosing a Style}}, which makes a comment
+ 
+ @example
+ /* Got O(n^2) here, which is a Bad Thing. */
+ @end example
+ 
+ @noindent
+ break into
+ 
+ @example
+ @group
+ /* Got O(n^2) here,
+  * which is a Bad Thing. */
+ @end group
+ @end example
+ 
+ Note that it won't work to adjust the indentation by putting leading
+ spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the
+ normal indentation engine to indent the line.  Thus, the right way to
+ fix the indentation is by customizing the @code{c} syntactic symbol.  It
+ defaults to @code{c-lineup-C-comments}, which handles the indentation of
+ most common comment styles, see @ref{Indentation Functions}.
+ @end defopt
+ 
+ @defopt c-ignore-auto-fill
+ @vindex ignore-auto-fill (c-)
+ When auto fill mode is enabled, @ccmode{} can selectively ignore it
+ depending on the context the line break would occur in, e.g., to never
+ break a line automatically inside a string literal.  This variable
+ takes a list of symbols for the different contexts where auto-filling
+ never should occur:
+ 
+ @table @code
+ @item string
+ Inside a string or character literal.
+ @item c
+ Inside a C style block comment.
+ @item c++
+ Inside a C++ style line comment.
+ @item cpp
+ Inside a preprocessor directive.
+ @item code
+ Anywhere else, i.e., in normal code.
+ @end table
+ 
+ By default, @code{c-ignore-auto-fill} is set to @code{'(string cpp
+ code)}, which means that auto-filling only occurs in comments when
+ auto-fill mode is activated.  In literals, it's often desirable to have
+ explicit control over newlines.  In preprocessor directives, the
+ necessary @samp{\} escape character before the newline is not
+ automatically inserted, so an automatic line break would produce invalid
+ code.  In normal code, line breaks are normally dictated by some logical
+ structure in the code rather than the last whitespace character, so
+ automatic line breaks there will produce poor results in the current
+ implementation.
+ @end defopt
+ 
+ The commands that do the actual work follow.
+ 
+ @table @asis
+ @item @kbd{M-q} (@code{c-fill-paragraph})
+ @kindex M-q
+ @findex c-fill-paragraph
+ @findex fill-paragraph (c-)
+ @cindex Javadoc markup
+ @cindex Pike autodoc markup
+ This is the replacement for @code{fill-paragraph} in @ccmode{}
+ buffers. It's used to fill multiline string literals and both block and
+ line style comments.  In Java buffers, the Javadoc markup words are
+ recognized as paragraph starters.  The line oriented Pike autodoc markup
+ words are recognized in the same way in Pike mode.
+ 
+ The function keeps the comment starters and enders of block comments as
+ they were before the filling.  This means that a comment ender on the
+ same line as the paragraph being filled will be filled with the
+ paragraph, and one on a line by itself will stay as it is.  The comment
+ starter is handled address@hidden means that the variables
+ @code{c-hanging-comment-starter-p} and @code{c-hanging-comment-ender-p},
+ which controlled this behavior in earlier versions of @ccmode{}, are now
+ obsolete.}.
+ 
+ @item @kbd{M-j} (@code{c-indent-new-comment-line})
+ @kindex M-j
+ @findex c-indent-new-comment-line
+ @findex indent-new-comment-line (c-)
+ This is the replacement for @code{indent-new-comment-line}.  It breaks
+ the line at point and indents the new line like the current one.
+ 
+ @vindex comment-multi-line
+ If inside a comment and @code{comment-multi-line} is address@hidden, the
+ indentation and line prefix are preserved.  If inside a comment and
+ @code{comment-multi-line} is @code{nil}, a new comment of the same type
+ is started on the next line and indented as appropriate for comments.
+ 
+ Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at
+ startup.  The reason is that @kbd{M-j} could otherwise produce sequences
+ of single line block comments for texts that should logically be treated
+ as one comment, and the rest of the paragraph handling code
+ (e.g., @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to
+ inconsistent behavior.
+ 
+ @item @kbd{M-x c-context-line-break}
+ @findex c-context-line-break
+ @findex context-line-break (c-)
+ This is a function that works like @code{indent-new-comment-line} in
+ comments and @code{newline-and-indent} elsewhere, thus combining those
+ two in a way that uses each one in the context it's best suited for.
+ I.e., in comments the comment line prefix and indentation is kept for
+ the new line, and in normal code it's indented according to context by
+ the indentation engine.
+ 
+ In macros it acts like @code{newline-and-indent} but additionally
+ inserts and optionally aligns the line ending backslash so that the
+ macro remains unbroken.  @xref{Macro Handling}, for details about the
+ backslash alignment.
+ 
+ It's not bound to a key by default, but it's intended to be used on the
+ @kbd{RET} key.  If you like the behavior of @code{newline-and-indent} on
+ @kbd{RET}, you should consider switching to this function.
+ 
+ @item @kbd{M-x c-context-open-line}
+ @findex c-context-open-line
+ @findex context-open-line (c-)
+ This is to @kbd{C-o} (@kbd{M-x open-line}) as
+ @code{c-context-line-break} is to @kbd{RET}.  I.e., it works just like
+ @code{c-context-line-break} but leaves the point before the inserted
+ line break.
+ @end table
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Macro Handling, Font Locking, Text Filling and Line Breaking, Top
+ @comment node-name, next, previous, up
+ @chapter Macro Handling
+ @cindex macros
+ @cindex preprocessor directives
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Preprocessor directives are handled as syntactic whitespace from other
+ code, i.e., they can be interspersed anywhere without affecting the
+ syntactic analysis, just like comments.
+ 
+ The code inside macro definitions is still analyzed syntactically so
+ that you get relative indentation there just as you'd get if the same
+ code was outside a macro.  However, since there is no hint about the
+ syntactic context, i.e., whether the macro expands to an expression, to some
+ statements, or perhaps to whole functions, the syntactic recognition can be
+ wrong.  @ccmode{} manages to figure it out correctly most of the time,
+ though.  @xref{Syntactic Symbols}, for details about the indentation.
+ 
+ @defopt c-syntactic-indentation-in-macros
+ @vindex syntactic-indentation-in-macros (c-)
+ Enable syntactic analysis inside macros, which is the default.  If this
+ is @code{nil}, all lines inside macro definitions are analyzed as
+ @code{cpp-macro-cont}.
+ @end defopt
+ 
+ @ccmode{} provides some tools to help keep the line continuation
+ backslashes in macros neat and tidy:
+ 
+ @table @asis
+ @item @kbd{C-c C-\} (@code{c-backslash-region})
+ @kindex C-c C-\
+ @findex c-backslash-region
+ @findex backslash-region (c-)
+ This function inserts and aligns or deletes the end-of-line backslashes
+ in the current region.
+ 
+ With no prefix argument, it inserts any missing backslashes and aligns
+ them according to the @code{c-backslash-column} and
+ @code{c-backslash-max-column} variables.  With a prefix argument, it
+ deletes any backslashes.
+ 
+ The function does not modify blank lines at the start of the region.  If
+ the region ends at the start of a line, it always deletes the backslash
+ (if any) at the end of the previous line.
+ @end table
+ 
+ @defopt c-backslash-column
+ @vindex backslash-column (c-)
+ @defoptx c-backslash-max-column
+ @vindex backslash-max-column (c-)
+ These variables control the alignment columns for line continuation
+ backslashes in multiline macros.  They are used by the functions that
+ automatically insert or align such backslashes,
+ e.g., @code{c-backslash-region} and @code{c-context-line-break}.
+ 
+ @code{c-backslash-column} specifies the minimum column for the
+ backslashes.  If any line in the macro exceeds it then the next tab
+ stop from that line is used as the alignment column for all the
+ backslashes, so that they remain in a single column.  However, if some
+ lines exceed @code{c-backslash-max-column} then the backslashes in the
+ rest of the macro will be kept at that column, so that the
+ lines which are too long ``stick out'' instead.
+ @end defopt
+ 
+ @defopt c-auto-align-backslashes
+ @vindex auto-align-backslashes (c-)
+ Align automatically inserted line continuation backslashes if
+ address@hidden  When line continuation backslashes are inserted
+ automatically for line breaks in multiline macros, e.g., by
+ @code{c-context-line-break}, they are aligned with the other backslashes
+ in the same macro if this flag is set.  Otherwise the inserted
+ backslashes are preceded by a single space.
+ @end defopt
+ 
+ The recommended line breaking function, @code{c-context-line-break}
+ (@pxref{Text Filling and Line Breaking}), is especially nice if you edit
+ multiline macros frequently.  When used inside a macro, it automatically
+ inserts and adjusts the mandatory backslash at the end of the line to
+ keep the macro together, and it leaves the point at the right
+ indentation column for the code.  Thus you can write code inside macros
+ almost exactly as you can elsewhere, without having to bother with the
+ trailing backslashes.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Font Locking, Commands, Macro Handling, Top
+ @comment node-name, next, previous, up
+ @chapter Font Locking
+ @cindex font locking
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @strong{Note:} The font locking in AWK mode is currently not integrated
+ with the rest of @ccmode{}, so this section does not apply there.
+ @xref{AWK Mode Font Locking}, instead.
+ 
+ @cindex Font Lock mode
+ 
+ @ccmode{} provides font locking for its supported languages by supplying
+ patterns for use with Font Lock mode.  This means that you get distinct
+ faces on the various syntactic parts such as comments, strings, keywords
+ and types, which is very helpful in telling them apart at a glance and
+ discovering syntactic errors.  @xref{Font Lock,,, emacs, The Emacs
+ Editor}, for ways to enable font locking in @ccmode{} buffers.
+ 
+ @menu
+ * Font Locking Preliminaries::
+ * Faces::
+ * Documentation Comments::
+ @end menu
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Font Locking Preliminaries, Faces, , Font Locking
+ @comment node-name, next, previous, up
+ @section Font Locking Preliminaries
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ The font locking for most of the @ccmode{} languages were provided
+ directly by the Font Lock package prior to version 5.30 of @ccmode{}.
+ In the transition to @ccmode{} the patterns have been reworked
+ completely and are applied uniformly across all the languages except AWK
+ mode, just like the indentation rules (although each language still has
+ some pecularities of its own, of course).  Since the languages
+ previously had completely separate font locking patterns, this means
+ that it's a bit different in most languages now.
+ 
+ The main goal for the font locking in @ccmode{} is accuracy, to provide
+ a dependable aid in recognizing the various constructs.  Some, like
+ strings and comments, are easy to recognize while others like
+ declarations and types can be very tricky.  @ccmode{} can go to great
+ lengths to recognize declarations and casts correctly, especially when
+ the types aren't recognized by standard patterns.  This is a fairly
+ demanding analysis which can be slow on older hardware, and it can
+ therefore be disabled by choosing a lower decoration level with the
+ variable @code{font-lock-maximum-decoration}.
+ 
+ @vindex font-lock-maximum-decoration
+ 
+ The decoration levels are used as follows:
+ 
+ @enumerate
+ @comment 1
+ @item
+ Minimal font locking: Fontify only comments, strings and preprocessor
+ directives (in the languages that use cpp).
+ 
+ @comment 2
+ @item
+ Fast normal font locking: In addition to level 1, fontify keywords,
+ simple types and declarations that are easy to recognize.  The variables
+ @code{*-font-lock-extra-types} (where @samp{*} is the name of the
+ language) are used to recognize types (see below).  Documentation
+ comments like Javadoc are fontified according to
+ @code{c-doc-comment-style} (@pxref{Documentation Comments}).
+ 
+ Use this if you think the font locking is too slow.  It's the closest
+ corresponding level to level 3 in the old font lock patterns.
+ 
+ @comment 3
+ @item
+ Accurate normal font locking: Like level 2 but uses a different approach
+ that can recognize types and declarations much more accurately.  The
+ @code{*-font-lock-extra-types} variables are still used, but user
+ defined types are recognized correctly anyway in most cases.  Therefore
+ those variables should be fairly restrictive and not contain patterns
+ that are uncertain.
+ 
+ @cindex Lazy Lock mode
+ @cindex Just-in-time Lock mode
+ 
+ This level is designed for fairly modern hardware and a font lock
+ support mode like Lazy Lock or Just-in-time Lock mode that only
+ fontifies the parts that are actually shown.
+ @end enumerate
+ 
+ @cindex user defined types
+ @cindex types, user defined
+ 
+ Since user defined types are hard to recognize you can provide
+ additional regexps to match those you use:
+ 
+ @defopt c-font-lock-extra-types
+ @defoptx c++-font-lock-extra-types
+ @defoptx objc-font-lock-extra-types
+ @defoptx java-font-lock-extra-types
+ @defoptx idl-font-lock-extra-types
+ @defoptx pike-font-lock-extra-types
+ For each language there's a variable @code{*-font-lock-extra-types},
+ where @samp{*} stands for the language in question.  It contains a list
+ of regexps that matches identifiers that should be recognized as types,
+ e.g., @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}
+ as is customary in C code.  Each regexp should not match more than a
+ single identifier.
+ 
+ The default values contain regexps for many types in standard runtime
+ libraries that are otherwise difficult to recognize, and patterns for
+ standard type naming conventions like the @samp{_t} suffix in C and C++.
+ Java, Objective-C and Pike have as a convention to start class names
+ with capitals, so there are patterns for that in those languages.
+ 
+ Despite the names of these variables, they are not only used for
+ fontification but in other places as well where @ccmode{} needs to
+ recognize types.
+ @end defopt
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Faces, Documentation Comments, Font Locking Preliminaries, Font 
Locking
+ @comment node-name, next, previous, up
+ @section Faces
+ @cindex faces
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @ccmode{} attempts to use the standard faces for programming languages
+ in accordance with their intended purposes as far as possible.  No extra
+ faces are currently provided, with the exception of a replacement face
+ @code{c-invalid-face} for emacsen that don't provide
+ @code{font-lock-warning-face}.
+ 
+ @itemize @bullet
+ @item
+ @vindex font-lock-comment-face
+ Normal comments are fontified in @code{font-lock-comment-face}.
+ 
+ @item
+ @vindex font-lock-doc-face
+ @vindex font-lock-doc-string-face
+ @vindex font-lock-comment-face
+ Comments that are recognized as documentation (@pxref{Documentation
+ Comments}) get @code{font-lock-doc-face} (Emacs) or
+ @code{font-lock-doc-string-face} (XEmacs) if those faces exist.  If they
+ don't then @code{font-lock-comment-face} is used.
+ 
+ @item
+ @vindex font-lock-string-face
+ String and character literals are fontified in
+ @code{font-lock-string-face}.
+ 
+ @item
+ @vindex font-lock-keyword-face
+ Keywords are fontified with @code{font-lock-keyword-face}.
+ 
+ @item
+ @vindex font-lock-function-name-face
+ @code{font-lock-function-name-face} is used for function names in
+ declarations and definitions, and classes in those contexts.  It's also
+ used for preprocessor defines with arguments.
+ 
+ @item
+ @vindex font-lock-variable-name-face
+ Variables in declarations and definitions, and other identifiers in such
+ variable contexts, get @code{font-lock-variable-name-face}.  It's also
+ used for preprocessor defines without arguments.
+ 
+ @item
+ @vindex font-lock-constant-face
+ @vindex font-lock-reference-face
+ Builtin constants are fontified in @code{font-lock-constant-face} if it
+ exists, @code{font-lock-reference-face} otherwise.  As opposed to the
+ preceding two faces, this is used on the names in expressions, and it's
+ not used in declarations, even if there happen to be a @samp{const} in
+ them somewhere.
+ 
+ @item
+ @vindex font-lock-type-face
+ @code{font-lock-type-face} is put on types (both predefined and user
+ defined) and classes in type contexts.
+ 
+ @item
+ @vindex font-lock-constant-face
+ @vindex font-lock-reference-face
+ Label identifiers get @code{font-lock-constant-face} if it exists,
+ @code{font-lock-reference-face} otherwise.
+ 
+ @item
+ Name qualifiers and identifiers for scope constructs are fontified like
+ labels.
+ 
+ @item
+ Special markup inside documentation comments are also fontified like
+ labels.
+ 
+ @item
+ @vindex font-lock-preprocessor-face
+ @vindex font-lock-builtin-face
+ @vindex font-lock-reference-face
+ Preprocessor directives get @code{font-lock-preprocessor-face} if it
+ exists (i.e., XEmacs).  In Emacs they get @code{font-lock-builtin-face}
+ or @code{font-lock-reference-face}, for lack of a closer equivalent.
+ 
+ @item
+ @vindex font-lock-warning-face
+ @vindex c-invalid-face
+ @vindex invalid-face (c-)
+ Some kinds of syntactic errors are fontified with
+ @code{font-lock-warning-face} in Emacs.  In older XEmacs versions
+ there's no corresponding standard face, so there a special
+ @code{c-invalid-face} is used, which is defined to stand out sharply by
+ default.
+ 
+ Note that it's not used for @samp{#error} or @samp{#warning} directives,
+ since those aren't syntactic errors in themselves.
+ @end itemize
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Documentation Comments, , Faces, Font Locking
+ @comment node-name, next, previous, up
+ @section Documentation Comments
+ @cindex documentation comments
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ There are various tools to supply documentation in the source as
+ specially structured comments, e.g., the standard Javadoc tool in Java.
+ @ccmode{} provides an extensible mechanism to fontify such comments and
+ the special markup inside them.
+ 
+ @defopt c-doc-comment-style
+ @vindex doc-comment-style (c-)
+ This is a style variable that specifies which documentation comment
+ style to recognize, e.g., @code{javadoc} for Javadoc comments.
+ 
+ The value may also be a list of styles, in which case all of them are
+ recognized simultaneously (presumably with markup cues that don't
+ conflict).
+ 
+ The value may also be an association list to specify different comment
+ styles for different languages.  The symbol for the major mode is then
+ looked up in the alist, and the value of that element is interpreted as
+ above if found.  If it isn't found then the symbol `other' is looked up
+ and its value is used instead.
+ 
+ Note that @ccmode{} uses this variable to set other variables that
+ handle fontification etc.  That's done at mode initialization or when
+ you switch to a style which sets this variable.  Thus, if you change it
+ in some other way, e.g., interactively in a CC Mode buffer, you will need
+ to do @kbd{M-x java-mode} (or whatever mode you're currently using) to
+ reinitialize.
+ 
+ @findex c-setup-doc-comment-style
+ @findex setup-doc-comment-style (c-)
+ Note also that when @ccmode{} starts up, the other variables are
+ modified before the mode hooks are run.  If you change this variable in
+ a mode hook, you have to call @code{c-setup-doc-comment-style}
+ afterwards to redo that work.
+ @end defopt
+ 
+ @ccmode{} currently provides handing of the following doc comment
+ styles:
+ 
+ @table @code
+ @item javadoc
+ @cindex Javadoc markup
+ Javadoc comments, the standard tool in Java.
+ 
+ @item autodoc
+ @cindex Pike autodoc markup
+ For Pike autodoc markup, the standard in Pike.
+ @end table
+ 
+ The above is by no means complete.  If you'd like to see support for
+ other doc comment styles, please let us know (@pxref{Mailing Lists and
+ Submitting Bug Reports}).
+ 
+ You can also write your own doc comment fontification support to use
+ with @code{c-doc-comment-style}: Supply a variable or function
+ @code{*-font-lock-keywords} where @samp{*} is the name you want to use
+ in @code{c-doc-comment-style}.  If it's a variable, it's prepended to
+ @code{font-lock-keywords}.  If it's a function, it's called at mode
+ initialization and the result is prepended.  For an example, see
+ @code{javadoc-font-lock-keywords} in @file{cc-fonts.el}.
+ 
+ If you add support for another doc comment style, please consider
+ contributing it --- send a note to @email{bug-cc-mode@@gnu.org}.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Commands, Customizing Indentation, Font Locking, Top
+ @comment node-name, next, previous, up
+ @chapter Commands
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @menu
+ * Indentation Commands::
+ * Movement Commands::
+ * Other Commands::
+ @end menu
+ 
+ See also @ref{Text Filling and Line Breaking} and @ref{Macro Handling},
+ for commands concerning those bits.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Indentation Commands, Movement Commands, , Commands
+ @comment node-name, next, previous,up
+ @section Indentation Commands
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ The following list of commands reindent C constructs.  Note that when
+ you change your coding style, either interactively or through some other 
+ means, your file does @emph{not} automatically get reindented.  You
+ will need to execute one of the following commands to see the effects of 
+ your changes.
+ 
+ @cindex GNU indent program
+ Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
+ only affect how on-the-fly code is formatted.  Changing the
+ ``hanginess'' of a brace and then reindenting, will not move the brace
+ to a different line.  For this, you're better off getting an external
+ program like GNU @code{indent}, which will rearrange brace location,
+ among other things.
+ 
+ Reindenting large sections of code can take a long time.  When
+ @ccmode{} reindents a region of code, it is essentially equivalent to
+ hitting @kbd{TAB} on every line of the region.
+ 
+ These commands are useful when indenting code:
+ 
+ @table @asis
+ @item @kbd{TAB} (@code{c-indent-command})
+ @kindex TAB
+ @findex c-indent-command
+ @findex indent-command (c-)
+ Indents the current line.  The actual behavior is controlled by several
+ variables, described below.  See @code{c-tab-always-indent},
+ @code{c-insert-tab-function}, and @code{indent-tabs-mode}.  With a
+ numeric argument, this command rigidly indents the region, preserving
+ the relative indentation among the lines.
+ 
+ @item @kbd{C-M-q} (@code{c-indent-exp})
+ @kindex C-M-q
+ @findex c-indent-exp
+ @findex indent-exp (c-)
+ Indent an entire balanced brace or parenthesis expression.  Note that
+ point must be on the opening brace or parenthesis of the expression you
+ want to indent.
+ 
+ @item @kbd{C-c C-q} (@code{c-indent-defun})
+ @kindex C-c C-q
+ @findex c-indent-defun
+ @findex indent-defun (c-)
+ Indents the entire top-level function, class or macro definition
+ encompassing point.  It leaves point unchanged.  This function can't be
+ used to reindent a nested brace construct, such as a nested class or
+ function, or a Java method.  The top-level construct being reindented
+ must be complete, i.e., it must have both a beginning brace and an ending
+ brace.
+ 
+ @item @kbd{C-M-\} (@code{indent-region})
+ @kindex C-M-\
+ @findex indent-region
+ Indents an arbitrary region of code.  This is a standard Emacs command,
+ tailored for C code in a @ccmode{} buffer.  Note, of course, that point
+ and mark must delineate the region you want to indent.
+ 
+ @item @kbd{M-;} (@code{indent-for-comment})
+ @kindex M-;
+ @findex indent-for-comment
+ Insert a comment at the end of the current line, if none is there already.
+ Then reindent the comment according to the variables
+ @code{c-indent-comment-alist}, @code{c-indent-comments-syntactically-p}
+ and @code{comment-column}.  Then position the point after the comment
+ starter.  This is a standard Emacs command, but @ccmode{} enhances it a
+ bit with two variables:
+ 
+ @defopt c-indent-comment-alist
+ @vindex indent-comment-alist (c-)
+ @vindex comment-column
+ This style variable allows you to control which column @kbd{M-;}
+ indents the comment to, depending on the preceding code and the
+ indentation of a similar comment on the preceding line, if there is
+ any.  It is an association list that maps different types of lines to
+ actions describing how they should be handled.  If a certain line type
+ isn't present on the list then the line is indented to the column
+ specified by @code{comment-column}.  See the documentation string for
+ @code{c-indent-comment-alist} for a full description of the available
+ line types and actions (use @kbd{C-h v c-indent-comment-alist}).
+ @end defopt
+ 
+ @defopt c-indent-comments-syntactically-p
+ @vindex indent-comments-syntactically-p (c-)
+ Normally, when this variable is @code{nil}, @kbd{M-;} will indent
+ comment-only lines according to @code{c-indent-comment-alist}, just as
+ it does with lines where other code precede the comments.  However, if
+ you want it to act just like @kbd{TAB} for comment-only lines you can
+ get that by setting @code{c-indent-comments-syntactically-p} to
+ address@hidden
+ 
+ If @code{c-indent-comments-syntactically-p} is address@hidden then
+ @code{c-indent-comment-alist} won't be consulted at all for comment-only
+ lines.
+ @end defopt
+ 
+ @item @kbd{C-M-h} (@code{c-mark-function})
+ @kindex C-M-h
+ @findex c-mark-function
+ @findex mark-function (c-)
+ While not strictly an indentation command, this is useful for marking
+ the current top-level function or class definition as the current
+ region.  As with @code{c-indent-defun}, this command operates on
+ top-level constructs, and can't be used to mark say, a Java method.
+ @end table
+ 
+ These variables are also useful when indenting code:
+ 
+ @defopt c-tab-always-indent
+ @vindex tab-always-indent (c-)
+ @kindex TAB
+ @cindex literal
+ This variable controls how @kbd{TAB} (@code{c-indent-command})
+ operates.  When it is @code{t}, @kbd{TAB} always indents the current
+ line.  When it is @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 some whitespace is inserted.  If this variable is
+ some other value (not @code{nil} or @code{t}), then some whitespace is
+ inserted only within strings and comments (literals), but the line is
+ always reindented.
+ @end defopt
+ 
+ @defopt c-insert-tab-function
+ @vindex insert-tab-function (c-)
+ @findex tab-to-tab-stop
+ When ``some whitespace'' is inserted as described above, what actually
+ happens is that the function stored in @code{c-insert-tab-function} is
+ called.  Normally, this just inserts a real tab character, or the
+ equivalent number of spaces, depending on @code{indent-tabs-mode}.
+ Some people, however, set @code{c-insert-tab-function} to
+ @code{tab-to-tab-stop} so as to get hard tab stops when indenting.
+ @end defopt
+ 
+ @defopt indent-tabs-mode
+ This is a standard Emacs variable that controls how line indentation
+ is composed.  When it's address@hidden, tabs can be used in a line's
+ indentation, otherwise only spaces can be used.
+ @end defopt
+ 
+ @defopt c-progress-interval
+ @vindex progress-interval (c-)
+ When indenting large regions of code, this variable controls how often a
+ progress message is displayed.  Set this variable to @code{nil} to
+ inhibit the progress messages, or set it to an integer which is how
+ often (in seconds) progress messages are to be displayed.
+ @end defopt
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Movement Commands, Other Commands, Indentation Commands, Commands
+ @comment node-name, next, previous, up
+ @section Movement Commands
+ @cindex movement
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @ccmode{} contains some useful commands for moving around in C
+ code.
+ 
+ @table @asis
+ @item @kbd{M-x c-beginning-of-defun}
+ @findex c-beginning-of-defun
+ @findex beginning-of-defun (c-)
+ @findex beginning-of-defun
+ Move point back to the least-enclosing brace.  This function is
+ analogous to the Emacs built-in command @code{beginning-of-defun},
+ except it eliminates the constraint that the top-level opening brace
+ must be in column zero.  See @code{beginning-of-defun} for more
+ information.
+ 
+ Depending on the coding style being used, you might prefer
+ @code{c-beginning-of-defun} to @code{beginning-of-defun}.  If so,
+ consider binding @kbd{C-M-a} to the former instead.  For backwards
+ compatibility reasons, the default binding remains in effect.
+ 
+ In AWK mode, a defun doesn't necessarily have braces at all.  AWK Mode
+ therefore has its own version of this function which is bound by
+ default to @kbd{C-M-a}.  You can thus chose freely which function to
+ bind to @kbd{C-M-a} for the other modes without worrying about AWK
+ buffers.  @xref{AWK Mode Defuns}.
+ 
+ @item @kbd{M-x c-end-of-defun}
+ @findex c-end-of-defun
+ @findex end-of-defun (c-)
+ @findex end-of-defun
+ Moves point to the end of the current top-level definition.  This
+ function is analogous to the Emacs built-in command @code{end-of-defun},
+ except it eliminates the constraint that the top-level opening brace of
+ the defun must be in column zero.  See @code{end-of-defun} for more
+ information.
+ 
+ Depending on the coding style being used, you might prefer
+ @code{c-end-of-defun} to @code{end-of-defun}.  If so,
+ consider binding @kbd{C-M-e} to the former instead.  For backwards
+ compatibility reasons, the default binding remains in effect.
+ 
+ In AWK Mode, a defun doesn't necessarily have braces at all.  AWK Mode
+ therefore has its own version of this function which is bound by
+ default to @kbd{C-M-e}.  You can thus chose freely which function to
+ bind to @kbd{C-M-e} for the other modes without worrying about AWK
+ buffers.  @ref{AWK Mode Defuns}.
+ 
+ @item @kbd{C-c C-u} (@code{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.
+ 
+ @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
+ function stops at them when going backward, but not when going forward.
+ 
+ @item @kbd{M-x c-up-conditional-with-else}
+ @findex c-up-conditional-with-else
+ @findex up-conditional-with-else (c-)
+ A variety of @code{c-up-conditional} that also stops at @samp{#else}
+ lines.  Normally those lines are ignored.
+ 
+ @item @kbd{M-x c-down-conditional}
+ @findex c-down-conditional
+ @findex down-conditional (c-)
+ Move point forward into the next nested preprocessor conditional,
+ leaving the mark behind.  A prefix argument acts as a repeat count.
+ With a negative argument, move point backward into the previous
+ nested preprocessor conditional.
+ 
+ @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
+ function stops at them when going forward, but not when going backward.
+ 
+ @item @kbd{M-x c-down-conditional-with-else}
+ @findex c-down-conditional-with-else
+ @findex down-conditional-with-else (c-)
+ A variety of @code{c-down-conditional} that also stops at @samp{#else}
+ lines.  Normally those lines are ignored.
+ 
+ @item @kbd{C-c C-p} (@code{c-backward-conditional})
+ @kindex C-c C-p
+ @findex c-backward-conditional
+ @findex backward-conditional (c-)
+ Move point back over a preprocessor conditional, leaving the mark
+ behind.  A prefix argument acts as a repeat count.  With a negative
+ argument, move forward.
+ 
+ @item @kbd{C-c C-n} (@code{c-forward-conditional})
+ @kindex C-c C-n
+ @findex c-forward-conditional
+ @findex forward-conditional (c-)
+ Move point forward across a preprocessor conditional, leaving the mark
+ behind.  A prefix argument acts as a repeat count.  With a negative
+ argument, move backward.
+ 
+ @item @kbd{M-a} (@code{c-beginning-of-statement})
+ @kindex M-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, move to the beginning of the
+ closest preceding statement, even if that means moving into a block (you
+ can use @kbd{C-M-b} to move over a balanced block).  With prefix
+ argument @var{n}, move back @var{n} @minus{} 1 statements.
+ 
+ If point is within or next to a comment or a string which spans more
+ than one line, this command moves by sentences instead of statements.
+ 
+ When called from a program, this function takes three optional
+ arguments: the repetition count, a buffer position limit which is the
+ farthest back to search for the syntactic context, and a flag saying
+ whether to do sentence motion in or near comments and multiline strings.
+ 
+ @item @kbd{M-e} (@code{c-end-of-statement})
+ @kindex M-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, even if it's
+ inside a nested block (use @kbd{C-M-f} to move to the other side of the
+ block).  With prefix argument @var{n}, move forward @var{n} @minus{} 1
+ statements.
+ 
+ If point is within or next to a comment or a string which spans more
+ than one line, this command moves by sentences instead of statements.
+ 
+ When called from a program, this function takes three optional
+ arguments: the repetition count, a buffer position limit which is the
+ farthest back to search for the syntactic context, and a flag saying
+ whether to do sentence motion in or near comments and multiline strings.
+ 
+ @item @kbd{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 next capitalized word.  With prefix
+ argument @var{n}, move @var{n} times.
+ 
+ @item @kbd{M-x c-backward-into-nomenclature}
+ @findex c-backward-into-nomenclature
+ @findex backward-into-nomenclature (c-)
+ Move point backward to beginning of the next capitalized
+ word.  With prefix argument @var{n}, move @var{n} times.  If
+ @var{n} is negative, move forward.
+ @end table
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Other Commands, , Movement Commands, Commands
+ @comment node-name, next, previous, up
+ @section Other Commands
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Here are the various other commands that didn't fit anywhere else:
+ 
+ @table @asis
+ @item @kbd{C-c :} (@code{c-scope-operator})
+ @kindex C-c :
+ @findex c-scope-operator
+ @findex scope-operator (c-)
+ 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, Commands, Top
+ @comment node-name, next, previous, up
+ @chapter Customizing Indentation
+ @cindex customization, indentation
+ @cindex indentation
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ The context sensitive indentation is mainly controlled by the variable
+ @code{c-offsets-alist}:
+ 
+ @defopt c-offsets-alist
+ @vindex offsets-alist (c-)
+ This special style variable contains the mappings between syntactic
+ symbols and the offsets to apply for those symbols.  It's set at mode
+ initialization from a @emph{style} you may specify.  Styles are
+ groupings of syntactic symbol offsets and other style variable values.
+ Most likely, you'll find that one of the predefined styles will suit
+ your needs.  @xref{Styles}, for an explanation of how to set up named
+ styles.
+ 
+ Only syntactic symbols not already bound on @code{c-offsets-alist} will
+ be set from styles.  This means that any association you set on it, be
+ it before or after mode initialization, will not be changed.  The
+ @code{c-offsets-alist} variable may therefore be used from e.g., the
+ Customization address@hidden in Emacs 20 and later, and
+ XEmacs 19.15 and later.} to easily change indentation offsets without
+ having to bother about styles.  Initially @code{c-offsets-alist} is
+ empty, so that all syntactic symbols are set by the style system.
+ 
+ The offset associated with any particular syntactic symbol can be an
+ integer, a function or lambda expression, a variable name, a vector, a
+ list, or one of the following special symbols: @code{+}, @code{-},
+ @code{++}, @code{--}, @code{*}, or @code{/}.  The meaning of these
+ values are described in detail below.
+ @end defopt
+ 
+ The special symbols describe an offset in multiples of the value of
+ @code{c-basic-offset}:
+ 
+ @defopt c-basic-offset
+ @vindex basic-offset (c-)
+ Style variable that holds the basic offset between indentation levels.
+ @end defopt
+ 
+ By defining a style's indentation in terms of @code{c-basic-offset},
+ you can change the amount of whitespace given to an indentation level
+ while maintaining the same basic shape of your code.  Here are the
+ values that the special symbols correspond to:
+ 
+ @table @code
+ @item +
+ @code{c-basic-offset} times 1
+ @item -
+ @code{c-basic-offset} times -1
+ @item ++
+ @code{c-basic-offset} times 2
+ @item --
+ @code{c-basic-offset} times -2
+ @item *
+ @code{c-basic-offset} times 0.5
+ @item /
+ @code{c-basic-offset} times -0.5
+ @end table
+ 
+ @cindex indentation functions
+ 
+ When a function is used as offset, it's called an @dfn{indentation
+ function}.  Such functions are useful when more context than just the
+ syntactic symbol is needed to get the desired indentation.
+ @xref{Indentation Functions}, and @ref{Custom Indentation Functions},
+ for details about them.
+ 
+ If the offset is a vector, its first element sets the absolute
+ indentation column, which will override any previous relative
+ indentation.  It won't override additional relative indentation for
+ nested constructs, though.
+ 
+ @vindex c-strict-syntax-p
+ @vindex strict-syntax-p (c-)
+ The offset can also be a list, in which case it is evaluated recursively
+ using the semantics described above.  The first element of the list that
+ returns a address@hidden value succeeds and the evaluation stops.  If
+ none of the list elements return a address@hidden value, then an offset
+ of 0 (zero) is address@hidden is however a variable
+ @code{c-strict-syntax-p} that, when set to address@hidden, will cause an
+ error to be signalled in that case.  It's now considered obsolete since
+ it doesn't work well with some of the alignment functions that now
+ returns @code{nil} instead of zero to be more usable in lists.  You
+ should therefore leave @code{c-strict-syntax-p} set to @code{nil}.}.
+ 
+ So, for example, because most of the default offsets are defined in
+ terms of @code{+}, @code{-}, and @code{0}, if you like the general
+ indentation style, but you use 4 spaces instead of 2 spaces per level,
+ you can probably achieve your style just by changing
+ @code{c-basic-offset} like address@hidden can try this interactively in
+ a C buffer by typing the text that appears in italics.}:
+ 
+ @example
+ @emph{M-x set-variable RET}
+ Set variable: @emph{c-basic-offset RET}
+ Set c-basic-offset to value: @emph{4 RET}
+ @end example
+ 
+ @noindent
+ This would change
+ 
+ @example
+ @group
+ 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 );
+         @}
+     return( val );
+ @}
+ @end group
+ @end example
+ 
+ To change indentation styles more radically, you will want to change the
+ offsets associated with other syntactic symbols.  First, I'll show you
+ how to do that interactively, then I'll describe how to make changes to
+ your @file{.emacs} file so that your changes are more permanent.
+ 
+ @menu
+ * Interactive Customization::
+ * Permanent Customization::
+ * Hooks::
+ * Styles::
+ * Advanced Customizations::
+ @end menu
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Interactive Customization, Permanent Customization, , Customizing 
Indentation
+ @comment node-name, next, previous, up
+ @section Interactive Customization
+ @cindex customization, interactive
+ @cindex interactive customization
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ As an example of how to customize indentation, let's change the
+ style of this address@hidden this and subsequent examples, the
+ original code is formatted using the @samp{gnu} style unless otherwise
+ indicated.  @xref{Styles}.}:
+ 
+ @example
+ @group
+  1: int add( int val, int incr, int doit )
+  2: @{
+  3:   if( doit )
+  4:     @{
+  5:       return( val + incr );
+  6:     @}
+  7:   return( val );
+  8: @}
+ @end group
+ @end example
+ 
+ @noindent
+ to:
+ 
+ @example
+ @group
+  1: int add( int val, int incr, int doit )
+  2: @{
+  3:   if( doit )
+  4:   @{
+  5:     return( val + incr );
+  6:   @}
+  7:   return( val );
+  8: @}
+ @end group
+ @end example
+ 
+ In other words, we want to change the indentation of braces that open a
+ block following a condition so that the braces line up under the
+ conditional, instead of being indented.  Notice that the construct we
+ want to change starts on line 4.  To change the indentation of a line,
+ we need to see which syntactic components affect the offset calculations
+ for that line.  Hitting @kbd{C-c C-s} on line 4 yields:
+ 
+ @example
+ ((substatement-open 44))
+ @end example
+ 
+ @noindent
+ so we know that to change the offset of the open brace, we need to
+ change the indentation for the @code{substatement-open} syntactic
+ symbol.
+ 
+ To do this interactively, just hit @kbd{C-c C-o}.  This prompts
+ you for the syntactic symbol to change, providing a reasonable default.
+ In this case, the default is @code{substatement-open}, which is just the
+ syntactic symbol we want to change!
+ 
+ After you hit return, @ccmode{} will then prompt you for the new
+ offset value, with the old value as the default.  The default in this
+ case is @samp{+}, but we want no extra indentation so enter
+ @samp{0} and @kbd{RET}.  This will associate the offset 0 with the
+ syntactic symbol @code{substatement-open}.
+ 
+ To check your changes quickly, just hit @kbd{C-c C-q}
+ (@code{c-indent-defun}) to reindent the entire function.  The example
+ should now look like:
+ 
+ @example
+ @group
+  1: int add( int val, int incr, int doit )
+  2: @{
+  3:   if( doit )
+  4:   @{
+  5:     return( val + incr );
+  6:   @}
+  7:   return( val );
+  8: @}
+ @end group
+ @end example
+ 
+ Notice how just changing the open brace offset on line 4 is all we
+ needed to do.  Since the other affected lines are indented relative to
+ line 4, they are automatically indented the way you'd expect.  For more
+ complicated examples, this may not always work.  The general approach to
+ take is to always start adjusting offsets for lines higher up in the
+ file, then reindent and see if any following lines need further
+ adjustments.
+ 
+ @deffn Command c-set-offset symbol offset
+ @findex set-offset (c-)
+ @kindex C-c C-o
+ This is the command bound to @kbd{C-c C-o}.  It provides a convenient
+ way to set offsets on @code{c-offsets-alist} both interactively (see
+ the example above) and from your mode hook.
+ 
+ It takes two arguments when used programmatically: @var{symbol} is the
+ syntactic element symbol to change and @var{offset} is the new offset
+ for that syntactic element.
+ @end deffn
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Permanent Customization, Hooks, Interactive Customization, 
Customizing Indentation
+ @comment node-name, next, previous, up
+ @section Permanent Customization
+ @cindex customization, permanent
+ @cindex permanent customization
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ To make your changes permanent, you need to add some lisp code to your
+ @file{.emacs} file.  @ccmode{} supports many different ways to be
+ configured, from the straightforward way by setting variables globally
+ in @file{.emacs} or in the Customization interface, to the complex and
+ precisely controlled way by using styles and hook functions.
+ 
+ The simplest way of customizing @ccmode{} permanently is to set the
+ variables in your @file{.emacs} with @code{setq} and similar commands.
+ So to make a permanent setting of @code{substatement-open} to 0, add
+ this to the @file{.emacs} file:
+ 
+ @example
+ @group
+ (setq c-offsets-alist
+       '((substatement-open . 0)))
+ @end group
+ @end example
+ 
+ When @ccmode{} initializes a buffer, it will fill out
+ @code{c-offsets-alist} with the remaining syntactic symbols according to
+ the style system.
+ 
+ You can also use the more user friendly Customization interface, but
+ this manual does not cover how that works.
+ 
+ Variables set like this at the top level in @file{.emacs} take effect in
+ all @ccmode{} buffers, regardless of language.  The indentation style
+ related variables, e.g., @code{c-offsets-alist}, that you don't set this
+ way get their value from the style system (@pxref{Styles}), and they
+ therefore depend on the setting of @code{c-default-style}.  Note that if
+ you use Customize, this means that the greyed-out default values
+ presented there might not be the ones you actually get, since the actual
+ values depend on the style, which may very well be different for
+ different languages.
+ 
+ If you want to make more advanced configurations, e.g., language-specific
+ customization, setting global variables isn't enough.  For that you can
+ use the language hooks, see @ref{Hooks}, and/or the style system, see
+ @ref{Styles}.
+ 
+ @defopt c-style-variables-are-local-p
+ @vindex style-variables-are-local-p (c-)
+ By default, all style variables are buffer local, so that different
+ buffers can have different style settings.  If you only use one style
+ in all the files you edit you might want to share them between buffers
+ so that a change take effect in all buffers.  That's done by setting
+ this variable to @code{nil}.  The value takes effect when @ccmode{} is
+ activated in a buffer for the first time in the Emacs session, so you
+ typically set it in your @file{.emacs} file and then restart Emacs.
+ @end defopt
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Hooks, Styles, Permanent Customization, Customizing Indentation
+ @comment node-name, next, previous, up
+ @section Hooks
+ @cindex mode hooks
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @ccmode{} 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 Emacs major mode conventions.  There is also one
+ general hook and one package initialization hook:
+ 
+ @defvar c-initialization-hook
+ @vindex initialization-hook (c-)
+ Hook run only once per Emacs session, when @ccmode{} is initialized.
+ @end defvar
+ 
+ @defvar c-mode-common-hook
+ @vindex mode-common-hook (c-)
+ Common hook across all languages.  It's run immediately before the
+ language specific hook.
+ @end defvar
+ 
+ @defvar c-mode-hook
+ @defvarx c++-mode-hook
+ @defvarx objc-mode-hook
+ @defvarx java-mode-hook
+ @defvarx idl-mode-hook
+ @defvarx pike-mode-hook
+ @defvarx awk-mode-hook
+ The language specific mode hooks.  The appropriate one is run as the
+ last thing when you enter that language mode.
+ @end defvar
+ 
+ Note that all the language-specific mode setup that CC Mode does is done
+ prior to both @code{c-mode-common-hook} and the language specific hook.
+ That includes installing the indentation style, which can be mode
+ specific (and also is by default for Java mode).  Thus, any style
+ settings done in @code{c-mode-common-hook} will override whatever
+ language-specific style is chosen by @code{c-default-style}.
+ 
+ Here's a simplified example of what you can add to your @file{.emacs}
+ file to do things whenever any @ccmode{} language is edited.  See the
+ Emacs manuals for more information on customizing Emacs via hooks.
+ @xref{Sample .emacs File}, for a more complete sample @file{.emacs}
+ file.
+ 
+ @example
+ (defun my-c-mode-common-hook ()
+   ;; my customizations for all of c-mode and related modes
+   (no-case-fold-search)
+   )
+ (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+ @end example
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Styles, Advanced Customizations, Hooks, Customizing Indentation
+ @comment node-name, next, previous, up
+ @section Styles
+ @cindex styles
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Most people only need to edit code formatted in just a few well-defined
+ and consistent styles.  For example, their organization might impose a
+ ``blessed'' style that all its programmers must conform to.  Similarly,
+ people who work on GNU software will have to use the GNU coding style.
+ Some shops are more lenient, allowing a variety of coding styles, and as
+ programmers come and go, there could be a number of styles in use.  For
+ this reason, @ccmode{} 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.
+ 
+ @cindex style variables
+ The variables that the style system affect are called @dfn{style
+ variables}.  They are handled specially in several ways:
+ 
+ @itemize @bullet
+ @item
+ Style variables are by default buffer local variables.  However, they
+ can instead be made global by setting
+ @code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is
+ initialized.
+ 
+ @item
+ @vindex c-old-style-variable-behavior
+ @vindex old-style-variable-behavior (c-)
+ The default value of any style variable (with two exceptions --- see
+ below) is the special symbol @code{set-from-style}.  Variables that are
+ still set to that symbol when a @ccmode{} buffer is initialized will be
+ set according to the current style, otherwise they will keep their
+ current address@hidden is a big change from versions of @ccmode{}
+ earlier than 5.26, where such settings would get overridden by the style
+ system unless special precautions were taken.  That was changed since it
+ was counterintuitive and confusing, especially to novice users.  If your
+ configuration depends on the old overriding behavior, you can set the
+ variable @code{c-old-style-variable-behavior} to address@hidden
+ 
+ Note that when we talk about the ``default value'' for a style variable,
+ we don't mean the @code{set-from-style} symbol that all style variables
+ are set to initially, but instead the value it will get at mode
+ initialization when neither a style nor a global setting has set its
+ value.
+ 
+ The style variable @code{c-offsets-alist} is handled a little
+ differently from the other style variables.  It's an association list,
+ and is thus by default set to the empty list, @code{nil}.  When the
+ style system is initialized, any syntactic symbols already on it are
+ kept --- only the missing ones are filled in from the chosen style.
+ 
+ The style variable @code{c-special-indent-hook} is also handled in a
+ special way.  Styles may only add more functions on this hook, so the
+ global settings on it are always address@hidden did not change
+ in version 5.26.}.
+ 
+ @item
+ The global settings of style variables get captured in the special
+ @code{user} style, which is used as the base for all the other styles.
+ @xref{Built-in Styles}, for details.
+ @end itemize
+ 
+ The style variables are:
+ @code{c-basic-offset},
+ @code{c-comment-only-line-offset},
+ @code{c-block-comment-prefix},
+ @code{c-comment-prefix-regexp},
+ @code{c-cleanup-list},
+ @code{c-hanging-braces-alist},
+ @code{c-hanging-colons-alist},
+ @code{c-hanging-semi&comma-criteria},
+ @code{c-backslash-column},
+ @code{c-backslash-max-column},
+ @code{c-special-indent-hook},
+ @code{c-label-minimum-indentation}, and
+ @code{c-offsets-alist}.
+ 
+ @menu
+ * Built-in Styles::
+ * Choosing a Style::
+ * Adding Styles::
+ * File Styles::
+ @end menu
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Built-in Styles, Choosing a Style, , Styles
+ @comment node-name, next, previous, up
+ @subsection Built-in Styles
+ @cindex styles, built-in
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ If you're lucky, one of @ccmode{}'s built-in styles might be just
+ what you're looking for.  These include:
+ 
+ @table @code
+ @item gnu
+ @cindex GNU style
+ Coding style blessed by the Free Software Foundation
+ for C code in GNU programs.
+ 
+ @item k&r
+ @cindex K&R style
+ The classic Kernighan and Ritchie style for C code.
+ 
+ @item bsd
+ @cindex BSD style
+ Also known as ``Allman style'' after Eric Allman.
+ 
+ @item whitesmith
+ @cindex Whitesmith style
+ Popularized by the examples that came with Whitesmiths C, an early
+ commercial C compiler.
+ 
+ @item stroustrup
+ @cindex Stroustrup style
+ The classic Stroustrup style for C++ code.
+ 
+ @item ellemtel
+ @cindex Ellemtel style
+ Popular C++ coding standards as defined by ``Programming in C++, Rules
+ and Recommendations,'' Erik Nyquist and Mats Henricson,
+ address@hidden document is available at
+ @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
+ places.}.
+ 
+ @item linux
+ @cindex Linux style
+ C coding standard for Linux (the kernel).
+ 
+ @item python
+ @cindex Python style
+ C coding standard for Python extension address@hidden is a
+ high level scripting language with a C/C++ foreign function interface.
+ For more information, see @uref{http://www.python.org/}.}.
+ 
+ @item java
+ @cindex Java style
+ The style for editing Java code.  Note that the default
+ value for @code{c-default-style} installs this style when you enter
+ @code{java-mode}.
+ 
+ @item user
+ @cindex User style
+ This is a special style for several reasons.  First, the
+ @ccmode{} customizations you do by using either the Customization
+ interface, or by writing @code{setq}'s at the top level of your
+ @file{.emacs} file, will be captured in the @code{user} style.  Also,
+ all other styles implicitly inherit their settings from @code{user}
+ style.  This means that for any styles you add via @code{c-add-style}
+ (@pxref{Adding Styles}) you need only define the differences between
+ your new style and @code{user} style.
+ @end table
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Choosing a Style, Adding Styles, Built-in Styles, Styles
+ @comment node-name, next, previous, up
+ @subsection Choosing a Style
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Use @kbd{C-c .} to choose a style interactively:
+ 
+ @deffn Command c-set-style style-name
+ @findex set-style (c-)
+ @kindex C-c .
+ Switch to the specified style in the current buffer.  Use
+ interactively like this:
+ 
+ @example
+ @kbd{C-c . @var{style-name} RET}
+ @end example
+ 
+ Note that all style names are case insensitive, even the ones you
+ define.
+ 
+ Setting a style in this way does @emph{not} automatically reindent your
+ file.  For commands that you can use to view the effect of your changes,
+ see @ref{Commands}.
+ @end deffn
+ 
+ The default style in all newly created buffers is @code{gnu}, except
+ in Java mode where it's @code{java}.  Although the @code{user} style
+ is not the default style, any style variable settings you do with the
+ Customization interface or on the top level in your @file{.emacs} file
+ will by default override the style system, so you don't need to set
+ @code{c-default-style} to @code{user} to see the effect of such
+ settings.
+ 
+ @defopt c-default-style
+ @vindex default-style (c-)
+ This variable specifies which style to install by default in new
+ buffers.  It takes either a style name string, or an association list
+ of major mode symbols to style names:
+ 
+ @enumerate
+ @item
+ When @code{c-default-style} is a string, it must be an existing style
+ name.  This style is then used for all modes.
+ 
+ @item
+ When @code{c-default-style} is an association list, the mode language
+ is looked up to find a style name string.
+ 
+ @item
+ If @code{c-default-style} is an association list where the mode
+ language mode isn't found then the special symbol @samp{other} is
+ looked up.  If it's found then the associated style is used.
+ 
+ @item
+ If @samp{other} is not found then the @samp{gnu} style is used.
+ 
+ @item
+ In all cases, the style described in @code{c-default-style} is installed 
+ @emph{before} the language hooks are run, so you can always override
+ this setting by including an explicit call to @code{c-set-style} in your 
+ language mode hook, or in @code{c-mode-common-hook}.
+ @end enumerate
+ @end defopt
+ 
+ @defvar c-indentation-style
+ @vindex indentation-style (c-)
+ This variable always contains the buffer's current style name, as a
+ string.
+ @end defvar
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Adding Styles, File Styles, Choosing a Style, Styles
+ @comment node-name, next, previous, up
+ @subsection Adding and Amending Styles
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ If none of the built-in styles is appropriate, you'll probably want to
+ create a new @dfn{style definition}, possibly based on an existing
+ style.  To do this, put the new style's settings into a list with the
+ following format - the list can then be passed as an argument to the
+ function @code{c-add-style}:
+ 
+ @cindex style definition
+ @defvr {List} style definition
+ (address@hidden [(@var{variable} . @var{value}) @dots{}])
+ 
+ Optional @var{base-style}, if present, must be a string which is the
+ name of the @dfn{base style} from which this style inherits.  At most
+ one @var{base-style} is allowed in a style definition.  If
+ @var{base-style} is not specified, the style inherits from a table of
+ default address@hidden table is stored internally in the
+ variable c-fallback-style.  It is computed during the initialisation
+ of @ccmode{} from the factory defaults of the style variables and any
+ global values they may have been given since starting Emacs.} instead.
+ All styles eventually inherit from this internal table.  Style loops
+ generate errors.  The list of pre-existing styles can be seen in
+ @ref{Built-in Styles}.
+ 
+ The dotted pairs (@var{variable} . @var{value}) each consist of a
+ variable and the value it is to be set to when the style is later
+ address@hidden certain circumstances, this value can get
+ overridden by another value.}  The variable can be either a @ccmode{}
+ style variable or an arbitrary Emacs variable.  In the latter case, it
+ is @emph{not} made buffer local by the @ccmode{} style system.
+ @end defvr
+ 
+ Two variables are treated specially in the dotted pair list:
+ 
+ @table @code
+ @item c-offsets-alist
+ The value is in turn a dotted list on the form
+ 
+ (@var{syntactic-symbol} . @var{offset})
+ 
+ as described in @ref{Customizing Indentation}.  These are passed to
+ @code{c-set-offset} so there is no need to set every syntactic symbol in
+ your style, only those that are different from the inherited style.
+ 
+ @item c-special-indent-hook
+ The value is added to @code{c-special-indent-hook} using
+ @code{add-hook}, so any functions already on it are kept.  If the value
+ is a list, each element of the list is added with @code{add-hook}.
+ @end table
+ 
+ Styles are kept in the @code{c-style-alist} variable, but you
+ should never modify this variable directly.  Instead, @ccmode{}
+ provides the function @code{c-add-style} for this purpose.
+ 
+ @defun c-add-style stylename description &optional set-p
+ @findex add-style (c-)
+ Add or update a style called @var{stylename}, a string.
+ @var{description} is the new style definition in the form described
+ above.  If @var{stylename} already exists in @code{c-style-alist} then
+ it is replaced by @var{description}.  (Note, this replacement is
+ total.  The old style is @emph{not} merged into the new one.)
+ Otherwise, a new style is added.  If the optional @var{set-p} is
+ address@hidden then the new style is applied to the current buffer as
+ well.
+ 
+ The sample @file{.emacs} file provides a concrete example of how a new
+ style can be added and automatically set.  @xref{Sample .emacs File}.
+ @end defun
+ 
+ @defvar c-style-alist
+ @vindex style-alist (c-)
+ This is the variable that holds the definitions for the styles.  It
+ should not be changed directly; use @code{c-add-style} instead.
+ @end defvar
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    File Styles, , Adding Styles, Styles
+ @comment node-name, next, previous, up
+ @subsection File Styles
+ @cindex styles, file local
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @cindex file local variables
+ 
+ The Emacs manual describes how you can customize certain variables on
+ a per-file basis by including a @dfn{file local variable} block at the
+ end of the file.  So far, you've only seen a functional interface to
+ @ccmode{} customization, which can't be used there.  @ccmode{}
+ provides two variables allow customization of the indentation style on
+ a per-file basis:
+ 
+ @defvar c-file-style
+ @vindex file-style (c-)
+ This variable can be set to a style name string.  When the file is
+ visited, @ccmode{} will automatically set the file's style to this
+ one using @code{c-set-style}.
+ @end defvar
+ 
+ @defvar c-file-offsets
+ @vindex file-offsets (c-)
+ This variable takes an association list similar to what is allowed in
+ @code{c-offsets-alist}.  When the file is visited, @ccmode{} will
+ automatically institute these offsets using @code{c-set-offset}.
+ @end defvar
+ 
+ Note that file style settings (i.e., @code{c-file-style}) are applied
+ before file offset settings (i.e., @code{c-file-offsets}).  Also, if
+ either of these are set in a file's local variable section, all the
+ style variable values are made local to that buffer.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Advanced Customizations, , Styles, Customizing Indentation
+ @comment node-name, next, previous, up
+ @section Advanced Customizations
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ For most users, @ccmode{} will support their coding styles with very
+ little need for more advanced customizations.  Usually, one of the
+ standard styles (@pxref{Built-in Styles}) 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 @ccmode{} is that the
+ syntactic analysis model provides just such a framework. This allows
+ you to implement custom indentation calculations for situations not
+ handled by the mode directly.
+ 
+ @menu
+ * Custom Indentation Functions::
+ * Custom Brace and Colon Hanging::
+ * Customizing Semicolons and Commas::
+ * Other Special Indentations::
+ @end menu
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Custom Indentation Functions, Custom Brace and Colon Hanging, , 
Advanced Customizations
+ @comment node-name, next, previous, up
+ @subsection Custom Indentation Functions
+ @cindex customization, indentation functions
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ The most flexible way to customize @ccmode{} is by writing custom
+ indentation functions, and associating them with specific syntactic
+ symbols (@pxref{Syntactic Symbols}).  @ccmode{} itself uses indentation
+ functions to provide more sophisticated indentation, for example when
+ lining up C++ stream operator blocks:
+ 
+ @example
+ @group
+  1: void main(int argc, char**)
+  2: @{
+  3:   cout << "There were "
+  4:     << argc
+  5:     << "arguments passed to the program"
+  6:     << endl;
+  7: @}
+ @end group
+ @end example
+ 
+ In this example, lines 4 through 6 are assigned the @code{stream-op}
+ 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 @ccmode{} to be a little more intelligent so that it aligns
+ 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 the first
+ stream operator on the first line of the statement.  Here is sample 
+ lisp code implementing this:
+ 
+ @example
+ (defun c-lineup-streamop (langelem)
+   (save-excursion
+     (goto-char (cdr langelem))
+     (re-search-forward "<<\\|>>" (c-point 'eol) 'move)
+     (goto-char (match-beginning 0))
+     (vector (current-column))))
+ @end example
+ 
+ Indentation functions take a single argument, which is a syntactic
+ component cons cell (@pxref{Syntactic Analysis}).  The function can
+ return an integer which is added to the running total indentation for
+ the line, or a vector containing an integer which is an absolute
+ column to align to.  Usually an absolute column is wanted when
+ aligning to existing text, as in this example.
+ 
+ The function should return @code{nil} if it's used in a situation where
+ it doesn't want to make any decision.  If the function is used in a list
+ expression (@pxref{Customizing Indentation}), that will cause @ccmode{}
+ to go on and check the next entry in the list.
+ 
+ Now, to associate the function @code{c-lineup-streamop} with the
+ @code{stream-op} syntactic symbol, we can add something like the
+ following to our @address@hidden probably makes more
+ sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook}
+ since stream operators are only relevant for C++.}:
+ 
+ @example
+ (c-set-offset 'stream-op 'c-lineup-streamop)
+ @end example
+ 
+ Now the function looks like this after reindenting (using @kbd{C-c
+ C-q}):
+ 
+ @example
+ @group
+  1: void main(int argc, char**)
+  2: @{
+  3:   cout << "There were "
+  4:        << argc
+  5:        << " arguments passed to the program"
+  6:        << endl;
+  7: @}
+ @end group
+ @end example
+ 
+ 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.
+ 
+ @ccmode{} comes with an extensive set of predefined indentation
+ functions, not all of which are used by the default styles.  So there's
+ a good chance the function you want already exists.  @xref{Indentation
+ Functions}, for a list of them.  If you have written an indentation
+ function that you think is generally useful, you're very welcome to
+ contribute it; please contact @email{bug-cc-mode@@gnu.org}.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Custom Brace and Colon Hanging, Customizing Semicolons and Commas, 
Custom Indentation Functions, Advanced Customizations
+ @comment node-name, next, previous, up
+ @subsection Custom Brace and Colon Hanging
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @vindex c-hanging-braces-alist
+ @vindex hanging-braces-alist (c-)
+ Syntactic symbols aren't the only place where you can customize
+ @ccmode{} with the lisp equivalent of callback functions.  Brace
+ ``hanginess'' can also be determined by custom functions associated with
+ syntactic symbols on the @code{c-hanging-braces-alist} style variable.
+ Remember that @var{action}'s are typically a list containing some
+ combination of the symbols @code{before} and @code{after}
+ (@pxref{Hanging Braces}).  However, an @var{action} can also be a
+ function which gets called when a brace matching that syntactic symbol
+ is entered.
+ 
+ @cindex customization, brace hanging
+ These @var{action} functions are called with two arguments: the
+ syntactic symbol for the brace, and the buffer position at which the
+ brace was inserted.  The @var{action} function is expected to return a
+ list containing some combination of @code{before} and @code{after},
+ including neither of them (i.e., @code{nil}).  This return value has the
+ normal brace hanging semantics.
+ 
+ As an example, @ccmode{} itself uses this feature to dynamically
+ determine the hanginess of braces which close ``do-while''
+ constructs:
+ 
+ @example
+ void do_list( int count, char** atleast_one_string )
+ @{
+     int i=0;
+     do @{
+         handle_string( atleast_one_string[i] );
+         i++;
+     @} while( i < count );
+ @}
+ @end example
+ 
+ @ccmode{} 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 ``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}:
+ 
+ @example
+ (defun c-snug-do-while (syntax pos)
+   "Dynamically calculate brace hanginess for do-while statements."
+   (save-excursion
+     (let (langelem)
+       (if (and (eq syntax 'block-close)
+                (setq langelem (assq 'block-close c-syntactic-context))
+                (progn (goto-char (cdr langelem))
+                       (if (= (following-char) address@hidden)
+                           (forward-sexp -1))
+                       (looking-at "\\<do\\>[^_]")))
+           '(before)
+         '(before after)))))
+ @end example
+ 
+ @findex c-snug-do-while
+ @findex snug-do-while (c-)
+ 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{(before after)} so
+ that the brace appears on a line by itself.
+ 
+ @defvar c-syntactic-context
+ @vindex syntactic-context (c-)
+ During the call to the indentation or brace hanging @var{action}
+ function, this variable is bound to the full syntactic analysis list.
+ @end defvar
+ 
+ @cindex customization, colon hanging
+ @vindex c-hanging-colons-alist
+ @vindex hanging-colons-alist (c-)
+ Note that for symmetry, colon hanginess should be customizable by
+ allowing function symbols as @var{action}s on the
+ @code{c-hanging-colons-alist} style variable.  Since no use has actually
+ been found for this feature, it isn't currently implemented!
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Customizing Semicolons and Commas, Other Special Indentations, 
Custom Brace and Colon Hanging, Advanced Customizations
+ @comment node-name, next, previous, up
+ @subsection Customizing Semicolons and Commas
+ @cindex customization, semicolon newlines
+ @cindex customization, comma newlines
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ You can also customize the insertion of newlines after semicolons and
+ commas when the auto-newline minor mode is enabled (@pxref{Minor
+ Modes}).
+ 
+ @defopt c-hanging-semi&comma-criteria
+ @vindex hanging-semi&comma-criteria (c-)
+ This style variable takes a list of hooks that get called when a
+ semicolon or comma is inserted.  The hooks are called in order without
+ arguments, and are expected to return one of the following values:
+ 
+ @table @code
+ @item t
+ A newline is inserted, and no more functions from the list are called.
+ @item stop
+ No more functions from the list are called, but no newline is
+ inserted.
+ @item nil
+ No determination is made, and the next function in the list is called.
+ @end table
+ 
+ If every function in the list is called without a determination being
+ made, then no newline is added. The default value for this variable is a
+ list containing a single function which inserts newlines only after
+ semicolons which do not appear inside parenthesis lists (i.e., those
+ that separate @code{for}-clause statements).
+ @end defopt
+ 
+ @defun c-semi&comma-no-newlines-before-nonblanks
+ @findex semi&comma-no-newlines-before-nonblanks (c-)
+ This is an example of a criteria function, provided by @ccmode{}.  It
+ prevents newlines from being inserted after semicolons when there is a
+ non-blank following line.  Otherwise, it makes no determination.  To
+ use, add this function to the front of the
+ @code{c-hanging-semi&comma-criteria} list.
+ 
+ @example
+ (defun c-semi&comma-no-newlines-before-nonblanks ()
+   (save-excursion
+     (if (and (eq last-command-char ?\;)
+              (zerop (forward-line 1))
+              (not (looking-at "^[ \t]*$")))
+         'stop
+       nil)))
+ @end example
+ @end defun
+ 
+ @defun c-semi&comma-inside-parenlist
+ @findex semi&comma-inside-parenlist (c-)
+ @defunx c-semi&comma-no-newlines-for-oneline-inliners
+ @findex semi&comma-no-newlines-for-oneline-inliners (c-)
+ The function @code{c-semi&comma-inside-parenlist} is what prevents
+ newlines from being inserted inside the parenthesis list of @code{for}
+ statements.  In addition to
+ @code{c-semi&comma-no-newlines-before-nonblanks} described above,
+ @ccmode{} also comes with the criteria function
+ @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
+ newlines after semicolons inside one-line inline method definitions
+ (e.g., in C++ or Java).
+ @end defun
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Other Special Indentations, , Customizing Semicolons and Commas, 
Advanced Customizations
+ @comment node-name, next, previous, up
+ @subsection Other Special Indentations
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Here are the remaining odds and ends regarding indentation:
+ 
+ @defopt c-label-minimum-indentation
+ @vindex label-minimum-indentation (c-)
+ In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation
+ is imposed on lines inside top-level constructs.  This minimum
+ indentation is controlled by this style variable.  The default value
+ is 1.
+ @end defopt
+ 
+ @defopt c-special-indent-hook
+ @vindex special-indent-hook (c-)
+ This style variable is a standard hook variable that is called after
+ every line is indented by @ccmode{}.  You can use it 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 that you should 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.
+ @end defopt
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Syntactic Symbols, Indentation Functions, Customizing Indentation, 
Top
+ @comment node-name, next, previous, up
+ @chapter Syntactic Symbols
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @cindex syntactic symbols, brief list
+ @vindex c-offsets-alist
+ @vindex offsets-alist (c-)
+ Here is a complete list of the recognized syntactic symbols as described
+ in the @code{c-offsets-alist} style variable, along with a brief
+ description.  More detailed descriptions follow.
+ 
+ @table @code
+ @item string
+ Inside a multiline string.
+ @item c
+ Inside a multiline C style block comment.
+ @item defun-open
+ Brace that opens a top-level function definition.
+ @item defun-close
+ Brace that closes a top-level function definition.
+ @item defun-block-intro
+ The first line in a top-level defun.
+ @item class-open
+ Brace that opens a class definition.
+ @item class-close
+ Brace that closes a class definition.
+ @item inline-open
+ Brace that opens an in-class inline method.
+ @item inline-close
+ Brace that closes an in-class inline method.
+ @item func-decl-cont
+ The region between a function definition's argument list and the
+ function opening brace (excluding K&R argument declarations).  In C, you
+ cannot put anything but whitespace and comments in this region, however
+ in C++ and Java, @code{throws} declarations and other things can appear
+ here.
+ @item knr-argdecl-intro
+ First line of a K&R C argument declaration.
+ @item knr-argdecl
+ Subsequent lines in a K&R C argument declaration.
+ @item topmost-intro
+ The first line in a ``topmost'' definition.
+ @item topmost-intro-cont
+ Topmost definition continuation lines.  This is only used in the parts
+ that aren't covered by other symbols such as @code{func-decl-cont} and
+ @code{knr-argdecl}.
+ @item member-init-intro
+ First line in a member initialization list.
+ @item member-init-cont
+ Subsequent member initialization list lines.
+ @item inher-intro
+ First line of a multiple inheritance list.
+ @item inher-cont
+ Subsequent multiple inheritance lines.
+ @item block-open
+ Statement block open brace.
+ @item block-close
+ Statement block close brace.
+ @item brace-list-open
+ Open brace of an enum or static array list.
+ @item brace-list-close
+ Close brace of an enum or static array list.
+ @item brace-list-intro
+ First line in an enum or static array list.
+ @item brace-list-entry
+ Subsequent lines in an enum or static array list.
+ @item brace-entry-open
+ Subsequent lines in an enum or static array list where the line begins
+ with an open brace.
+ @item statement
+ A statement.
+ @item statement-cont
+ A continuation of a statement.
+ @item statement-block-intro
+ The first line in a new statement block.
+ @item statement-case-intro
+ The first line in a case block.
+ @item statement-case-open
+ The first line in a case block that starts with a brace.
+ @item substatement
+ The first line after a conditional or loop construct.
+ @item substatement-open
+ The brace that opens a substatement block.
+ @item substatement-label
+ The first line after a conditional or loop construct if it's a label.
+ @item case-label
+ A label in a @code{switch} block.
+ @item access-label
+ C++ access control label.
+ @item label
+ Any other label.
+ @item do-while-closure
+ The @code{while} line that ends a @address@hidden construct.
+ @item else-clause
+ The @code{else} line of an @address@hidden construct.
+ @item catch-clause
+ The @code{catch} or @code{finally} (in Java) line of a
+ @address@hidden construct.
+ @item comment-intro
+ A line containing only a comment introduction.
+ @item arglist-intro
+ The first line in an argument list.
+ @item arglist-cont
+ Subsequent argument list lines when no arguments follow on the same line
+ as the arglist opening paren.
+ @item arglist-cont-nonempty
+ Subsequent argument list lines when at least one argument follows on the
+ same line as the arglist opening paren.
+ @item arglist-close
+ The solo close paren of an argument list.
+ @item stream-op
+ Lines continuing a stream operator (C++ only).
+ @item inclass
+ The line is nested inside a class definition.
+ @item cpp-macro
+ The start of a preprocessor macro definition.
+ @item cpp-define-intro
+ The first line inside a multiline preproprocessor macro if
+ @code{c-syntactic-indentation-in-macros} is set.
+ @item cpp-macro-cont
+ All lines inside multiline preprocessor macros if
+ @code{c-syntactic-indentation-in-macros} is @code{nil}.
+ @item friend
+ A C++ friend declaration.
+ @item objc-method-intro
+ The first line of an Objective-C method definition.
+ @item objc-method-args-cont
+ Lines continuing an Objective-C method definition.
+ @item objc-method-call-cont
+ Lines continuing an Objective-C method call.
+ @item extern-lang-open
+ Brace that opens an @code{extern} block (e.g., @code{extern "C" 
@address@hidden).
+ @item extern-lang-close
+ Brace that closes an @code{extern} block.
+ @item inextern-lang
+ Analogous to @code{inclass} syntactic symbol, but used inside
+ @code{extern} blocks.
+ @item namespace-open
+ @itemx namespace-close
+ @itemx innamespace
+ These are analogous to the three @code{extern-lang} symbols above, but
+ are returned for C++ namespace blocks.
+ @item module-open
+ @itemx module-close
+ @itemx inmodule
+ Analogous to the above, but for CORBA IDL @code{module} blocks.
+ @item composition-open
+ @itemx composition-close
+ @itemx incomposition
+ Analogous to the above, but for CORBA CIDL @code{composition} blocks.
+ @item template-args-cont
+ C++ template argument list continuations.
+ @item inlambda
+ Analogous to @code{inclass} syntactic symbol, but used inside lambda
+ (i.e., anonymous) functions.  Only used in Pike mode.
+ @item lambda-intro-cont
+ Lines continuing the header of a lambda function, i.e., between the
+ @code{lambda} keyword and the function body.  Only used in Pike mode.
+ @item inexpr-statement
+ A statement block inside an expression.  The gcc C and C++ extension for
+ this is recognized.  It's also used for the special functions that take
+ a statement block as an argument in Pike.
+ @item inexpr-class
+ A class definition inside an expression.  This is used for anonymous
+ classes in Java.  It's also used for anonymous array initializers in
+ Java.
+ @end table
+ 
+ @ssindex -open symbols
+ @ssindex -close symbols
+ Most syntactic symbol names follow a general naming convention.  When a
+ line begins with an open or close brace, the syntactic symbol will
+ contain the suffix @code{-open} or @code{-close} respectively.
+ 
+ @ssindex -intro symbols
+ @ssindex -cont symbols
+ @ssindex -block-intro symbols
+ Usually, a distinction is made between the first line that introduces a
+ construct and lines that continue a construct, and the syntactic symbols
+ that represent these lines will contain the suffix @code{-intro} or
+ @code{-cont} respectively.  As a sub-classification of this scheme, a
+ line which is the first of a particular brace block construct will
+ contain the suffix @code{-block-intro}.
+ 
+ Let's look at some examples to understand how this works.  Remember that
+ you can check the syntax of any line by using @kbd{C-c C-s}.
+ 
+ @example
+  1: void
+  2: swap( int& a, int& b )
+  3: @{
+  4:     int tmp = a;
+  5:     a = b;
+  6:     b = tmp;
+  7:     int ignored =
+  8:         a + b;
+  9: @}
+ @end example
+ 
+ @ssindex topmost-intro
+ @ssindex topmost-intro-cont
+ @ssindex defun-open
+ @ssindex defun-close
+ @ssindex defun-block-intro
+ Line 1 shows a @code{topmost-intro} since it is the first line that
+ introduces a top-level construct.  Line 2 is a continuation of the
+ top-level construct introduction so it has the syntax
+ @code{topmost-intro-cont}.  Line 3 shows a @code{defun-open} since it is
+ the brace that opens a top-level function definition.  Line 9 is the
+ corresponding
+ @code{defun-close} since it contains the brace that closes the top-level
+ function definition.  Line 4 is a @code{defun-block-intro}, i.e., it is
+ the first line of a brace-block, enclosed in a
+ top-level function definition.
+ 
+ @ssindex statement
+ @ssindex statement-cont
+ Lines 5, 6, and 7 are all given @code{statement} syntax since there
+ isn't much special about them.  Note however that line 8 is given
+ @code{statement-cont} syntax since it continues the statement begun
+ on the previous line.
+ 
+ Here's another example, which illustrates some C++ class syntactic
+ symbols:
+ 
+ @example
+  1: class Bass
+  2:     : public Guitar,
+  3:       public Amplifiable
+  4: @{
+  5: public:
+  6:     Bass()
+  7:         : eString( new BassString( 0.105 )),
+  8:           aString( new BassString( 0.085 )),
+  9:           dString( new BassString( 0.065 )),
+ 10:           gString( new BassString( 0.045 ))
+ 11:     @{
+ 12:         eString.tune( 'E' );
+ 13:         aString.tune( 'A' );
+ 14:         dString.tune( 'D' );
+ 15:         gString.tune( 'G' );
+ 16:     @}
+ 17:     friend class Luthier;
+ 18: @};
+ @end example
+ 
+ @ssindex class-open
+ @ssindex class-close
+ As in the previous example, line 1 has the @code{topmost-intro} syntax.
+ Here however, the brace that opens a C++ class definition on line 4 is
+ assigned the @code{class-open} syntax.  Note that in C++, classes,
+ structs, and unions are essentially equivalent syntactically (and are
+ very similar semantically), so replacing the @code{class} keyword in the
+ example above with @code{struct} or @code{union} would still result in a
+ syntax of @code{class-open} for line 4 @footnote{This is the case even
+ for C and Objective-C.  For consistency, structs in all supported
+ languages are syntactically equivalent to classes.  Note however that
+ the keyword @code{class} is meaningless in C and Objective-C.}.
+ Similarly, line 18 is assigned @code{class-close} syntax.
+ 
+ @ssindex inher-intro
+ @ssindex inher-cont
+ Line 2 introduces the inheritance list for the class so it is assigned
+ the @code{inher-intro} syntax, and line 3, which continues the
+ inheritance list is given @code{inher-cont} syntax.
+ 
+ @ssindex access-label
+ @ssindex inclass
+ Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
+ 
+ @example
+ ((inclass 58) (access-label 58))
+ @end example
+ 
+ @noindent
+ The primary syntactic symbol for this line is @code{access-label} as
+ this a label keyword that specifies access protection in C++.  However,
+ because this line is also a top-level construct inside a class
+ definition, the analysis actually shows two syntactic symbols.  The
+ other syntactic symbol assigned to this line is @code{inclass}.
+ Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
+ syntax:
+ 
+ @example
+ ((inclass 58) (topmost-intro 60))
+ @end example
+ 
+ @ssindex member-init-intro
+ @ssindex member-init-cont
+ Line 7 introduces a C++ member initialization list and as such is given
+ @code{member-init-intro} syntax.  Note that in this case it is
+ @emph{not} assigned @code{inclass} since this is not considered a
+ top-level construct.  Lines 8 through 10 are all assigned
+ @code{member-init-cont} since they continue the member initialization
+ list started on line 7.
+ 
+ @cindex in-class inline methods
+ @ssindex inline-open
+ @ssindex inline-close
+ Line 11's analysis is a bit more complicated:
+ 
+ @example
+ ((inclass 58) (inline-open))
+ @end example
+ 
+ This line is assigned a syntax of both @code{inline-open} and
+ @code{inclass} because it opens an @dfn{in-class} C++ inline method
+ definition.  This is distinct from, but related to, the C++ notion of an
+ inline function in that its definition occurs inside an enclosing class
+ definition, which in C++ implies that the function should be inlined.
+ However, if the definition of the @code{Bass} constructor appeared
+ outside the class definition, the construct would be given the
+ @code{defun-open} syntax, even if the keyword @code{inline} appeared
+ before the method name, as in:
+ 
+ @example
+  1: class Bass
+  2:     : public Guitar,
+  3:       public Amplifiable
+  4: @{
+  5: public:
+  6:     Bass();
+  7: @};
+  8:
+  9: inline
+ 10: Bass::Bass()
+ 11:     : eString( new BassString( 0.105 )),
+ 12:       aString( new BassString( 0.085 )),
+ 13:       dString( new BassString( 0.065 )),
+ 14:       gString( new BassString( 0.045 ))
+ 15: @{
+ 16:     eString.tune( 'E' );
+ 17:     aString.tune( 'A' );
+ 18:     dString.tune( 'D' );
+ 19:     gString.tune( 'G' );
+ 20: @}
+ @end example
+ 
+ @ssindex friend
+ Returning to the previous example, line 16 is given @code{inline-close}
+ syntax, while line 12 is given @code{defun-block-open} syntax, and lines
+ 13 through 15 are all given @code{statement} syntax.  Line 17 is
+ interesting in that its syntactic analysis list contains three
+ elements:
+ 
+ @example
+ ((inclass 58) (topmost-intro 380) (friend))
+ @end example
+ 
+ The @code{friend} syntactic symbol is a modifier that typically does not
+ have a relative buffer position.
+ 
+ Template definitions introduce yet another syntactic symbol:
+ 
+ @example
+  1: ThingManager <int,
+  2:    Framework::Callback *,
+  3:    Mutex> framework_callbacks;
+ @end example
+ 
+ Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
+ are both analyzed as @code{template-args-cont} lines.
+ 
+ Here is another (totally contrived) example which illustrates how syntax
+ is assigned to various conditional constructs:
+ 
+ @example
+  1: void spam( int index )
+  2: @{
+  3:     for( int i=0; i<index; i++ )
+  4:     @{
+  5:         if( i == 10 )
+  6:             do_something_special();
+  7:         else
+  8:           silly_label:
+  9:             do_something( i );
+ 10:     @}
+ 11:     do @{
+ 12:         another_thing( i-- );
+ 13:     @}
+ 14:     while( i > 0 );
+ 15: @}
+ @end example
+ 
+ Only the lines that illustrate new syntactic symbols will be discussed.
+ 
+ @ssindex substatement-open
+ @ssindex substatement-block-intro
+ @ssindex block-close
+ Line 4 has a brace which opens a conditional's substatement block.  It
+ is thus assigned @code{substatement-open} syntax, and since line 5 is
+ the first line in the substatement block, it is assigned
+ @code{substatement-block-intro} syntax.  Line 10 contains the brace that
+ closes the inner substatement block, and is therefore given the syntax
+ @code{block-close}.  Line 13 is treated the same way.
+ 
+ @ssindex substatement
+ Lines 6 and 9 are also substatements of conditionals, but since they
+ don't start blocks they are given @code{substatement} syntax
+ instead of @code{substatement-open}.
+ 
+ @ssindex substatement-label
+ Line 8 contains a label, which is normally given @code{label} syntax.
+ This one is however a bit special since it's between a conditional and
+ its substatement.  It's analyzed as @code{substatement-label} to let you
+ handle this rather odd case differently from normal labels.
+ 
+ @ssindex else-clause
+ @ssindex catch-clause
+ Line 7 start with an @code{else} that matches the @code{if} statement on
+ line 5.  It is therefore given the @code{else-clause} syntax and is
+ anchored on the matching @code{if}.  The @address@hidden
+ constructs in C++ and Java are treated this way too, except that
+ @code{catch} and (in Java) @code{finally}, are marked with
+ @code{catch-clause}.
+ 
+ @ssindex do-while-closure
+ The @code{while} construct on line 14 that closes a @code{do}
+ conditional is given the special syntax @code{do-while-closure} if it
+ appears on a line by itself.  Note that if the @code{while} appeared on
+ the same line as the preceding close brace, that line would still have
+ @code{block-close} syntax.
+ 
+ Switch statements have their own set of syntactic symbols.  Here's an
+ example:
+ 
+ @example
+  1: void spam( enum Ingredient i )
+  2: @{
+  3:     switch( i ) @{
+  4:     case Ham:
+  5:         be_a_pig();
+  6:         break;
+  7:     case Salt:
+  8:         drink_some_water();
+  9:         break;
+ 10:     default:
+ 11:         @{
+ 12:             what_is_it();
+ 13:             break;
+ 14:         @}
+ 15:     @}
+ 14: @}
+ @end example
+ 
+ @ssindex case-label
+ @ssindex statement-case-intro
+ @ssindex statement-case-open
+ Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
+ while lines 5 and 8 are assigned @code{statement-case-intro}.  Line 11
+ is treated slightly differently since it contains a brace that opens a
+ block --- it is given @code{statement-case-open} syntax.
+ 
+ @cindex brace lists
+ There are a set of syntactic symbols that are used to recognize
+ constructs inside of brace lists.  A brace list is defined as an
+ @code{enum} or aggregate initializer list, such as might statically
+ initialize an array of structs.  The three special aggregate constructs
+ in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
+ brace lists too.  An example:
+ 
+ @example
+  1: static char* ingredients[] =
+  2: @{
+  3:     "Ham",
+  4:     "Salt",
+  5:     NULL
+  6: @};
+ @end example
+ 
+ @ssindex brace-list-open
+ @ssindex brace-list-intro
+ @ssindex brace-list-close
+ @ssindex brace-list-entry
+ Following convention, line 2 in this example is assigned
+ @code{brace-list-open} syntax, and line 3 is assigned
+ @code{brace-list-intro} syntax.  Likewise, line 6 is assigned
+ @code{brace-list-close} syntax.  Lines 4 and 5 however, are assigned
+ @code{brace-list-entry} syntax, as would all subsequent lines in this
+ initializer list.
+ 
+ @ssindex brace-entry-open
+ Your static initializer might be initializing nested structures, for
+ example:
+ 
+ @example
+  1: struct intpairs[] =
+  2: @{
+  3:     @{ 1, 2 @},
+  4:     @{
+  5:         3,
+  6:         4
+  7:     @}
+  8:     @{ 1,
+  9:       2 @},
+ 10:     @{ 3, 4 @}
+ 11: @};
+ @end example
+ 
+ Here, you've already seen the analysis of lines 1, 2, 3, and 11.  On
+ line 4, things get interesting; this line is assigned
+ @code{brace-entry-open} syntactic symbol because it's a bracelist entry
+ line that starts with an open brace.  Lines 5 and 6 (and line 9) are
+ pretty standard, and line 7 is a @code{brace-list-close} as you'd
+ expect.  Once again, line 8 is assigned as @code{brace-entry-open} as is
+ line 10.
+ 
+ External language definition blocks also have their own syntactic
+ symbols.  In this example:
+ 
+ @example
+  1: extern "C"
+  2: @{
+  3:     int thing_one( int );
+  4:     int thing_two( double );
+  5: @}
+ @end example
+ 
+ @ssindex extern-lang-open
+ @ssindex extern-lang-close
+ @ssindex inextern-lang
+ @ssindex inclass
+ @noindent
+ line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
+ the @code{extern-lang-close} syntax.  The analysis for line 3 yields:
+ 
+ @example
+ ((inextern-lang) (topmost-intro 14))
+ @end example
+ 
+ @noindent
+ where @code{inextern-lang} is a modifier similar in purpose to
+ @code{inclass}.
+ 
+ There are various other top level blocks like @code{extern}, and they
+ are all treated in the same way except that the symbols are named after
+ the keyword that introduces the block.  e.g., C++ namespace blocks get
+ the three symbols @code{namespace-open}, @code{namespace-close} and
+ @code{innamespace}.  The currently recognized top level blocks are:
+ 
+ @table @asis
+ @item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
+ @code{extern} blocks in C and address@hidden should logically be
+ named @code{extern-open}, @code{extern-close} and @code{inextern}, but
+ that isn't the case for historical reasons.}
+ 
+ @item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
+ @ssindex namespace-open
+ @ssindex namespace-close
+ @ssindex innamespace
+ @code{namespace} blocks in C++.
+ 
+ @item @code{module-open}, @code{module-close}, @code{inmodule}
+ @ssindex module-open
+ @ssindex module-close
+ @ssindex inmodule
+ @code{module} blocks in CORBA IDL.
+ 
+ @item @code{composition-open}, @code{composition-close}, @code{incomposition}
+ @ssindex composition-open
+ @ssindex composition-close
+ @ssindex incomposition
+ @code{composition} blocks in CORBA CIDL.
+ @end table
+ 
+ A number of syntactic symbols are associated with parenthesis lists,
+ a.k.a argument lists, as found in function declarations and function
+ calls.  This example illustrates these:
+ 
+ @example
+  1: void a_function( int line1,
+  2:                  int line2 );
+  3: 
+  4: void a_longer_function(
+  5:     int line1,
+  6:     int line2
+  7:     );
+  8: 
+  9: void call_them( int line1, int line2 )
+ 10: @{
+ 11:     a_function(
+ 12:         line1,
+ 13:         line2
+ 14:         );
+ 15: 
+ 16:     a_longer_function( line1,
+ 17:                        line2 );
+ 18: @}
+ @end example
+ 
+ @ssindex arglist-intro
+ @ssindex arglist-close
+ Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
+ the first line following the open parenthesis, and lines 7 and 14 are
+ assigned @code{arglist-close} syntax since they contain the parenthesis
+ that closes the argument list.
+ 
+ @ssindex arglist-cont-nonempty
+ @ssindex arglist-cont
+ Lines that continue argument lists can be assigned one of two syntactic
+ symbols.  For example, Lines 2 and 17
+ are assigned @code{arglist-cont-nonempty} syntax.  What this means
+ is that they continue an argument list, but that the line containing the
+ parenthesis that opens the list is @emph{not empty} following the open
+ parenthesis.  Contrast this against lines 6 and 13 which are assigned
+ @code{arglist-cont} syntax.  This is because the parenthesis that opens
+ their argument lists is the last character on that line.
+ 
+ Note that there is no @code{arglist-open} syntax.  This is because any
+ parenthesis that opens an argument list, appearing on a separate line,
+ is assigned the @code{statement-cont} syntax instead.
+ 
+ A few miscellaneous syntactic symbols that haven't been previously
+ covered are illustrated by this C++ example:
+ 
+ @example
+  1: void Bass::play( int volume )
+  2: const
+  3: @{
+  4:     /* this line starts a multiline
+  5:      * comment.  This line should get `c' syntax */
+  6: 
+  7:     char* a_multiline_string = "This line starts a multiline \
+  8: string.  This line should get `string' syntax.";
+  9: 
+ 10:   note:
+ 11:     @{
+ 12: #ifdef LOCK
+ 13:         Lock acquire();
+ 14: #endif // LOCK
+ 15:         slap_pop();
+ 16:         cout << "I played "
+ 17:              << "a note\n";
+ 18:     @}
+ 19: @}
+ @end example
+ 
+ The lines to note in this example include:
+ 
+ @itemize @bullet
+ @item
+ @ssindex func-decl-cont
+ Line 2 is assigned the @code{func-decl-cont} syntax.
+ 
+ @item
+ @ssindex comment-intro
+ Line 4 is assigned both @code{defun-block-intro} @emph{and}
+ @code{comment-intro} syntax.
+ 
+ @item
+ @ssindex c
+ Line 5 is assigned @code{c} syntax.
+ 
+ @item
+ @cindex syntactic whitespace
+ Line 6 which, even though it contains nothing but whitespace, is
+ assigned @code{defun-block-intro}.  Note that the appearance of the
+ comment on lines 4 and 5 do not cause line 6 to be assigned
+ @code{statement} syntax because comments are considered to be
+ @dfn{syntactic whitespace}, which are ignored when analyzing
+ code.
+ 
+ @item
+ @ssindex string
+ Line 8 is assigned @code{string} syntax.
+ 
+ @item
+ @ssindex label
+ Line 10 is assigned @code{label} syntax.
+ 
+ @item
+ @ssindex block-open
+ Line 11 is assigned @code{block-open} syntax.
+ 
+ @item
+ @ssindex cpp-macro
+ Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
+ normal syntactic symbols (@code{statement-block-intro} and
+ @code{statement}, respectively).  Normally @code{cpp-macro} is
+ configured to cancel out the normal syntactic context to make all
+ preprocessor directives stick to the first column, but that's easily
+ changed if you want preprocessor directives to be indented like the rest
+ of the code.
+ 
+ @item
+ @ssindex stream-op
+ Line 17 is assigned @code{stream-op} syntax.
+ @end itemize
+ 
+ @cindex multiline macros
+ @cindex syntactic whitespace
+ @ssindex cpp-define-intro
+ Multiline preprocessor macro definitions are normally handled just like
+ other code, i.e., the lines inside them are indented according to the
+ syntactic analysis of the preceding lines inside the macro.  The first
+ line inside a macro definition (i.e., the line after the starting line of
+ the cpp directive itself) gets @code{cpp-define-intro}.  In this example:
+ 
+ @example
+  1: #define LIST_LOOP(cons, listp)                         \
+  2:   for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
+  3:     if (!CONSP (cons))                                 \
+  4:       signal_error ("Invalid list format", listp);     \
+  5:     else
+ @end example
+ 
+ @noindent
+ line 1 is given the syntactic symbol @code{cpp-macro}.  The first line
+ of a cpp directive is always given that symbol.  Line 2 is given
+ @code{cpp-define-intro}, so that you can give the macro body as a whole
+ some extra indentation.  Lines 3 through 5 are then analyzed as normal
+ code, i.e., @code{substatement} on lines 3 and 4, and @code{else-clause}
+ on line 5.
+ 
+ The syntactic analysis inside macros can be turned off with
+ @code{c-syntactic-indentation-in-macros}.  In that case, lines 2 through
+ 5 would all be given @code{cpp-macro-cont} with a relative buffer
+ position pointing to the @code{#} which starts the cpp
+ address@hidden is how @ccmode{} 5.28 and earlier analyzed
+ macros.}.
+ 
+ @xref{Macro Handling}, for more info about the treatment of macros.
+ 
+ In Objective-C buffers, there are three additional syntactic symbols
+ assigned to various message calling constructs.  Here's an example
+ illustrating these:
+ 
+ @example
+  1: - (void)setDelegate:anObject
+  2:           withStuff:stuff
+  3: @{
+  4:     [delegate masterWillRebind:self
+  5:               toDelegate:anObject
+  6:               withExtraStuff:stuff];
+  7: @}
+ @end example
+ 
+ @ssindex objc-method-intro
+ @ssindex objc-method-args-cont
+ @ssindex objc-method-call-cont
+ Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
+ assigned @code{objc-method-args-cont} syntax.  Lines 5 and 6 are both
+ assigned @code{objc-method-call-cont} syntax.
+ 
+ Java has a concept of anonymous classes, which may look something like
+ this:
+ 
+ @example
+  1: public void watch(Observable o) @{
+  2:     o.addObserver(new Observer() @{
+  3:             public void update(Observable o, Object arg) @{
+  4:                 history.addElement(arg);
+  5:             @}
+  6:         @});
+  7: @}
+ @end example
+ 
+ @ssindex inexpr-class
+ The brace following the @code{new} operator opens the anonymous class.
+ Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the
+ @code{inclass} symbol used in normal classes.  Thus, the class will be
+ indented just like a normal class, with the added indentation given to
+ @code{inexpr-class}.
+ 
+ There are a few occasions where a statement block may be used inside an
+ expression.  One is in C or C++ code using the gcc extension for this,
+ e.g:
+ 
+ @example
+  1: int res = (@{
+  2:         int y = foo (); int z;
+  3:         if (y > 0) z = y; else z = - y;
+  4:         z;
+  5:     @});
+ @end example
+ 
+ @ssindex inexpr-statement
+ Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
+ symbols they'd get in a normal block.  Therefore, the indentation put on
+ @code{inexpr-statement} is added to the normal statement block
+ indentation.
+ 
+ In Pike code, there are a few other situations where blocks occur inside
+ statements, as illustrated here:
+ 
+ @example
+  1: array itgob()
+  2: @{
+  3:     string s = map (backtrace()[-2][3..],
+  4:                     lambda
+  5:                         (mixed arg)
+  6:                     @{
+  7:                         return sprintf ("%t", arg);
+  8:                     @}) * ", " + "\n";
+  9:     return catch @{
+ 10:             write (s + "\n");
+ 11:         @};
+ 12: @}
+ @end example
+ 
+ @ssindex inlambda
+ @ssindex lambda-intro-cont
+ Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
+ by the @code{lambda} keyword.  If the function argument list is put
+ on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
+ syntax.  The function body is handled as an inline method body, with the
+ addition of the @code{inlambda} syntactic symbol.  This means that line
+ 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
+ @address@hidden might wonder why it doesn't get
+ @code{inlambda} too.  It's because the closing brace is relative to the
+ opening brace, which stands on its own line in this example.  If the
+ opening brace was hanging on the previous line, then the closing brace
+ would get the @code{inlambda} syntax too to be indented correctly.}.
+ 
+ @ssindex inexpr-statement
+ On line 9, @code{catch} is a special function taking a statement block
+ as its argument.  The block is handled as an in-expression statement
+ with the @code{inexpr-statement} syntax, just like the gcc extended C
+ example above.  The other similar special function, @code{gauge}, is
+ handled like this too.
+ 
+ @ssindex knr-argdecl-intro
+ @ssindex knr-argdecl
+ Two other syntactic symbols can appear in old style, non-prototyped C
+ code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
+ 
+ @example
+  1: int add_three_integers(a, b, c)
+  2:      int a;
+  3:      int b;
+  4:      int c;
+  5: @{
+  6:     return a + b + c;
+  7: @}
+ @end example
+ 
+ Here, line 2 is the first line in an argument declaration list and so is
+ given the @code{knr-argdecl-intro} syntactic symbol.  Subsequent lines
+ (i.e., lines 3 and 4 in this example), are given @code{knr-argdecl}
+ syntax.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Indentation Functions, AWK Mode, Syntactic Symbols, Top
+ @comment node-name, next, previous, up
+ @chapter Indentation Functions
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @cindex indentation function
+ @cindex line-up function
+ Often there are cases when a simple offset setting on a syntactic
+ symbol isn't enough to get the desired indentation.  Therefore, it's
+ also possible to use an @dfn{indentation function} (a.k.a. @dfn{line-up
+ function}) for a syntactic symbol.
+ 
+ @ccmode{} comes with many predefined indentation functions for common
+ situations.  If none of these does what you want, you can write your
+ own, see @ref{Custom Indentation Functions}.  If you do, it's probably a
+ good idea to start working from one of these predefined functions, they
+ can be found in the file @file{cc-align.el}.
+ 
+ For every function below there is a ``works with'' list that indicates
+ which syntactic symbols the function is intended to be used with.
+ 
+ @macro workswith
+ @emph{Works with:@ }
+ @end macro
+ @ifinfo
+ @unmacro workswith
+ @macro workswith
+ Works with:
+ @end macro
+ @end ifinfo
+ 
+ @macro sssTBasicOffset
+ <--> @address@hidden
+ @end macro
+ 
+ @macro sssTsssTBasicOffset
+ <--><--> @address@hidden
+ @end macro
+ 
+ @macro hereFn{func}
+ <- @address@hidden
+ @end macro
+ 
+ @c The TeX backend seems to insert extra spaces around the argument. :P
+ @iftex
+ @unmacro hereFn
+ @macro hereFn{func}
+ <address@hidden@c
+ @end macro
+ @end iftex
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-indent-one-line-block
+ @findex indent-one-line-block (c-)
+ Indent a one line block @code{c-basic-offset} extra.  E.g:
+ 
+ @example
+ @group
+ if (n > 0)
+     @{m+=n; n=0;@}      @hereFn{c-indent-one-line-block}
+ @sssTBasicOffset{}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ if (n > 0)
+ @{                     @hereFn{c-indent-one-line-block}
+     m+=n; n=0;
+ @}
+ @end group
+ @end example
+ 
+ The block may be surrounded by any kind of parenthesis characters.
+ @code{nil} is returned if the line doesn't start with a one line block,
+ which makes the function usable in list expressions.
+ 
+ @workswith Almost all syntactic symbols, but most useful on the
+ @code{-open} symbols.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-indent-multi-line-block
+ @findex indent-multi-line-block (c-)
+ Indent a multiline block @code{c-basic-offset} extra.  E.g:
+ 
+ @example
+ @group
+ int *foo[] = @{
+     NULL,                 
+     @address@hidden,             @hereFn{c-indent-multi-line-block}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ int *foo[] = @{
+     NULL,
+         @{             @hereFn{c-indent-multi-line-block}
+         17
+         @},
+     @sssTBasicOffset{}
+ @end group
+ @end example
+ 
+ The block may be surrounded by any kind of parenthesis characters.
+ @code{nil} is returned if the line doesn't start with a multiline
+ block, which makes the function usable in list expressions.
+ 
+ @workswith Almost all syntactic symbols, but most useful on the
+ @code{-open} symbols.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-argcont
+ @findex lineup-argcont (c-)
+ Line up a continued argument.  E.g:
+ 
+ @example
+ @group
+ foo (xyz, aaa + bbb + ccc
+           + ddd + eee + fff);  @hereFn{c-lineup-argcont}
+ @end group
+ @end example
+ 
+ Only continuation lines like this are touched, @code{nil} is returned on
+ lines which are the start of an argument.
+ 
+ Within a gcc @code{asm} block, @code{:} is recognised as an argument
+ separator, but of course only between operand specifications, not in the
+ expressions for the operands.
+ 
+ @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-arglist
+ @findex lineup-arglist (c-)
+ Line up the current argument line under the first argument.
+ 
+ As a special case, if an argument on the same line as the open
+ parenthesis starts with a brace block opener, the indentation is
+ @code{c-basic-offset} only.  This is intended as a ``DWIM'' measure in
+ cases like macros that contains statement blocks, e.g:
+ 
+ @example
+ @group
+ A_VERY_LONG_MACRO_NAME (@{
+         some (code, with + long, lines * in[it]);
+     @});
+ @sssTBasicOffset{}
+ @end group
+ @end example
+ 
+ This is motivated partly because it's more in line with how code
+ blocks are handled, and partly since it approximates the behavior of
+ earlier CC Mode versions, which due to inaccurate analysis tended to
+ indent such cases this way.
+ 
+ @workswith @code{arglist-cont-nonempty}, @code{arglist-close}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-arglist-intro-after-paren
+ @findex lineup-arglist-intro-after-paren (c-)
+ Line up a line to just after the open paren of the surrounding paren or
+ brace block.
+ 
+ @workswith @code{defun-block-intro}, @code{brace-list-intro},
+ @code{statement-block-intro}, @code{statement-case-intro},
+ @code{arglist-intro}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-arglist-close-under-paren
+ @findex lineup-arglist-close-under-paren (c-)
+ 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.  It can also be used with
+ @code{arglist-cont} and @code{arglist-cont-nonempty} to line up all
+ lines inside a parenthesis under the open paren.
+ 
+ As a special case, if a brace block is opened at the same line as the
+ open parenthesis of the argument list, the indentation is
+ @code{c-basic-offset} only.  See @code{c-lineup-arglist} for further
+ discussion of this ``DWIM'' measure.
+ 
+ @workswith Almost all symbols, but are typically most useful on
+ @code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and
+ @code{arglist-cont-nonempty}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-arglist-operators
+ @findex lineup-arglist-operators (c-)
+ Line up lines starting with an infix operator under the open paren.
+ Return @code{nil} on lines that don't start with an operator, to leave
+ those cases to other lineup functions.  Example:
+ 
+ @example
+ @group
+ if (  x < 10
+    || at_limit (x,     @hereFn{c-lineup-arglist-operators}
+                 list)  @address@hidden returns nil}}
+    )
+ @end group
+ @end example
+ 
+ Since this function doesn't do anything for lines without an infix
+ operator you typically want to use it together with some other lineup
+ settings, e.g., as follows (the @code{arglist-close} setting is just a
+ suggestion to get a consistent style):
+ 
+ @example
+ (c-set-offset 'arglist-cont
+               '(c-lineup-arglist-operators 0))
+ (c-set-offset 'arglist-cont-nonempty
+               '(c-lineup-arglist-operators c-lineup-arglist))
+ (c-set-offset 'arglist-close
+               '(c-lineup-arglist-close-under-paren))
+ @end example
+ 
+ @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-C-comments
+ @findex lineup-C-comments (c-)
+ Line up C block comment continuation lines.  Various heuristics are used
+ to handle most of the common comment styles.  Some examples:
+ 
+ @example
+ @group
+ /*                 /**               /*
+  * text             * text             text
+  */                 */               */
+ @end group
+ @end example
+ 
+ @example
+ @group
+ /* text            /*                /**
+    text            ** text            ** text
+ */                 */                 */
+ @end group
+ @end example
+ 
+ @example
+ @group
+ /**************************************************
+  * text
+  *************************************************/
+ @end group
+ @end example
+ 
+ @vindex comment-start-skip
+ @example
+ @group
+ /**************************************************
+     Free form text comments:
+  In comments with a long delimiter line at the
+  start, the indentation is kept unchanged for lines
+  that start with an empty comment line prefix.  The
+  delimiter line is whatever matches the
+  @code{comment-start-skip} regexp.
+ **************************************************/
+ @end group
+ @end example
+ 
+ The style variable @code{c-comment-prefix-regexp} is used to recognize
+ the comment line prefix, e.g., the @samp{*} that usually starts every
+ line inside a comment.
+ 
+ @workswith The @code{c} syntactic symbol.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-cascaded-calls
+ @findex lineup-cascaded-calls (c-)
+ Line up ``cascaded calls'' under each other.  If the line begins with
+ @code{->} or @code{.} and the preceding line ends with one or more
+ function calls preceded by the same token, then the arrow is lined up
+ with the first of those tokens.  E.g:
+ 
+ @example
+ @group
+ r = proc->add(17)->add(18)
+         ->add(19) +         @hereFn{c-lineup-cascaded-calls}
+   offset;                   @address@hidden (inactive)}}
+ @end group
+ @end example
+ 
+ In any other situation @code{nil} is returned to allow use in list
+ expressions.
+ 
+ @workswith @code{topmost-intro-cont}, @code{statement-cont},
+ @code{arglist-cont}, @code{arglist-cont-nonempty}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-close-paren
+ @findex lineup-close-paren (c-)
+ Line up the closing paren under its corresponding open paren if the
+ open paren is followed by code.  If the open paren ends its line, no
+ indentation is added.  E.g:
+ 
+ @example
+ @group
+ main (int,
+       char **           
+      )                @hereFn{c-lineup-close-paren}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ main (
+     int, char **
+ )                     @hereFn{c-lineup-close-paren}
+ @end group
+ @end example
+ 
+ As a special case, if a brace block is opened at the same line as the
+ open parenthesis of the argument list, the indentation is
+ @code{c-basic-offset} instead of the open paren column.  See
+ @code{c-lineup-arglist} for further discussion of this ``DWIM'' measure.
+ 
+ @workswith All @code{*-close} symbols.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-comment
+ @findex lineup-comment (c-)
+ Line up a comment-only line according to the style variable
+ @code{c-comment-only-line-offset}.  If the comment is lined up with a
+ comment starter on the previous line, that alignment is preserved.
+ 
+ @defopt c-comment-only-line-offset
+ @vindex comment-only-line-offset (c-)
+ This style variable specifies the extra offset for the line.  It can
+ contain an integer or a cons cell of the form
+ 
+ @example
+ (@address@hidden . @address@hidden)
+ @end example
+ 
+ @noindent
+ where @var{non-anchored-offset} is the amount of offset given to
+ non-column-zero anchored lines, and @var{anchored-offset} is the amount
+ of offset to give column-zero anchored lines.  Just an integer as value
+ is equivalent to @code{(@address@hidden . -1000)}.
+ @end defopt
+ 
+ @workswith @code{comment-intro}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-cpp-define
+ @findex lineup-cpp-define (c-)
+ Line up macro continuation lines according to the indentation of the
+ construct preceding the macro.  E.g:
+ 
+ @example
+ @group
+ const char msg[] =    @address@hidden beginning of the preceding construct.}}
+   \"Some text.\";
+ 
+ #define X(A, B)  \
+ do @{             \    @hereFn{c-lineup-cpp-define}
+   printf (A, B); \
+ @} while (0)
+ @end group
+ @end example
+ 
+ @noindent
+ and:
+ 
+ @example
+ @group
+ int dribble() @{
+   if (!running)       @address@hidden beginning of the preceding construct.}}
+     error(\"Not running!\");
+ 
+ #define X(A, B)    \
+   do @{             \  @hereFn{c-lineup-cpp-define}
+     printf (A, B); \
+   @} while (0)
+ @end group
+ @end example
+ 
+ If @code{c-syntactic-indentation-in-macros} is address@hidden, the
+ function returns the relative indentation to the macro start line to
+ allow accumulation with other offsets.  e.g., in the following cases,
+ @code{cpp-define-intro} is combined with the
+ @code{statement-block-intro} that comes from the @samp{do @{} that hangs
+ on the @samp{#define} line:
+ 
+ @example
+ @group
+ const char msg[] =
+   \"Some text.\";
+ 
+ #define X(A, B) do @{ \
+   printf (A, B);     \  @hereFn{c-lineup-cpp-define}
+   this->refs++;      \
+ @} while (0)             @hereFn{c-lineup-cpp-define}
+ @end group
+ @end example
+ 
+ @noindent
+ and:
+ 
+ @example
+ @group
+ int dribble() @{
+   if (!running)
+     error(\"Not running!\");
+ 
+ #define X(A, B) do @{ \
+     printf (A, B);   \  @hereFn{c-lineup-cpp-define}
+     this->refs++;    \
+   @} while (0)           @hereFn{c-lineup-cpp-define}
+ @end group
+ @end example
+ 
+ The relative indentation returned by @code{c-lineup-cpp-define} is zero
+ and two, respectively, on the two lines in each of these examples.  They
+ are then added to the two column indentation that
+ @code{statement-block-intro} gives in both cases here.
+ 
+ If the relative indentation is zero, then @code{nil} is returned
+ instead.  That is useful in a list expression to specify the default
+ indentation on the top level.
+ 
+ If @code{c-syntactic-indentation-in-macros} is @code{nil} then this
+ function keeps the current indentation, except for empty lines (ignoring
+ the ending backslash) where it takes the indentation from the closest
+ preceding nonempty line in the macro.  If there's no such line in the
+ macro then the indentation is taken from the construct preceding it, as
+ described above.
+ 
+ @workswith @code{cpp-define-intro}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-dont-change
+ @findex lineup-dont-change (c-)
+ This lineup function makes the line stay at whatever indentation it
+ already has; think of it as an identity function for lineups.
+ 
+ @workswith Any syntactic symbol.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-gcc-asm-reg
+ @findex lineup-gcc-asm-reg (c-)
+ Line up a gcc asm register under one on a previous line.
+ 
+ @example
+ @group
+     asm ("foo %1, %0\n"
+          "bar %0, %1"
+          : "=r" (w),
+            "=r" (x)
+          :  "0" (y),
+             "1" (z));
+ @end group
+ @end example
+ 
+ The @samp{x} line is aligned to the text after the @samp{:} on the
+ @samp{w} line, and similarly @samp{z} under @samp{y}.
+ 
+ This is done only in an @samp{asm} or @samp{__asm__} block, and only to
+ those lines mentioned.  Anywhere else @code{nil} is returned.  The usual
+ arrangement is to have this routine as an extra feature at the start of
+ arglist lineups, e.g.
+ 
+ @example
+ (c-lineup-gcc-asm-reg c-lineup-arglist)
+ @end example
+ 
+ @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-inexpr-block
+ @findex lineup-inexpr-block (c-)
+ This can be used with the in-expression block symbols to indent the
+ whole block to the column where the construct is started.  e.g., for Java
+ anonymous classes, this lines up the class under the @samp{new} keyword,
+ and in Pike it lines up the lambda function body under the @samp{lambda}
+ keyword.  Returns @code{nil} if the block isn't part of such a
+ construct.
+ 
+ @workswith @code{inlambda}, @code{inexpr-statement},
+ @code{inexpr-class}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-java-inher
+ @findex lineup-java-inher (c-)
+ Line up Java implements and extends declarations.  If class names
+ follow on the same line as the @samp{implements}/@samp{extends}
+ keyword, they are lined up under each other.  Otherwise, they are
+ indented by adding @code{c-basic-offset} to the column of the keyword.
+ E.g:
+ 
+ @example
+ @group
+ class Foo
+     extends           
+         Bar           @hereFn{c-lineup-java-inher}
+     @sssTBasicOffset{}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ class Foo
+     extends Cyphr,
+             Bar       @hereFn{c-lineup-java-inher}
+ @end group
+ @end example
+ 
+ @workswith @code{inher-cont}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-java-throws
+ @findex lineup-java-throws (c-)
+ Line up Java throws declarations.  If exception names follow on the
+ same line as the throws keyword, they are lined up under each other.
+ Otherwise, they are indented by adding @code{c-basic-offset} to the
+ column of the @samp{throws} keyword.  The @samp{throws} keyword itself
+ is also indented by @code{c-basic-offset} from the function declaration
+ start if it doesn't hang.  E.g:
+ 
+ @example
+ @group
+ int foo()
+     throws            @hereFn{c-lineup-java-throws}
+         Bar           @hereFn{c-lineup-java-throws}
+ @sssTsssTBasicOffset{}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ int foo() throws Cyphr,
+                  Bar,    @hereFn{c-lineup-java-throws}
+                  Vlod    @hereFn{c-lineup-java-throws}
+ @end group
+ @end example
+ 
+ @workswith @code{func-decl-cont}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-knr-region-comment
+ @findex lineup-knr-region-comment (c-)
+ Line up a comment in the ``K&R region'' with the declaration.  That is
+ the region between the function or class header and the beginning of the
+ block.  E.g:
+ 
+ @example
+ @group
+ int main()
+ /* Called at startup. */  @hereFn{c-lineup-knr-region-comment}
+ @{
+   return 0;
+ @}
+ @end group
+ @end example
+ 
+ Return @code{nil} if called in any other situation, to be useful in list
+ expressions.
+ 
+ @workswith @code{comment-intro}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-math
+ @findex lineup-math (c-)
+ Line up the current line to after the equal sign on the first line in the
+ statement.  If there isn't any, indent with @code{c-basic-offset}.  If
+ the current line contains an equal sign too, try to align it with the
+ first one.
+ 
+ @workswith @code{topmost-intro-cont}, @code{statement-cont},
+ @code{arglist-cont}, @code{arglist-cont-nonempty}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-multi-inher
+ @findex lineup-multi-inher (c-)
+ Line up the classes in C++ multiple inheritance clauses and member
+ initializers under each other.  E.g:
+ 
+ @example
+ @group
+ Foo::Foo (int a, int b):
+     Cyphr (a),
+     Bar (b)           @hereFn{c-lineup-multi-inher}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ class Foo
+     : public Cyphr,
+       public Bar      @hereFn{c-lineup-multi-inher}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ Foo::Foo (int a, int b)
+     : Cyphr (a)
+     , Bar (b)         @hereFn{c-lineup-multi-inher}
+ @end group
+ @end example
+ 
+ @workswith @code{inher-cont}, @code{member-init-cont}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-ObjC-method-call
+ @findex lineup-ObjC-method-call (c-)
+ For Objective-C code, line up selector args as Emacs Lisp mode does
+ with function args: go to the position right after the message receiver,
+ and if you are at the end of the line, indent the current line
+ c-basic-offset columns from the opening bracket; otherwise you are
+ looking at the first character of the first method call argument, so
+ lineup the current line with it.
+ 
+ @workswith @code{objc-method-call-cont}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-ObjC-method-args
+ @findex lineup-ObjC-method-args (c-)
+ For Objective-C code, line up the colons that separate args.  The colon
+ on the current line is aligned with the one on the first line.
+ 
+ @workswith @code{objc-method-args-cont}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-ObjC-method-args-2
+ @findex lineup-ObjC-method-args-2 (c-)
+ Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on
+ the current line with the colon on the previous line.
+ 
+ @workswith @code{objc-method-args-cont}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-runin-statements
+ @findex lineup-runin-statements (c-)
+ Line up statements for coding standards which place the first statement
+ in a block on the same line as the block opening address@hidden
+ style doesn't really work too well.  You might need to write your own
+ custom indentation functions to better support this style.}.  E.g:
+ 
+ @example
+ @group
+ int main()
+ @{ puts ("Hello!");
+   return 0;           @hereFn{c-lineup-runin-statements}
+ @}
+ @end group
+ @end example
+ 
+ If there is no statement after the opening brace to align with,
+ @code{nil} is returned.  This makes the function usable in list
+ expressions.
+ 
+ @workswith The @code{statement} syntactic symbol.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-streamop
+ @findex lineup-streamop (c-)
+ Line up C++ stream operators (i.e., @samp{<<} and @samp{>>}).
+ 
+ @workswith @code{stream-op}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-string-cont
+ @findex lineup-string-cont (c-)
+ Line up a continued string under the one it continues.  A continued
+ string in this sense is where a string literal follows directly after
+ another one.  E.g:
+ 
+ @example
+ @group
+ result = prefix + "A message "
+                   "string.";    @hereFn{c-lineup-string-cont}
+ @end group
+ @end example
+ 
+ @code{nil} is returned in other situations, to allow stacking with other
+ lineup functions.
+ 
+ @workswith @code{topmost-intro-cont}, @code{statement-cont},
+ @code{arglist-cont}, @code{arglist-cont-nonempty}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-template-args
+ @findex lineup-template-args (c-)
+ Line up the arguments of a template argument list under each other, but
+ only in the case where the first argument is on the same line as the
+ opening @samp{<}.
+ 
+ To allow this function to be used in a list expression, @code{nil} is
+ returned if there's no template argument on the first line.
+ 
+ @workswith @code{template-args-cont}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-topmost-intro-cont
+ @findex lineup-topmost-intro-cont (c-)
+ Line up declaration continuation lines zero or one indentation
+ address@hidden function is mainly provided to mimic the behavior of
+ CC Mode 5.28 and earlier where this case wasn't handled consistently so
+ that those lines could be analyzed as either topmost-intro-cont or
+ statement-cont.  It's used for @code{topmost-intro-cont} by default, but
+ you might consider using @code{+} instead.}.  For lines preceding a
+ definition, zero is used.  For other lines, @code{c-basic-offset} is
+ added to the indentation.  E.g:
+ 
+ @example
+ @group
+ int
+ neg (int i)           @hereFn{c-lineup-topmost-intro-cont}
+ @{
+     return -i;
+ @}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ struct
+ larch                 @hereFn{c-lineup-topmost-intro-cont}
+ @{
+     double height;
+ @}
+     the_larch,        @hereFn{c-lineup-topmost-intro-cont}
+     another_larch;    @hereFn{c-lineup-topmost-intro-cont}
+ @sssTBasicOffset{}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ struct larch
+ the_larch,            @hereFn{c-lineup-topmost-intro-cont}
+     another_larch;    @hereFn{c-lineup-topmost-intro-cont}
+ @end group
+ @end example
+ 
+ @workswith @code{topmost-intro-cont}.
+ @end defun
+ 
+ @comment ------------------------------------------------------------
+ 
+ @defun c-lineup-whitesmith-in-block
+ @findex lineup-whitesmith-in-block (c-)
+ Line up lines inside a block in Whitesmith style.  It's done in a way
+ that works both when the opening brace hangs and when it doesn't.  E.g:
+ 
+ @example
+ @group
+ something
+     @{
+     foo;              @hereFn{c-lineup-whitesmith-in-block}
+     @}
+ @end group
+ @end example
+ 
+ @noindent
+ and
+ 
+ @example
+ @group
+ something @{
+     foo;              @hereFn{c-lineup-whitesmith-in-block}
+     @}
+ @sssTBasicOffset{}
+ @end group
+ @end example
+ 
+ In the first case the indentation is kept unchanged, in the second
+ @code{c-basic-offset} is added.
+ 
+ @workswith @code{defun-close}, @code{defun-block-intro},
+ @code{block-close}, @code{brace-list-close}, @code{brace-list-intro},
+ @code{statement-block-intro} and all @code{in*} symbols,
+ e.g., @code{inclass} and @code{inextern-lang}.
+ @end defun
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node AWK Mode, Odds and Ends, Indentation Functions, Top
+ @comment  node-name,  next,  previous,  up
+ @chapter Status of AWK Mode
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @dfn{AWK mode} existed until recently in the file @file{awk-mode.el}
+ as a mode derived from c-mode.  It had not been actively maintained to
+ keep pace with the newer @ccmode{}, and its indentation mechanism no
+ longer worked satisfactorally.
+ 
+ The current AWK mode is based around the GNU implementation,
+ @emph{GAWK version 3.1.0}, though it should work pretty well with any
+ AWK.  It has now been updated and integrated into @ccmode{} to a
+ substantial extent, though as yet not all the features of @ccmode{}
+ have been adapted to support it.
+ 
+ If your (X)Emacs is set up to use the old file @file{awk-mode.elc}
+ (which will usually be the case if you have obtained this @ccmode{}
+ independently of (X)Emacs itself), or if you are not sure, insert the
+ following form into your @file{.emacs} or @file{init.el} so that the new
+ AWK mode will be used instead:
+ 
+ @example
+ (autoload 'awk-mode "cc-mode" nil t)
+ @end example
+ 
+ You can check which AWK mode you are running by displaying the mode
+ documentation string with @kbd{C-h m} from an AWK buffer.  The newer
+ mode's doc string contains @code{To submit a problem report, enter
+ `C-c C-b'} near the top of the doc string where the older mode has
+ @code{This is much like C mode except ....}.
+ 
+ Since this newer AWK mode makes essential use of a relatively new
+ Emacs Lisp address@hidden, the @code{syntax-table} text
+ property.}, you need either GNU Emacs 20.1 (or later) or XEmacs 21.4
+ (or later) to use it.  If your Emacs version is earlier than one of
+ these, the older @file{awk-mode.el} will get loaded and run in place
+ of the AWK mode described here, even when you have put the above
+ @code{autoload} form into your @file{.emacs} or @file{init.el}.
+ Upgrading your (X)Emacs is strongly recommended if this is the case.
+ 
+ Here is an overview of which @ccmode{} features currently work with
+ AWK mode and which don't:
+ 
+ @table @asis
+ @item Indentation Engine
+ The @ccmode{} indentation engine fully supports AWK mode.
+ @xref{Indentation Engine}.
+ 
+ AWK mode handles code formatted in the conventional AWK fashion:
+ @address@hidden which start actions, user-defined functions, or compound
+ statements are placed on the same line as the associated construct; the
+ matching @address@hidden are normally placed under the start of the
+ respective pattern, function definition, or structured statement.
+ @c Add in a bit about the @address@hidden being on the same line when the
+ @c contents are short.
+ 
+ The predefined indentation functions (@pxref{Indentation Functions})
+ haven't yet been adapted for AWK mode, though some of them may work
+ serendipitously.  There shouldn't be any problems writing custom
+ indentation functions for AWK mode.
+ 
+ The command @kbd{C-c C-q} (@code{c-indent-defun}) hasn't yet been
+ adapted for AWK, though in practice it works properly nearly all the
+ time.  Should it fail, explicitly set the region around the function
+ (using @kbd{C-u C-SPC}: @kbd{C-M-h} probably won't work either) then do
+ @kbd{C-M-\} (@code{indent-region}).
+ 
+ @item Font Locking
+ There is a single level of font locking in AWK mode, rather than the
+ three distinct levels the other modes have.  There are several
+ idiosyncrasies in AWK mode's font-locking due to the peculiarities of
+ the AWK language itself.  @xref{AWK Mode Font Locking}.
+ 
+ @item Comment Commands
+ @kbd{M-;} (@code{indent-for-comment}) works fine.  None of the other
+ @ccmode{} comment formatting commands have yet been adapted for AWK
+ mode.  @xref{Text Filling and Line Breaking}.
+ 
+ @item Movement Commands
+ Most of the movement commands work in AWK mode.  The most important
+ exceptions are @kbd{M-a} (@code{c-beginning-of-statement}) and
+ @kbd{M-e} (@code{c-end-of-statement}) which haven't yet been adapted.
+ 
+ The notion of @dfn{defun} has been augmented to include pattern-action
+ pairs.  See @ref{AWK Mode Defuns} for a description of commands which
+ work on AWK ``defuns''.
+ 
+ Since there is no preprocessor in AWK, the commands which move to
+ preprocessor directives (e.g., @code{c-up-conditional}) are meaningless
+ in AWK mode and are not bound in the AWK mode keymap.
+ 
+ @item Auto-newline Insertion and Clean-ups
+ Auto-newline insertion hasn't yet been adapted for AWK.  Some of the
+ clean-ups can actually convert good AWK code into syntactically
+ invalid code.
+ 
+ If auto-newline or its associated clean-ups are enabled generally for
+ the modes in @ccmode{}, you are strongly recommended to disable them
+ in the AWK Mode hook.  @xref{Initialising AWK Mode}.
+ 
+ The clean-up @code{space-before-funcall}, which is independent of
+ auto-newline, should never be active in AWK mode (since inserting a
+ space between a user function's name and its opening @samp{(} makes
+ the call syntactically invalid).  If necessary, this should be
+ disabled in the AWK Mode hook.  @xref{Initialising AWK Mode}.
+ 
+ @end table
+ 
+ @menu
+ * Initialising AWK Mode::
+ * AWK Mode Font Locking::
+ * AWK Mode Defuns::
+ @end menu
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node Initialising AWK Mode, AWK Mode Font Locking, , AWK Mode
+ @comment  node-name,  next,  previous,  up
+ @section AWK mode - What to put in your @file{.emacs} or @file{init.el}
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Much of the AWK mode initialization can, of course, be done by the
+ @ccmode{} general initialization procedure.  You may want to use certain
+ @ccmode{} features such as @code{auto-newline} and @code{clean-ups} in
+ the other modes, and you might thus have enabled them in a
+ @code{c-mode-common-hook} function, as described in @ref{Sample .emacs File}.
+ These features have not yet been amended for AWK mode, and far from
+ being useful, can be irritating in AWK mode or actually make AWK code
+ syntactically invalid.  Adding the following code to your
+ @file{.emacs} or @file{init.el} file will disable them for AWK mode.
+ 
+ @example
+ (defun my-awk-mode-hook ()
+   "Disable certain @ccmode{} features which could impair AWK mode."
+   (c-toggle-auto-state -1)       ; disable automatic insertions of newlines
+   (if (memq 'space-before-funcall c-cleanup-list)
+       (setq c-cleanup-list ; don't automatically insert a space into "foo("
+             (remove 'space-before-funcall c-cleanup-list))))
+ (add-hook 'awk-mode-hook 'my-awk-mode-hook)
+ @end example
+ 
+ Naturally you can add your own AWK-specific customizations to this
+ function.  @xref{Hooks}.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node AWK Mode Font Locking, AWK Mode Defuns, Initialising AWK Mode, AWK Mode
+ @comment  node-name,  next,  previous,  up
+ @section AWK Mode Font Locking
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ The general appearance of font-locking in AWK mode is much like in any
+ other programming mode.  @xref{Faces For Font Lock,,,elisp}.
+ 
+ The following faces are, however, used in a non-standard fashion in
+ AWK mode:
+ 
+ @table @asis
+ @item @code{font-lock-variable-name-face}
+ This face was intended for variable declarations.  Since variables are
+ not declared in AWK, this face is used instead for AWK system
+ variables (such as @code{NF}) and ``Special File Names'' (such as
+ @code{"/dev/stderr"}).
+ 
+ @item @code{font-lock-builtin-face} 
(Emacs)/@code{font-lock-preprocessor-face} (XEmacs)
+ This face is normally used for preprocessor directives in @ccmode{}.
+ There are no such things in AWK, so this face is used instead for
+ standard functions (such as @code{match}).
+ 
+ @item @code{font-lock-string-face}
+ As well as being used for strings, including localizable strings,
+ (delimited by @samp{"} and @samp{_"}), this face is also used for AWK
+ regular expressions (delimited by @samp{/}).
+ 
+ @item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs)
+ This face highlights the following syntactically invalid AWK
+ constructs:
+ 
+ @itemize @bullet
+ @item
+ An unterminated string or regular expression.  Here the opening
+ delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in
+ @code{font-lock-warning-face}.  This is most noticeable when typing in a
+ new string/regular expression into a buffer, when the warning-face
+ serves as a continual reminder to terminate the construct.
+ 
+ AWK mode fontifies unterminated strings/regular expressions
+ differently from other modes: Only the text up to the end of the line
+ is fontified as a string (escaped newlines being handled correctly),
+ rather than the text up to the next string quote.
+ 
+ @item
+ A space between the function name and opening parenthesis when calling
+ a user function.  The last character of the function name and the
+ opening parenthesis are highlighted.  This font-locking rule will
+ spuriously highlight a valid concatenation expression where an
+ identifier precedes a parenthesised expression.  Unfortunately.
+ 
+ @item
+ Whitespace following the @samp{\} in what otherwise looks like an
+ escaped newline.  The @samp{\} is highlighted.
+ @end itemize
+ @end table
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node AWK Mode Defuns,  , AWK Mode Font Locking, AWK Mode
+ @comment  node-name,  next,  previous,  up
+ @section AWK Mode Defuns
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ In AWK mode, @dfn{defun} means either a user-defined function or a
+ pattern-action pair.  Either the pattern or the action may be
+ implicit.
+ 
+ The beginning of a defun is recognised heuristically as, more or less,
+ code which begins in column zero.  Having the @address@hidden in column zero,
+ as is suggested for some modes, is neither necessary nor helpful in AWK
+ mode.
+ 
+ More precisely, the beginning of a defun is code which begins in
+ column zero, and which isn't a closing brace, a comment, or a
+ continuation of the previous line.  Code is the @dfn{continuation of
+ the previous line} when that line is syntactically incomplete, for
+ example when it ends with @address@hidden or an escaped newline.
+ 
+ The end of a defun is the @address@hidden which matches the @address@hidden 
(if
+ any) at the beginning of the action or function body, or the EOL or
+ @samp{;} which marks an implicit action.  Although this @address@hidden is
+ usually placed in column zero, AWK mode doesn't need it to be placed
+ there.
+ 
+ @table @asis
+ @item @kbd{C-M-a} @code{c-awk-beginning-of-defun}
+ @itemx @kbd{C-M-e} @code{c-awk-end-of-defun}
+ @findex c-awk-beginning-of-defun
+ @findex awk-beginning-of-defun (c-)
+ @findex c-awk-end-of-defun
+ @findex awk-end-of-defun (c-)
+ Move point back to the beginning or forward to the end of the current
+ AWK defun.  These functions can take prefix-arguments, their
+ functionality being entirely equivalent to @code{beginning-of-defun}
+ and @code{end-of-defun}.  @xref{Moving by Defuns,,,emacs}.
+ 
+ @item @kbd{C-M-h} @code{c-mark-function}
+ This works fine with AWK defuns.  @xref{Indentation Commands}.
+ @end table
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Odds and Ends, Performance Issues, AWK Mode, Top
+ @comment node-name, next, previous, up
+ @chapter Odds and Ends
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ The stuff that didn't fit in anywhere else is documented here.
+ 
+ @defopt c-require-final-newline
+ @vindex require-final-newline (c-)
+ Controls whether a final newline is ensured when the file is saved.  The
+ value is an association list that for each language mode specifies the
+ value to give to @code{require-final-newline} at mode initialization;
+ see that variable for details about the value.  If a language isn't
+ present on the association list, CC Mode won't touch
+ @code{require-final-newline} in buffers for that language.
+ 
+ The default is to set @code{require-final-newline} to @code{t} in the
+ languages that mandates that source files should end with newlines,
+ i.e., C, C++ and Objective-C.
+ @end defopt
+ 
+ @defopt c-echo-syntactic-information-p
+ @vindex echo-syntactic-information-p (c-)
+ If address@hidden, the syntactic analysis for the current line is shown
+ in the echo area when it's indented (unless
+ @code{c-syntactic-indentation} is @code{nil}).  That's useful when
+ finding out which syntactic symbols to modify to get the indentation you
+ want.
+ @end defopt
+ 
+ @defopt c-report-syntactic-errors
+ @vindex report-syntactic-errors (c-)
+ If address@hidden, certain syntactic errors are reported with a ding and
+ a message, for example when an @code{else} is indented for which there
+ is no corresponding @code{if}.
+ 
+ Note however that @ccmode{} doesn't make any special effort to check for
+ syntactic errors; that's the job of the compiler.  The reason it can
+ report cases like the one above is that it can't find the correct
+ anchoring position to indent the line in that case.
+ @end defopt
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Performance Issues, Limitations and Known Bugs, Odds and Ends, Top
+ @comment node-name, next, previous, up
+ @chapter Performance Issues
+ @cindex performance
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @comment FIXME: (ACM, 2003/5/24).  Check whether AWK needs mentioning here.
+ 
+ C and its derivative languages are highly complex creatures.  Often,
+ ambiguous code situations arise that require @ccmode{} to scan large
+ portions of the buffer to determine syntactic context.  Such
+ pathological code can cause @ccmode{} to perform fairly badly.  This
+ section gives some insight in how @ccmode{} operates, how that interacts
+ with some coding styles, and what you can use to improve performance.
+ 
+ The overall goal is that @ccmode{} shouldn't be overly slow (i.e., take
+ more than a fraction of a second) in any interactive operation.
+ i.e., it's tuned to limit the maximum response time in single operations,
+ which sometimes is at the expense of batch-like operations like
+ reindenting whole blocks.  If you find that @ccmode{} gradually gets
+ slower and slower in certain situations, perhaps as the file grows in
+ size or as the macro or comment you're editing gets bigger, then chances
+ are that something isn't working right.  You should consider reporting
+ it, unless it's something that's mentioned in this section.
+ 
+ Because @ccmode{} has to scan the buffer backwards from the current
+ insertion point, and because C's syntax is fairly difficult to parse in
+ the backwards direction, @ccmode{} often tries to find the nearest
+ position higher up in the buffer from which to begin a forward scan
+ (it's typically an opening or closing parethesis of some kind).  The
+ farther this position is from the current insertion point, the slower it
+ gets.
+ 
+ @findex beginning-of-defun
+ @findex defun-prompt-regexp
+ One of the simplest things you can do to reduce scan time, is make sure
+ any brace that opens a top-level address@hidden, a function in
+ C, or outermost class definition in C++ or Java.} always appears in the
+ leftmost column.  This is actually an Emacs constraint, as embodied in
+ the @code{beginning-of-defun} function which @ccmode{} uses heavily.  If
+ you hang top-level open braces on the right side of the line, then you
+ might want to set the variable @code{defun-prompt-regexp} to something
+ reasonable, however that ``something reasonable'' is difficult to
+ define, so @ccmode{} doesn't do it for you.
+ 
+ @vindex c-Java-defun-prompt-regexp
+ @vindex Java-defun-prompt-regexp (c-)
+ A special note about @code{defun-prompt-regexp} in Java mode: The common
+ style is to hang the opening braces of functions and classes on the
+ right side of the line, and that doesn't work well with the Emacs
+ approach.  @ccmode{} comes with a variable
+ @code{c-Java-defun-prompt-regexp} which tries to define a regular
+ expression usable for this style, but there are problems with it.  In
+ some cases it can cause @code{beginning-of-defun} to address@hidden
+ has been observed in Emacs 19.34 and XEmacs 19.15.}.  For this reason,
+ it is not used by default, but if you feel adventurous, you can set
+ @code{defun-prompt-regexp} to it in your mode hook.  In any event,
+ setting and relying on @code{defun-prompt-regexp} will definitely slow
+ things down because (X)Emacs will be doing regular expression searches a
+ lot, so you'll probably be taking a hit either way!
+ 
+ @ccmode{} maintains a cache of the opening parentheses of the blocks
+ surrounding the point, and it adapts that cache as the point is moved
+ around.  That means that in bad cases it can take noticeable time to
+ indent a line in a new surrounding, but after that it gets fast as long
+ as the point isn't moved far off.  The farther the point is moved, the
+ less useful is the cache.  Since editing typically is done in ``chunks''
+ rather than on single lines far apart from each other, the cache
+ typically gives good performance even when the code doesn't fit the
+ Emacs approach to finding the defun starts.
+ 
+ @vindex c-enable-xemacs-performance-kludge-p
+ @vindex enable-xemacs-performance-kludge-p (c-)
+ XEmacs users can set the variable
+ @code{c-enable-xemacs-performance-kludge-p} to address@hidden  This
+ tells @ccmode{} to use XEmacs-specific built-in functions which, in some
+ circumstances, can locate the top-most opening brace much more quickly than
+ @code{beginning-of-defun}.  Preliminary testing has shown that for
+ styles where these braces are hung (e.g., most JDK-derived Java styles),
+ this hack can improve performance of the core syntax parsing routines
+ from 3 to 60 times.  However, for styles which @emph{do} conform to
+ Emacs' recommended style of putting top-level braces in column zero,
+ this hack can degrade performance by about as much.  Thus this variable
+ is set to @code{nil} by default, since the Emacs-friendly styles should
+ be more common (and encouraged!).  Note that this variable has no effect
+ in Emacs since the necessary built-in functions don't exist (in Emacs
+ 21.3 as of this writing in May 2003).
+ 
+ Text properties are used to speed up skipping over syntactic whitespace,
+ i.e., comments and preprocessor directives.  Indenting a line after a
+ huge macro definition can be slow the first time, but after that the
+ text properties are in place and it should be fast (even after you've
+ edited other parts of the file and then moved back).
+ 
+ Font locking can be a CPU hog, especially the font locking done on
+ decoration level 3 which tries to be very accurate.  Note that that
+ level is designed to be used with a font lock support mode that only
+ fontifies the text that's actually shown, i.e., Lazy Lock or Just-in-time
+ Lock mode, so make sure you use one of them.  Fontification of a whole
+ buffer with some thousand lines can often take over a minute.  That is
+ a known weakness; the idea is that it never should happen.
+ 
+ The most effective way to speed up font locking is to reduce the
+ decoration level to 2 by setting @code{font-lock-maximum-decoration}
+ appropriately.  That level is designed to be as pretty as possible
+ without sacrificing performance.  @xref{Font Locking Preliminaries}, for
+ more info.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Limitations and Known Bugs, Frequently Asked Questions, Performance 
Issues, Top
+ @comment node-name, next, previous, up
+ @chapter Limitations and Known Bugs
+ @cindex limitations
+ @cindex bugs
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @itemize @bullet
+ @item
+ There is no way to apply auto newline settings (@pxref{Auto-newline
+ Insertion}) on already typed lines.  That's only a feature to ease
+ interactive editing.
+ 
+ To generalize this issue a bit: @ccmode{} is not intended to be used as
+ a reformatter for old code in some more or less batch-like way.  With
+ the exception of some functions like @code{c-indent-region}, it's only
+ geared to be used interactively to edit new code.  There's currently no
+ intention to change this goal.
+ 
+ If you want to reformat old code, you're probably better off using some
+ other tool instead, e.g., @ref{Top, , GNU indent, indent, The `indent'
+ Manual}, which has more powerful reformatting capabilities than
+ @ccmode{}.
+ 
+ @item
+ @vindex signal-error-on-buffer-boundary
+ XEmacs has a variable called @code{signal-error-on-buffer-boundary}.
+ It's used as a solution to user interface problems associated with
+ buffer movement and the @code{zmacs-region} deactivation on errors.
+ However, setting this variable to a non-default value in XEmacs 19 and
+ 20 had the deleterious side effect of breaking many built-in primitive
+ functions.  @strong{Do not set this variable to @code{nil} in XEmacs
+ 19 and 20}; you will cause serious problems in @ccmode{} and probably
+ other XEmacs packages!  In XEmacs 21 the effects of the variable is
+ limited to some functions that are only used interactively, so it's
+ not a problem there.
+ @end itemize
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Frequently Asked Questions, Getting the Latest CC Mode Release, 
Limitations and Known Bugs, Top
+ @comment node-name, next, previous, up
+ @appendix Frequently Asked Questions
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @itemize @bullet
+ @item
+ @kindex C-x h
+ @kindex C-M-\
+ @emph{How do I reindent the whole file?}
+ 
+ Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit
+ @kbd{C-M-\}.
+ 
+ @item
+ @kindex C-M-q
+ @kindex C-M-u
+ @emph{How do I reindent the current block?}
+ 
+ First move to the brace which opens the block with @kbd{C-M-u}, then
+ reindent that expression with @kbd{C-M-q}.
+ 
+ @item
+ @kindex RET
+ @kindex C-j
+ @emph{Why doesn't the @kbd{RET} key indent the new line?}
+ 
+ Emacs' convention is that @kbd{RET} just adds a newline, and that
+ @kbd{C-j} adds a newline and indents it.  You can make @kbd{RET} do this
+ too by adding this to your @code{c-mode-common-hook}:
+ 
+ @example
+ (define-key c-mode-base-map "\C-m" 'c-context-line-break)
+ @end example
+ 
+ This is a very common question.  If you want this to be the default
+ behavior, don't lobby me, lobby RMS!  @t{:-)}
+ 
+ @item
+ @emph{I put @code{(c-set-offset 'substatement-open 0)} in my
+ @file{.emacs} file but I get an error saying that @code{c-set-offset}'s
+ function definition is void.  What's wrong?}
+ 
+ This means that @ccmode{} wasn't loaded into your Emacs session by the
+ time the @code{c-set-offset} call was reached, most likely because
+ @ccmode{} is being autoloaded.  Instead of putting the
+ @code{c-set-offset} line in your top-level @file{.emacs} file, put it in
+ your @code{c-mode-common-hook}, or simply modify @code{c-offsets-alist}
+ directly:
+ 
+ @example
+ (setq c-offsets-alist '((substatement-open . 0)))
+ @end example
+ 
+ @item
+ @kindex M-a
+ @kindex M-e
+ @address@hidden and @kbd{M-e} used to move over entire balanced brace
+ lists, but now they move into blocks.  How do I get the old behavior
+ back?}
+ 
+ Use @kbd{C-M-f} and @kbd{C-M-b} to move over balanced brace blocks.  Use
+ @kbd{M-a} and @kbd{M-e} to move by statements, which will also move into
+ blocks.
+ 
+ @item
+ @emph{Whenever I try to indent a line or type an ``electric'' key such
+ as @kbd{;}, @address@hidden, or @address@hidden, I get an error that look 
like this:
+ @code{Invalid function: (macro . #[...}. What gives?}
+ 
+ This is a common error when @ccmode{} hasn't been compiled correctly,
+ especially under Emacs address@hidden, it's because some
+ macro wasn't defined during the compilation, so the byte compiler put
+ in function calls instead of the macro expansions. Later, when the
+ interpreter tries to call the macro as a function, it shows this
+ (somewhat cryptic) error message.}. If you are using the standalone
+ @ccmode{} distribution, try recompiling it according to the instructions
+ in the @file{README} file.
+ 
+ @item
+ @cindex open paren in column zero
+ @emph{I have an open paren character at column zero inside a comment or
+ multiline string literal, and it causes the fontification and/or
+ indentation to go haywire.  What gives?}
+ 
+ It's due to the ad-hoc rule in (X)Emacs that such open parens always
+ start defuns (which translates to functions, classes, namespaces or any
+ other top-level block constructs in the @ccmode{} languages).
+ @xref{Left Margin Paren,,, emacs, The Emacs Editor}, for details
+ (@xref{Defuns,,, emacs, The Emacs Editor}, in the Emacs 20 manual).
+ 
+ This heuristic is built into the core syntax analysis routines in
+ (X)Emacs, so it's not really a @ccmode{} issue.  However, in Emacs 21.4
+ it has become possible to turn it address@hidden the variable
+ @code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so
+ there since it got its own system to keep track of blocks.
+ 
+ @end itemize
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Getting the Latest CC Mode Release, Mailing Lists and Submitting Bug 
Reports, Frequently Asked Questions, Top
+ @comment node-name, next, previous, up
+ @appendix Getting the Latest CC Mode Release
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @ccmode{} has been standard with all versions of Emacs since 19.34 and
+ of XEmacs since 19.16.
+ 
+ @cindex web site
+ Due to release schedule skew, it is likely that all of these Emacsen
+ have old versions of @ccmode{} and so should be upgraded.  Access to the
+ @ccmode{} source code, as well as more detailed information on Emacsen
+ compatibility, etc. are all available on the web site:
+ 
+ @quotation
+ @uref{http://cc-mode.sourceforge.net/}
+ @end quotation
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Mailing Lists and Submitting Bug Reports, Sample .emacs File, 
Getting the Latest CC Mode Release, Top
+ @comment node-name, next, previous, up
+ @appendix Mailing Lists and Submitting Bug Reports
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @kindex C-c C-b
+ @findex c-submit-bug-report
+ @findex submit-bug-report (c-)
+ To report bugs, use the @kbd{C-c C-b} (bound to
+ @code{c-submit-bug-report}) command.  This provides vital information
+ we need to reproduce your problem.  Make sure you include a concise,
+ but complete code example.  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, if
+ you think it might affect our ability to reproduce it.
+ 
+ Please try to produce the problem in an Emacs instance without any
+ customizations loaded (i.e., start it with the @samp{-q --no-site-file}
+ arguments).  If it works correctly there, the problem might be caused by
+ faulty customizations in either your own or your site configuration.  In
+ that case, we'd appreciate if you isolate the Emacs Lisp code that trigs
+ the bug and include it in your report.
+ 
+ @cindex bug report mailing list
+ Bug reports are sent to @email{bug-cc-mode@@gnu.org}.  You can also send
+ other questions and suggestions (kudos? @t{;-)} to that address.  It's a
+ mailing list which you can join or browse an archive of; see the web
+ site at @uref{http://cc-mode.sourceforge.net/} for further details.
+ 
+ @cindex announcement mailing list
+ If you want to get announcements of new @ccmode{} releases, send the
+ word @emph{subscribe} in the body of a message to
+ @email{cc-mode-announce-request@@lists.sourceforge.net}.  It's possible
+ to subscribe from the web site too.  Announcements will also be posted
+ to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs} and
+ @code{comp.emacs.xemacs}.
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Sample .emacs File, Command and Function Index, Mailing Lists and 
Submitting Bug Reports, Top
+ @comment node-name, next, previous, up
+ @appendix Sample .emacs file
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @example
+ ;; Here's a sample .emacs file that might help you along the way.
+ ;; Just copy this region and paste it into your .emacs file.  You may
+ ;; want to change some of the actual values.
+ 
+ (defconst my-c-style
+   '((c-tab-always-indent        . t)
+     (c-comment-only-line-offset . 4)
+     (c-hanging-braces-alist     . ((substatement-open after)
+                                    (brace-list-open)))
+     (c-hanging-colons-alist     . ((member-init-intro before)
+                                    (inher-intro)
+                                    (case-label after)
+                                    (label after)
+                                    (access-label after)))
+     (c-cleanup-list             . (scope-operator
+                                    empty-defun-braces
+                                    defun-close-semi))
+     (c-offsets-alist            . ((arglist-close . c-lineup-arglist)
+                                    (substatement-open . 0)
+                                    (case-label        . 4)
+                                    (block-open        . 0)
+                                    (knr-argdecl-intro . -)))
+     (c-echo-syntactic-information-p . t))
+   "My C Programming Style")
+ 
+ ;; offset customizations not in my-c-style
+ (setq c-offsets-alist '((member-init-intro . ++)))
+ 
+ ;; Customizations for all modes in CC Mode.
+ (defun my-c-mode-common-hook ()
+   ;; add my personal style and set it for the current buffer
+   (c-add-style "PERSONAL" my-c-style t)
+   ;; other customizations
+   (setq tab-width 8
+         ;; this will make sure spaces are used instead of tabs
+         indent-tabs-mode nil)
+   ;; we like auto-newline and hungry-delete
+   (c-toggle-auto-hungry-state 1)
+   ;; key bindings for all supported languages.  We can put these in
+   ;; c-mode-base-map because c-mode-map, c++-mode-map, objc-mode-map,
+   ;; java-mode-map, idl-mode-map, and pike-mode-map inherit from it.
+   (define-key c-mode-base-map "\C-m" 'c-context-line-break))
+ 
+ (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+ @end example
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Command and Function Index, Variable Index, Sample .emacs File, Top
+ @comment node-name, next, previous, up
+ @unnumbered Command and Function Index
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Since most @ccmode{} commands are prepended with the string
+ @samp{c-}, each appears under its @address@hidden name and its
+ @address@hidden (c-)} name.
+ @iftex
+ @sp 2
+ @end iftex
+ @printindex fn
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Variable Index, Concept Index, Command and Function Index, Top
+ @comment node-name, next, previous, up
+ @unnumbered Variable Index
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ Since most @ccmode{} variables are prepended with the string
+ @samp{c-}, each appears under its @address@hidden name and its
+ @address@hidden (c-)} name.
+ @iftex
+ @sp 2
+ @end iftex
+ @printindex vr
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @node    Concept Index, , Variable Index, Top
+ @comment node-name, next, previous, up
+ @unnumbered Concept Index
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @printindex cp
+ 
+ 
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ @comment Epilogue.
+ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ 
+ @iftex
+ @page
+ @summarycontents
+ @contents
+ @end iftex
+ 
+ @bye
+ 
+ @ignore
+    arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0
+ @end ignore




reply via email to

[Prev in Thread] Current Thread [Next in Thread]