\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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment How to make the various output formats:
+@comment (Thanks to Robert Chassell for supplying this information.)
+@comment Note that Texinfo 4.7 (or later) is needed.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@ignore
+In each of the following pairs of commands, the first generates a
+version with cross references pointing to the GNU Emacs manuals,
+the second with them pointing to the XEmacs manuals.
+ ## Info output
+ makeinfo cc-mode.texi
+ makeinfo -DXEMACS cc-mode.texi
+
+ ## DVI output
+ ## You may need to set up the environment variable TEXINPUTS so
+ ## that tex can find the file texinfo.tex - See the tex
+ ## manpage.
+ texi2dvi cc-mode.texi
+ texi2dvi -t "@set XEMACS " cc-mode.texi
+
+ ## HTML output. (The --no-split parameter is optional)
+ makeinfo --html --no-split cc-mode.texi
+ makeinfo --html --no-split -DXEMACS cc-mode.texi
+
+ ## Plain text output
+ makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
+ --no-headers --output=cc-mode.txt cc-mode.texi
+ makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
+ --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi
+
+ ## DocBook output
+ makeinfo --docbook --no-split --paragraph-indent=0 \
+ cc-mode.texi
+ makeinfo --docbook --no-split --paragraph-indent=0 \
+ -DXEMACS cc-mode.texi
+
+ ## XML output
+ makeinfo --xml --no-split --paragraph-indent=0 \
+ cc-mode.texi
+ makeinfo --xml --no-split --paragraph-indent=0 \
+ -DXEMACS cc-mode.texi
+
+ #### (You must be in the same directory as the viewed file.)
+
+ ## View DVI output
+ xdvi cc-mode.dvi &
+
+ ## View HTML output
+ mozilla cc-mode.html
+@end ignore
+
@comment No overfull hbox marks in the dvi file.
@finalout
@settitle CC Mode Manual
@footnotestyle end
+@c The following four macros generate the filenames and titles of the
+@c main (X)Emacs manual and the Elisp/Lispref manual. Leave the
+@c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it
+@c to generate an XEmacs version, e.g. with
+@c "makeinfo -DXEMACS cc-mode.texi".
+@ifset XEMACS
+@macro emacsman
+xemacs
+@end macro
+@macro emacsmantitle
+XEmacs User's Manual
+@end macro
+@macro lispref
+lispref
+@end macro
+@macro lispreftitle
+XEmacs Lisp Reference Manual
+@end macro
+@end ifset
+
+@ifclear XEMACS
+@macro emacsman
+emacs
+@end macro
+@macro emacsmantitle
+GNU Emacs Manual
+@end macro
+@macro lispref
+elisp
+@end macro
+@macro lispreftitle
+GNU Emacs Lisp Reference Manual
+@end macro
+@end ifclear
+
+
+@macro ccmode
+CC Mode
+@end macro
+
@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 <krishna@earth-gw.njit.edu>
@comment Authors:
@comment Barry A. Warsaw
@comment Martin Stjernholm
+@comment Alan Mackenzie
+@comment
+@comment Maintained by Martin Stjernholm and Alan Mackenzie <bug-cc-mode@gnu.org>
@comment
-@comment Maintained by Martin Stjernholm <bug-cc-mode@gnu.org>
-@comment
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@macro copyrightblurb
-Copyright @copyright{} 1995, 96, 97, 98, 99, 2000, 01 Free Software Foundation, Inc.
-@end macro
+@comment Define an index for syntactic symbols.
+@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss
+ @c For Info, unlike tex, @syncodeindex needs a matching @defindex.
+@defindex ss
+@end ifnottex
-@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, and IDL code.
-@end direntry
+@comment Combine key, syntactic symbol and concept indices into one.
+@syncodeindex ss cp
+@syncodeindex ky cp
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@comment The following lines inserts the copyright notice
-@comment into the Info file.
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@copying
+This manual is for CC Mode in Emacs.
-@ifnottex
-Copyright @copyright{} 1995, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+2003, 2004, 2005, 2006 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
+under the terms of the GNU Free Documentation License, Version 1.2 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
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 ifnottex
+@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
@titlepage
@sp 10
-@center @titlefont{CC Mode 5.28}
+@center @titlefont{CC Mode 5.31}
@sp 2
@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
@sp 2
-@center Barry A. Warsaw, Martin Stjernholm
+@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1995, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
-@sp 1
-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.''
+@insertcopying
-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.
+This manual was generated from $Revision: 1.36 $ of $RCSfile: cc-mode.texi,v $, which can be
+downloaded from
+@url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/man/cc-mode.texi}.
@end titlepage
@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 Pike code. It provides syntax-based
-indentation and has several handy commands and some minor modes to make
-the editing easier. Note that @ccmode{} does @emph{not} provide
-font-locking; there are other Emacs packages for that.
+Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
+and AWK code. 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::
-* New Indentation Engine::
-* Minor Modes::
-* Text Filling and Line Breaking::
-* Commands::
-* Customizing Indentation::
-* Syntactic Symbols::
-* Indentation Functions::
-* 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 ---
-
-* Concept Index::
-* Command Index::
-* Key Index::
-* Variable Index::
-
+* Introduction::
+* Overview::
+* Getting Started::
+* Commands::
+* Font Locking::
+* Config Basics::
+* Custom Filling and Breaking::
+* Custom Auto-newlines::
+* Clean-ups::
+* Indentation Engine Basics::
+* Customizing Indentation::
+* Custom Macros::
+* Odds and Ends::
+* Sample .emacs File::
+* Performance Issues::
+* Limitations and Known Bugs::
+* FAQ::
+* Updating CC Mode::
+* Mailing Lists and Bug Reports::
+* Command and Function Index::
+* Variable Index::
+* Concept and Key Index::
+
+@detailmenu
--- The Detailed Node Listing ---
-New Indentation Engine
+Commands
-* Syntactic Analysis::
-* Indentation Calculation::
+* Indentation Commands::
+* Comment Commands::
+* Movement Commands::
+* Filling and Breaking::
+* Minor Modes::
+* Electric Keys::
+* Auto-newlines::
+* Hungry WS Deletion::
+* Subword Movement::
+* Other Commands::
-Minor Modes
+Font Locking
-* Auto-newline Insertion::
-* Hungry-deletion of Whitespace::
+* Font Locking Preliminaries::
+* Faces::
+* Doc Comments::
+* AWK Mode Font Locking::
-Auto-newline Insertion
+Configuration Basics
-* Hanging Braces::
-* Hanging Colons::
-* Hanging Semi-colons and Commas::
-* Other Electric Commands::
-* Clean-ups::
+* CC Hooks::
+* Style Variables::
+* Styles::
-Commands
+Styles
-* Indentation Commands::
-* Movement Commands::
-* Other Commands::
+* Built-in Styles::
+* Choosing a Style::
+* Adding Styles::
+* File Styles::
-Customizing Indentation
+Customizing Auto-newlines
-* Interactive Customization::
-* Permanent Customization::
-* Hooks::
-* Styles::
-* Advanced Customizations::
+* Hanging Braces::
+* Hanging Colons::
+* Hanging Semicolons and Commas::
-Styles
+Hanging Braces
-* Built-in Styles::
-* Adding Styles::
-* File Styles::
+* Custom Braces::
-Advanced Customizations
+Indentation Engine Basics
-* Custom Indentation Functions::
-* Custom Brace and Colon Hanging::
-* Customizing Semi-colons and Commas::
-* Other Special Indentations::
-@end menu
+* Syntactic Analysis::
+* Syntactic Symbols::
+* Indentation Calculation::
+
+Syntactic Symbols
+
+* Function Symbols::
+* Class Symbols::
+* Conditional Construct Symbols::
+* Switch Statement Symbols::
+* Brace List Symbols::
+* External Scope Symbols::
+* Paren List Symbols::
+* Literal Symbols::
+* Multiline Macro Symbols::
+* Objective-C Method Symbols::
+* Anonymous Class Symbol::
+* Statement Block Symbols::
+* K&R Symbols::
+
+Customizing Indentation
+
+* c-offsets-alist::
+* Interactive Customization::
+* Line-Up Functions::
+* Custom Line-Up::
+* Other Indentation::
+
+Line-Up Functions
+
+* Brace/Paren Line-Up::
+* List Line-Up::
+* Operator Line-Up::
+* Comment Line-Up::
+* Misc Line-Up::
+@end detailmenu
+@end menu
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Introduction, Getting Connected, Top, Top
+@node Introduction, Overview, Top, Top
@comment node-name, next, previous, up
-@chapter Introduction
+@chapter Introduction
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@cindex BOCM
+@cindex history
+@cindex awk-mode.el
+@cindex c-mode.el
+@cindex c++-mode.el
Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
-C++, Objective-C, Java, CORBA IDL, and Pike code. This incarnation of
-the mode is descendant 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. @ccmode{} represents a significant
-milestone in the mode's life. It has been fully merged back with Emacs
-19's @file{c-mode.el}. Also a new, more intuitive and flexible mechanism
-for controlling indentation has been developed. 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.
+C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
+CIDL), Pike and AWK code. This incarnation of the mode is descended
+from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM
+@t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been
+maintaining since 1992, and @file{awk-mode.el}, a long neglected mode
+in the (X)Emacs base.
+
+Late in 1997, Martin Stjernholm joined Barry on the @ccmode{}
+Maintainers Team, and implemented the Pike support. In 2000 Martin
+took over as the sole maintainer. In 2001 Alan Mackenzie joined the
+team, implementing AWK support in version 5.30. @ccmode{} did not
+originally contain the font lock support for its languages --- that
+was added in version 5.30.
This manual describes @ccmode{}
-@comment The following line must appear on its own, so that the automated
-version 5.28.
+@comment The following line must appear on its own, so that the
+version 5.31.
@comment Release.py script can update the version number automatically
-@ccmode{} supports the editing of K&R and ANSI C, @dfn{ARM}
-@footnote{@cite{The Annotated C++ Reference Manual}, by Ellis and
-Stroustrup.} C++, Objective-C, Java, CORBA's Interface Definition
-Language, and Pike@footnote{A C-like scripting language with its roots
-in the LPC language used in some MUD engines. See
-@uref{http://pike.idonex.se/}.} files. In this way, you can easily set
-up consistent coding styles for use in editing all of these languages.
-@ccmode{} does @emph{not} handle font-locking (a.k.a. syntax coloring,
-keyword highlighting) or anything of that nature, for any of these
-modes. Font-locking is handled by other Emacs packages.
-
-This manual will describe the following:
-
-@itemize @bullet
-@item
-How to get started using @ccmode{}.
-
-@item
-How the new indentation engine works.
-
-@item
-How to customize the new indentation engine.
-
-@end itemize
+@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
+Java, CORBA's Interface Definition Language, Pike@footnote{A 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 java-mode
@findex idl-mode
@findex pike-mode
-Note that the name of this package is ``@ccmode{},'' but there is no top
+@findex awk-mode
+Note that the name of this package is ``@ccmode{}'', but there is no top
level @code{cc-mode} entry point. All of the variables, commands, and
-functions in @ccmode{} are prefixed with @code{c-@var{<thing>}}, and
+functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and
@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
-@code{idl-mode}, and @code{pike-mode} entry points are provided. This
-package is intended to be a replacement for @file{c-mode.el} and
-@file{c++-mode.el}.
-
-@cindex @file{cc-compat.el} file
-This distribution also contains a file
-called @file{cc-compat.el} which should ease your transition from BOCM
-to @ccmode{}. If you have a BOCM configuration you are really happy
-with, and want to postpone learning how to configure @ccmode{}, take a
-look at that file. It maps BOCM configuration variables to @ccmode{}'s
-new indentation model. It is not actively supported so for the long
-run, you should learn how to customize @ccmode{} to support your coding
-style.
+@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}.
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.
-
+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, New Indentation Engine, Introduction, Top
-@comment node-name, next, previous, up
-@chapter Getting Connected
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Overview, Getting Started, Introduction, Top
+@comment node-name, next, previous, up@cindex organization of the manual
+@chapter Overview of the Manual
+@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.
+@noindent
+The manual starts with several introductory chapters (including this
+one).
-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
-Web pages for the latest information on Emacs version and package
-compatibility (@pxref{Getting the Latest CC Mode Release}).
+@noindent
+The next chunk of the manual describes the day to day @emph{use} of
+@ccmode{} (as contrasted with how to customize it).
-@cindex @file{cc-mode-18.el} file
-@emph{Note that @ccmode{} no longer
-works with Emacs 18!}, so if you haven't upgraded from Emacs 18 by now,
-you are out of luck.
+@itemize @bullet
+@item
+The chapter ``Commands'' describes in detail how to use (nearly) all
+of @ccmode{}'s features. There are extensive cross-references from
+here to the corresponding sections later in the manual which tell you
+how to customize these features.
-@findex 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
+@item
+``Font Locking'' describes how ``syntax highlighting'' is applied to
+your buffers. It is mainly background information and can be skipped
+over at a first reading.
+@end itemize
-Using CC Mode version 5.XX
+@noindent
+The next chunk of the manual describes how to @emph{customize}
+@ccmode{}. Typically, an overview of a topic is given at the chapter
+level, then the sections and subsections describe the material in
+increasing detail.
-@end example
+@itemize @bullet
+@item
+The chapter ``Configuration Basics'' tells you @emph{how} to write
+customizations - whether in hooks, in styles, in both, or in neither,
+depending on your needs. It describes the @ccmode{} style system and
+lists the standard styles that @ccmode{} supplies.
-@noindent
-where @samp{XX} is the minor release number.
+@item
+The next few chapters describe in detail how to customize the various
+features of @ccmode{}.
+@item
+Finally, there is a sample @file{.emacs} fragment, which might help you
+in creating your own customization.
+@end itemize
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node New Indentation Engine, Minor Modes, Getting Connected, Top
-@comment node-name, next, previous, up
-@chapter New Indentation Engine
-@cindex indentation engine
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@noindent
+The manual ends with ``this and that'', things that don't fit cleanly
+into any of the previous chunks.
-@ccmode{} has a new indentation engine, providing a simplified, yet
-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.
+@itemize @bullet
+@item
+Two chapters discuss the performance of @ccmode{} and known
+bugs/limitations.
-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.
+@item
+The FAQ contains a list of common problems and questions.
-@menu
-* Syntactic Analysis::
-* Indentation Calculation::
-@end menu
+@item
+The next two chapters tell you how to get in touch with the @ccmode{}
+project - whether for updating @ccmode{} or submitting bug reports.
+@end itemize
+@noindent
+Finally, there are the customary indices.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Syntactic Analysis, Indentation Calculation, , New Indentation Engine
+@node Getting Started, Commands, Overview, Top
@comment node-name, next, previous, up
-@section Syntactic Analysis
-@cindex syntactic analysis
+@chapter Getting Started
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@cindex relative buffer position
-@cindex syntactic symbol
-@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
-information (in lisp parlance, a @emph{cons cell}), where the first part
-is a @dfn{syntactic symbol}, and the second part is a @dfn{relative
-buffer position}. Syntactic symbols describe elements of C code
-@footnote{Unless otherwise noted, the term ``C code'' to 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.
+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 might not
+have the latest @ccmode{} release and might want to upgrade your copy
+(see below).
-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
-@group
+You should probably start by reading the entire chapter
+@ref{Commands} to get an overview of @ccmode{}'s capabilities.
- 1: void swap( int& a, int& b )
- 2: @{
- 3: int tmp = a;
- 4: a = b;
- 5: b = tmp;
- 6: @}
+After trying out some commands, you may dislike some aspects of
+@ccmode{}'s default configuration. Here is an outline of how to
+change some of the settings that newcomers to @ccmode{} most often
+want to change:
-@end group
-@end example
+@table @asis
+@item c-basic-offset
+This Lisp variable holds an integer, the number of columns @ccmode{}
+indents nested code. To set this value to 6, customize
+@code{c-basic-offset} or put this into your @file{.emacs}:
-@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}
-(@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 area@footnote{With a universal
-argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the
-buffer as a comment
-on the current line.}:
@example
-
-((statement . 35))
-
+(setq c-basic-offset 6)
@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))
+@item The (indentation) style
+The basic ``shape'' of indentation created by @ccmode{}---by default,
+this is @code{gnu} style (except for Java and AWK buffers). A list of
+the availables styles and their descriptions can be found in
+@ref{Built-in Styles}. A complete specification of the @ccmode{}
+style system, including how to create your own style, can be found in
+the chapter @ref{Styles}. To set your style to @code{linux}, either
+customize @code{c-default-style} or put this into your @file{.emacs}:
+@example
+(setq c-default-style '((java-mode . "java")
+ (awk-mode . "awk")
+ (other . "linux")))
@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
-@group
-
- 1: int add( int val, int incr, int doit )
- 2: @{
- 3: if( doit )
- 4: @{
- 5: return( val + incr );
- 6: @}
- 7: return( val );
- 8: @}
+@item Electric Indentation
+Normally, when you type ``punctuation'' characters such as @samp{;} or
+@samp{@{}, @ccmode{} instantly reindents the current line. This can
+be disconcerting until you get used to it. To disable @dfn{electric
+indentation} in the current buffer, type @kbd{C-c C-l}. Type the same
+thing to enable it again. To have electric indentation disabled by
+default, put the following into your @file{.emacs} file@footnote{There
+is no ``easy customization'' facility for making this change.}:
-@end group
-@end example
-
-@noindent
-Hitting @kbd{C-c C-s} on line 4 gives us:
@example
-
-((substatement-open . 46))
-
+(setq-default c-electric-flag nil)
@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
-@group
+Details of of this and other similar ``Minor Modes'' appear in the
+section @ref{Minor Modes}.
- 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: @}
+@item Making the @key{RET} key indent the new line
+The standard Emacs binding for @key{RET} just adds a new line. If you
+want it to reindent the new line as well, rebind the key. Note that
+the action of rebinding will fail if the pertinent keymap doesn't yet
+exist---we thus need to delay the action until after @ccmode{} has
+been loaded. Put the following code into your @file{.emacs}:
-@end group
+@example
+(defun my-make-CR-do-indent ()
+ (define-key c-mode-base-map "\C-m" 'c-context-line-break))
+(add-hook 'c-initialization-hook 'my-make-CR-do-indent)
@end example
@noindent
-Hitting @kbd{C-c C-s} on line 3 of this example gives:
-@example
+This example demonstrates the use of a very powerful @ccmode{} (and
+Emacs) facility, the hook. The use of @ccmode{}'s hooks is described
+in @ref{CC Hooks}.
+@end table
-((comment-intro) (defun-block-intro . 46))
+All these settings should occur in your @file{.emacs} @emph{before}
+any @ccmode{} buffers get loaded---in particular, before any call of
+@code{desktop-read}.
+
+As you get to know the mode better, you may want to make more
+ambitious changes to your configuration. For this, you should start
+reading the chapter @ref{Config Basics}.
+
+If you are upgrading an existing @ccmode{} installation, please see
+the @file{README} file for installation details. In particular, if
+you are going to be editing AWK files, @file{README} describes how to
+configure your (X)Emacs so that @ccmode{} will supersede the obsolete
+@code{awk-mode.el} which might have been supplied with your (X)Emacs.
+@ccmode{} might 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{Updating CC Mode}).
+
+@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
-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.
-
+where @samp{XX} is the minor release number.
+@end deffn
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Indentation Calculation, , Syntactic Analysis, New Indentation Engine
+@node Commands, Font Locking, Getting Started, Top
@comment node-name, next, previous, up
-@section Indentation Calculation
-@cindex indentation calculation
+@chapter Commands
@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.
+This chapter specifies all of CC Mode's commands, and thus contains
+nearly everything you need to know to @emph{use} @ccmode{} (as
+contrasted with configuring it). @dfn{Commands} here means both
+control key sequences and @dfn{electric keys}, these being characters
+such as @samp{;} which, as well as inserting themselves into the
+buffer, also do other things.
-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.
+You might well want to review
+@ifset XEMACS
+@ref{Lists,,,@emacsman{}, @emacsmantitle{}},
+@end ifset
+@ifclear XEMACS
+@ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}},
+@end ifclear
+which describes commands for moving around brace and parenthesis
+structures.
-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
-@group
+@menu
+* Indentation Commands::
+* Comment Commands::
+* Movement Commands::
+* Filling and Breaking::
+* Minor Modes::
+* Electric Keys::
+* Auto-newlines::
+* Hungry WS Deletion::
+* Subword Movement::
+* Other Commands::
+@end menu
- 1: void swap( int& a, int& b )
- 2: @{
- 3: int tmp = a;
- 4: a = b;
- 5: b = tmp;
- 6: @}
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Indentation Commands, Comment Commands, Commands, Commands
+@comment node-name, next, previous,up
+@section Indentation Commands
+@cindex indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@end group
-@end example
+The following 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.
-Let's say point is on line 3 and we hit the @kbd{TAB} key to re-indent
-the line. Remember that the syntactic component list for that
-line is:
-@example
+@cindex GNU indent program
+Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
+(@pxref{Custom Auto-newlines}) 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, amongst other things.
+
+Preprocessor directives are handled as syntactic whitespace from other
+code, i.e. they can be interspersed anywhere without affecting the
+indentation of the surrounding code, just like comments.
+
+The code inside macro definitions is, by default, 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.
+
+Reindenting large sections of code can take a long time. When
+@ccmode{} reindents a region of code, it is essentially equivalent to
+hitting @key{TAB} on every line of the region.
-((defun-block-intro . 29))
+These commands indent code:
-@end example
+@table @asis
+@item @kbd{@key{TAB}} (@code{c-indent-command})
+@kindex TAB
+@findex c-indent-command
+@findex indent-command (c-)
+This command indents the current line. That is all you need to know
+about it for normal use.
-@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.
+@code{c-indent-command} does different things, depending on the
+settting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
+Basics}):
-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.
+@itemize @bullet
+@item
+When it's non-@code{nil} (which it normally is), the command indents
+the line according to its syntactic context. With a prefix argument
+(@kbd{C-u @key{TAB}}), it will re-indent the entire
+expression@footnote{this is only useful for a line starting with a
+comment opener or an opening brace, parenthesis, or string quote.}
+that begins at the line's left margin.
-Here's another example:
-@example
-@group
+@item
+When it's @code{nil}, the command indents the line by an extra
+@code{c-basic-offset} columns. A prefix argument acts as a
+multiplier. A bare prefix (@kbd{C-u @key{TAB}} is equivalent to -1,
+removing @code{c-basic-offset} columns from the indentation.
+@end itemize
- 1: int add( int val, int incr, int doit )
- 2: @{
- 3: if( doit )
- 4: @{
- 5: return( val + incr );
- 6: @}
- 7: return( val );
- 8: @}
+The precise behavior is modified by several variables: With
+@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace
+in some circumstances---@code{c-insert-tab-function} then defines
+precisely what sort of ``whitespace'' this will be. Set the standard
+Emacs variable @code{indent-tabs-mode} to @code{t} if you want real
+@samp{tab} characters to be used in the indentation, to @code{nil} if
+you want only spaces. @xref{Just Spaces,,, @emacsman{},
+@emacsmantitle{}}.
-@end group
-@end example
+@defopt c-tab-always-indent
+@vindex tab-always-indent (c-)
+@cindex literal
+This variable modifies how @key{TAB} operates.
+@itemize @bullet
+@item
+When it is @code{t} (the default), @key{TAB} simply indents the
+current line.
+@item
+When it is @code{nil}, @key{TAB} (re)indents the line only if point is
+to the left of the first non-whitespace character on the line.
+Otherwise it inserts some whitespace (a tab or an equivalent number of
+spaces - see below) at point.
+@item
+With some other value, the line is reindented. Additionally, if point
+is within a string or comment, some whitespace is inserted.
+@end itemize
+@end defopt
-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
+@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 is @code{insert-tab}, which 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
+@end table
-((substatement-open . 46))
+@noindent
+The kind of indentation the next five commands do depends on the
+setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
+Basics}):
+@itemize @bullet
+@item
+when it is non-@code{nil} (the default), the commands indent lines
+according to their syntactic context;
+@item
+when it is @code{nil}, they just indent each line the same amount as
+the previous non-blank line. The commands that indent a region aren't
+very useful in this case.
+@end itemize
-@end example
+@table @asis
+@item @kbd{C-j} (@code{newline-and-indent})
+@kindex C-j
+@findex newline-and-indent
+Inserts a newline and indents the new blank line, ready to start
+typing. This is a standard (X)Emacs command.
-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.
+@item @kbd{C-M-q} (@code{c-indent-exp})
+@kindex C-M-q
+@findex c-indent-exp
+@findex indent-exp (c-)
+Indents 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.
-Simple, huh?
+@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.
-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.
+@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
-@vindex c-echo-syntactic-information-p
-@vindex echo-syntactic-information-p (c-)
-As you configure @ccmode{}, you might want to set the variable
-@code{c-echo-syntactic-information-p} to non-@code{nil} so that the
-syntactic component list and calculated offset will always be echoed in
-the minibuffer when you hit @kbd{TAB}.
+These variables are also useful when indenting code:
+@defopt indent-tabs-mode
+This is a standard Emacs variable that controls how line indentation
+is composed. When it's non-@code{nil}, tabs can be used in a line's
+indentation, otherwise only spaces are 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 Minor Modes, Text Filling and Line Breaking, New Indentation Engine, Top
+@node Comment Commands, Movement Commands, Indentation Commands, Commands
@comment node-name, next, previous, up
-@chapter Minor Modes
+@section Comment Commands
+@cindex comments (insertion of)
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@ccmode{} contains two minor-mode-like features that you should
-find useful while you enter new C code. The first is called
-@dfn{auto-newline} mode, and the second is called @dfn{hungry-delete}
-mode. These minor modes can be toggled on and off independently, and
-@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.
+@table @asis
+@item @kbd{C-c C-c} (@code{comment-region})
+@kindex C-c C-c
+@findex comment-region
+This command comments out the lines that start in the region. With a
+negative argument, it does the opposite - it deletes the comment
+delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU
+Emacs Manual}, for fuller details. @code{comment-region} isn't
+actually part of @ccmode{} - it is given a @ccmode{} binding for
+convenience.
+
+@item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.})
+@kindex M-;
+@findex comment-dwim
+@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 @code{comment-column}
+@ifclear XEMACS
+(@pxref{Options for Comments,,, emacs, GNU Emacs Manual})
+@end ifclear
+@ifset XEMACS
+(@pxref{Comments,,, xemacs, XEmacs User's Manual})
+@end ifset
+and the variables below. Finally, position the point after the
+comment starter. @kbd{C-u M-;} kills any comment on the current line,
+together with any whitespace before it. 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 vary the column that @kbd{M-;} puts
+the comment at, depending on what sort of code is on the line, and
+possibly the indentation of any similar comment on the preceding line.
+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 for a full description of this
+variable (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 style 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 @key{TAB} for comment-only
+lines you can get that by setting
+@code{c-indent-comments-syntactically-p} to non-@code{nil}.
+
+If @code{c-indent-comments-syntactically-p} is non-@code{nil} then
+@code{c-indent-comment-alist} won't be consulted at all for comment-only
+lines.
+@end defopt
+@end table
-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 line @footnote{The @samp{C}
-would be replaced with @samp{C++}, @samp{ObjC}, @samp{Java}, @samp{IDL},
-or @samp{Pike} for the respective languages.}. When hungry delete mode
-is enabled you would see @samp{C/h} and when both modes are enabled,
-you'd see @samp{C/ah}.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Movement Commands, Filling and Breaking, Comment Commands, Commands
+@comment node-name, next, previous, up
+@section Movement Commands
+@cindex movement
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@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} (@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
+@ccmode{} contains some useful commands for moving around in C code.
-(add-hook 'c-mode-common-hook
- (lambda () (c-toggle-auto-hungry-state 1)))
+@table @asis
+@item @kbd{M-x c-beginning-of-defun}
+@itemx @kbd{M-x c-end-of-defun}
+@findex c-beginning-of-defun
+@findex c-end-of-defun
+@findex beginning-of-defun (c-)
+@findex end-of-defun (c-)
+@findex beginning-of-defun
+@findex end-of-defun
+Move to the start or end of the current top-level definition. This is
+the outermost brace pair which encloses point, together with the
+function header or similar preamble which precedes the opening brace.
+These functions are analogous to the Emacs built-in commands
+@code{beginning-of-defun} and @code{end-of-defun}, except they
+eliminate the constraint that the top-level opening brace of the defun
+must be in column zero. See @ref{Defuns,,,@emacsman{},
+@emacsmantitle{}}, for more information.
+
+Depending on the coding style you're using, you might prefer these two
+commands to the standard Emacs ones. If so, consider binding them to
+@kbd{C-M-a} and @kbd{C-M-e}. @xref{Sample .emacs File}. This
+customization won't affect the special bindings for these key
+sequences in force in AWK Mode. For backwards compatibility reasons,
+the default bindings for @kbd{C-M-a} and @kbd{C-M-e} remain in effect.
+
+@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
+@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
+@kindex C-M-a (AWK Mode)
+@kindex C-M-e (AWK Mode)
+@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 back to the beginning or forward to the end of the current AWK
+defun. These functions are bound to @kbd{C-M-a} and @kbd{C-M-e} by
+default in AWK Mode. They can take prefix-arguments, their
+functionality being entirely equivalent to @code{beginning-of-defun}
+and @code{end-of-defun}.
+
+AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
+might be implicit) or user defined functions. Having the @samp{@{} and
+@samp{@}} (if there are any) in column zero, as is suggested for some
+modes, is neither necessary nor helpful in AWK mode.
-@end example
+@item @kbd{M-a} (@code{c-beginning-of-statement})
+@itemx @kbd{M-e} (@code{c-end-of-statement})
+@kindex M-a
+@kindex M-e
+@findex c-beginning-of-statement
+@findex c-end-of-statement
+@findex beginning-of-statement (c-)
+@findex end-of-statement (c-)
+Move to the beginning or end of the innermost C statement. If point
+is already there, move to the next beginning or end of a statement,
+even if that means moving into a block. (Use @kbd{C-M-b} or
+@kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n}
+means move over @var{n} statements.
+If point is within or next to a comment or a string which spans more
+than one line, these commands move by sentences instead of statements.
-@cindex electric characters
+When called from a program, these functions take 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.
-@menu
-* Auto-newline Insertion::
-* Hungry-deletion of Whitespace::
-@end menu
+@item @kbd{C-c C-u} (@code{c-up-conditional})
+@kindex C-c C-u
+@findex c-up-conditional
+@findex up-conditional (c-)
+Move back to the containing preprocessor conditional, leaving the mark
+behind. A prefix argument acts as a repeat count. With a negative
+argument, move 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.
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Auto-newline Insertion, Hungry-deletion of Whitespace, , Minor Modes
-@comment node-name, next, previous, up
-@section Auto-newline Insertion
-@cindex auto-newline insertion
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+This key sequence is not bound in AWK Mode, which doesn't have
+preprocessor statements.
-@cindex electric commands
-Auto-newline minor mode works by enabling certain @dfn{electric
-commands}. Electric commands are typically bound to special characters
-such as the left and right braces, colons, semi-colons, etc., which when
-typed, perform some magic formatting in addition to inserting the typed
-character. As a general rule, electric commands are only electric when
-the following conditions apply:
+@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.
-@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 @kbd{M-x c-down-conditional}
+@findex c-down-conditional
+@findex down-conditional (c-)
+Move forward into the next nested preprocessor conditional, leaving
+the mark behind. A prefix argument acts as a repeat count. With a
+negative argument, move backward into the previous nested preprocessor
+conditional.
-@cindex literal
-@cindex syntactic whitespace
-@item
-The character was not typed inside of a literal @footnote{A
-@dfn{literal} is defined as any comment, string, or C preprocessor macro
-definition. These constructs are also known as @dfn{syntactic
-whitespace} since they are usually ignored when scanning C code.}.
+@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
-@kindex C-u
-No numeric argument was supplied to the command (i.e. it was typed as
-normal, with no @kbd{C-u} prefix).
+@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.
-@end itemize
+@item @kbd{C-c C-p} (@code{c-backward-conditional})
+@itemx @kbd{C-c C-n} (@code{c-forward-conditional})
+@kindex C-c C-p
+@kindex C-c C-n
+@findex c-backward-conditional
+@findex c-forward-conditional
+@findex backward-conditional (c-)
+@findex forward-conditional (c-)
+Move backward or forward across a preprocessor conditional, leaving
+the mark behind. A prefix argument acts as a repeat count. With a
+negative argument, move in the opposite direction.
-@menu
-* Hanging Braces::
-* Hanging Colons::
-* Hanging Semi-colons and Commas::
-* Other Electric Commands::
-* Clean-ups::
-@end menu
+These key sequences are not bound in AWK Mode, which doesn't have
+preprocessor statements.
+
+@item @kbd{M-x c-backward-into-nomenclature}
+@itemx @kbd{M-x c-forward-into-nomenclature}
+@findex c-backward-into-nomenclature
+@findex c-forward-into-nomenclature
+@findex backward-into-nomenclature (c-)
+@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}.
+These commands move backward or forward to the beginning of the next
+capitalized word. With prefix argument @var{n}, move @var{n} times.
+If @var{n} is negative, move in the opposite direction.
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Hanging Braces, Hanging Colons, , Auto-newline Insertion
-@comment node-name, next, previous, up
-@subsection Hanging Braces
-@cindex hanging braces
+Note that these two commands have been superseded by
+@code{c-subword-mode}, which you should use instead. @xref{Subword
+Movement}. They might be removed from a future release of @ccmode{}.
+@end table
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Filling and Breaking, Minor Modes, Movement Commands, Commands
+@comment node-name, next, previous, up
+@section Filling and Line Breaking Commands
+@cindex text filling
+@cindex line breaking
+@cindex comment handling
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@findex c-electric-brace
-@findex electric-brace (c-)
-@vindex c-hanging-braces-alist
-@vindex hanging-braces-alist (c-)
-When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}),
-the electric command @code{c-electric-brace} gets run. This command has
-two electric formatting behaviors. First, it will perform some
-re-indentation of the line the brace was typed on, and second, it will
-add various newlines before and/or after the typed brace.
-Re-indentation occurs automatically whenever the electric behavior is
-enabled. If the brace ends up on a line other than the one it was typed
-on, then that line is also re-indented.
-
-@cindex class-open syntactic symbol
-@cindex class-close syntactic symbol
-@cindex defun-open syntactic symbol
-@cindex defun-close syntactic symbol
-@cindex inline-open syntactic symbol
-@cindex inline-close syntactic symbol
-@cindex brace-list-open syntactic symbol
-@cindex brace-list-close syntactic symbol
-@cindex brace-list-intro syntactic symbol
-@cindex brace-entry-open syntactic symbol
-@cindex block-open syntactic symbol
-@cindex block-close syntactic symbol
-@cindex substatement-open syntactic symbol
-@cindex statement-case-open syntactic symbol
-@cindex extern-lang-open syntactic symbol
-@cindex extern-lang-close syntactic symbol
-@cindex namespace-open syntactic symbol
-@cindex namespace-close syntactic symbol
-@cindex inexpr-class-open symbol
-@cindex inexpr-class-close symbol
-
-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. 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{class-open}, @code{class-close}, @code{defun-open},
-@code{defun-close}, @code{inline-open}, @code{inline-close},
-@code{brace-list-open}, @code{brace-list-close},
-@code{brace-list-intro}, @code{brace-entry-open}, @code{block-open},
-@code{block-close}, @code{substatement-open},
-@code{statement-case-open}, @code{extern-lang-open},
-@code{extern-lang-close}, @code{namespace-open}, @code{namespace-close},
-@code{inexpr-class-open}, and @code{inexpr-class-close}@footnote{Note
-that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})},
-@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.}. @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.
+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 seamlessly, 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{} keeps the indentation, fixes suitable comment line prefixes,
+and so on.
-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 classes@footnote{The
-braces of anonymous classes produces a combination of
-@code{inexpr-class}, and @code{class-open} or @code{class-close} in
-normal indentation analysis.}.
+You can configure the exact way comments get filled and broken, and
+where Emacs does auto-filling (see @pxref{Custom Filling and
+Breaking}). Typically, the style system (@pxref{Styles}) will have
+set this up for you, so you probably won't have to bother.
-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}.
+@findex auto-fill-mode
+@cindex Auto Fill mode
+@cindex paragraph filling
+Line breaks are by default handled (almost) the same regardless of
+whether they are made by auto fill mode (@pxref{Auto Fill,,,
+@emacsman{}, @emacsmantitle{}}), by 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.@footnote{You can change this default by
+setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols}
+and @pxref{Customizing Indentation})}.
-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
-@group
+@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 command fills 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.
-// here, open braces always `hang'
-void spam( int i ) @{
- if( i == 7 ) @{
- dosomething(i);
- @}
-@}
+The formatting of the starters (@code{/*}) and enders (@code{*/}) of
+block comments are kept as they were before the filling. I.e., if
+either the starter or ender were on a line of its own, then it stays
+on its own line; conversely, if the delimiter has comment text on its
+line, it keeps at least one word of that text with it on the line.
+This command is the replacement for @code{fill-paragraph} in @ccmode{}
+buffers.
-@end group
-@end example
+@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 breaks the current line at point and indents the new line. If
+point was in a comment, the new line gets the proper comment line
+prefix. If point was inside a macro, a backslash is inserted before
+the line break. It is the replacement for
+@code{indent-new-comment-line}.
-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.
+@item @kbd{M-x c-context-line-break}
+@findex c-context-line-break
+@findex context-line-break (c-)
+Insert a line break suitable to the context: If the point is inside a
+comment, the new line gets the suitable indentation and comment line
+prefix like @code{c-indent-new-comment-line}. In normal code it's
+indented like @code{newline-and-indent} would do. 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{Custom Macros}, for details about the backslash alignment.
+
+This function is 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. @xref{Sample .emacs File}.
+
+@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
-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
-@group
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Minor Modes, Electric Keys, Filling and Breaking, Commands
+@comment node-name, next, previous, up
+@section Minor Modes
+@cindex Minor Modes
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
- ((brace-list-open)
- (brace-entry-open)
- (substatement-open after)
- (block-close . c-snug-do-while)
- (extern-lang-open after)
- (inexpr-class-open after)
- (inexpr-class-close before))
+@ccmode{} contains several minor-mode-like features that you might
+find useful while writing new code or editing old code:
-@end group
-@end example
+@table @asis
+@item electric mode
+When this is enabled, certain visible characters cause reformatting as
+they are typed. This is normally helpful, but can be a nuisance when
+editing chaotically formatted code. It can also be disconcerting,
+especially for users who are new to @ccmode{}.
+@item auto-newline mode
+This automatically inserts newlines where you'd probably want to type
+them yourself, e.g. after typing @samp{@}}s. Its action is suppressed
+when electric mode is disabled.
+@item hungry-delete mode
+This lets you delete a contiguous block of whitespace with a single
+key - for example, the newline and indentation just inserted by
+auto-newline when you want to back up and write a comment after the
+last statement.
+@item subword mode
+This mode makes basic word movement commands like @kbd{M-f}
+(@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the
+parts of sillycapsed symbols as different words.
+E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS},
+@samp{Graphics}, and @samp{Context}.
+@item syntactic-indentation mode
+When this is enabled (which it normally is), indentation commands such
+as @kbd{C-j} indent lines of code according to their syntactic
+structure. Otherwise, a line is simply indented to the same level as
+the previous one and @kbd{@key{TAB}} adjusts the indentation in steps
+of `c-basic-offset'.
+@end table
-@noindent which says that @code{brace-list-open} and
-@code{brace-entry-open} braces should both hang on the right side, and
-allow subsequent text to follow on the same line as the brace. Also,
-@code{substatement-open}, @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.
+Full details on how these minor modes work are at @ref{Electric Keys},
+@ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement},
+and @ref{Indentation Engine Basics}.
-A word of caution: it is not a good idea to hang top-level construct
-introducing braces, such as @code{class-open} or @code{defun-open}.
-Emacs makes an assumption that such braces will always appear in column
-zero, hanging them can introduce performance problems.
-@xref{Performance Issues}, for more information.
+You can toggle each of these minor modes on and off, and you can
+configure @ccmode{} so that it starts up with your favourite
+combination of them (@pxref{Sample .emacs File}). By default, when
+you initialize a buffer, electric mode and syntactic-indentation mode
+are enabled but the other two modes are disabled.
+@ccmode{} displays the current state of the first four of these minor
+modes on the modeline by appending letters to the major mode's name,
+one letter for each enabled minor mode - @samp{l} for electric mode,
+@samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and
+@samp{w} for subword mode. If all these modes were enabled, you'd see
+@samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of
+the language in question for the other languages @ccmode{} supports.}.
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Hanging Colons, Hanging Semi-colons and Commas, Hanging Braces, Auto-newline Insertion
-@comment node-name, next, previous, up
-@subsection Hanging Colons
-@cindex hanging colons
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+Here are the commands to toggle these modes:
-@vindex hanging-colons-alist (c-)
-@vindex c-hanging-colons-alist
-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}. 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.
+@table @asis
+@item @kbd{C-c C-l} (@code{c-toggle-electric-state})
+@kindex C-c C-l
+@findex c-toggle-electric-state
+@findex toggle-electric-state (c-)
+Toggle electric minor mode. When the command turns the mode off, it
+also suppresses auto-newline mode.
+
+@item @kbd{C-c C-a} (@code{c-toggle-auto-newline})
+@kindex C-c C-a
+@findex c-toggle-auto-newline
+@findex toggle-auto-newline (c-)
+Toggle auto-newline minor mode. When the command turns the mode on,
+it also enables electric minor mode.
-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.
+@item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.}
+@findex c-toggle-hungry-state
+@findex toggle-hungry-state (c-)
+Toggle hungry-delete minor mode.
+
+@item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.}
+@findex c-toggle-auto-hungry-state
+@findex toggle-auto-hungry-state (c-)
+Toggle both auto-newline and hungry delete minor modes.
+
+@item @kbd{C-c C-w} (@code{M-x c-subword-mode})
+@kindex C-c C-w
+@findex c-subword-mode
+@findex subword-mode (c-)
+Toggle subword mode.
+
+@item @kbd{M-x c-toggle-syntactic-indentation}
+@findex c-toggle-syntactic-indentation
+@findex toggle-syntactic-indentation (c-)
+Toggle syntactic-indentation mode.
+@end table
+
+Common to all the toggle functions above is that if they are called
+programmatically, they take an optional numerical argument. A
+positive value will turn on the minor mode (or both of them in the
+case of @code{c-toggle-auto-hungry-state}) and a negative value will
+turn it (or them) off.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Hanging Semi-colons and Commas, Other Electric Commands, Hanging Colons, Auto-newline Insertion
+@node Electric Keys, Auto-newlines, Minor Modes, Commands
@comment node-name, next, previous, up
-@subsection Hanging Semi-colons and Commas
-@cindex hanging semi-colons
-@cindex hanging commas
+@section Electric Keys and Keywords
+@cindex electric characters
@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
-Semi-colons and Commas}, for details.
+Most punctuation keys provide @dfn{electric} behavior - as well as
+inserting themselves they perform some other action, such as
+reindenting the line. This reindentation saves you from having to
+reindent a line manually after typing, say, a @samp{@}}. A few
+keywords, such as @code{else}, also trigger electric action.
+You can inhibit the electric behaviour described here by disabling
+electric minor mode (@pxref{Minor Modes}).
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Other Electric Commands, Clean-ups, Hanging Semi-colons and Commas, Auto-newline Insertion
-@comment node-name, next, previous, up
-@subsection Other Electric Commands
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+Common to all these keys is that they only behave electrically when
+used in normal code (as contrasted with getting typed in a string
+literal or comment). Those which cause re-indentation do so only when
+@code{c-syntactic-indentation} has a non-@code{nil} value (which it
+does by default).
+
+These keys and keywords are:
+@c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more
+@c like a bug in the code than a bug in this document. It'll get
+@c fixed in the code sometime.
+@table @kbd
+@item #
@kindex #
@findex c-electric-pound
-@vindex c-electric-pound-behavior
@findex electric-pound (c-)
+@vindex c-electric-pound-behavior
@vindex electric-pound-behavior (c-)
-A few other keys also provide electric behavior. For example
-@kbd{#} (@code{c-electric-pound}) is electric when typed as
-the first non-whitespace character on a line. In this case, the
-variable @code{c-electric-pound-behavior} is consulted for the electric
-behavior. This variable takes a list value, although the only element
-currently defined is @code{alignleft}, which tells this command to force
-the @samp{#} character into column zero. This is useful for entering
-C preprocessor macro definitions.
+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.
+@c ACM, 2004/8/24: Change this (and the code) to do AWK comment
+@c reindentation.
+@item *
+@kindex *
+@itemx /
+@kindex /
@findex c-electric-star
-@findex c-electric-slash
@findex electric-star (c-)
+@findex c-electric-slash
@findex electric-slash (c-)
-Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and
-@code{c-electric-slash} respectively) are also electric under
-certain circumstances. If a star is inserted as the second character of
-a C style block comment on a 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 slash 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}.
-
-@findex c-electric-lt-gt
-@findex electric-lt-gt (c-)
+A star (bound to @code{c-electric-star}) or a slash
+(@code{c-electric-slash}) causes reindentation when you type it as the
+second component of a C style block comment opener (@samp{/*}) or a
+C++ line comment opener (@samp{//}) respectively, but only if the
+comment opener is the first thing on the line (i.e. there's only
+whitespace before it).
+
+Additionally, you can configure @ccmode{} so that typing a slash at
+the start of a line within a block comment will terminate the
+comment. You don't need to have electric minor mode enabled to get
+this behaviour. @xref{Clean-ups}.
+
+In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not
+electric.
+
+@item <
@kindex <
+@itemx >
@kindex >
-Less-than and greater-than signs (@code{c-electric-lt-gt}) are also
-electric, but only in C++ mode. Hitting the second of two @kbd{<} or
-@kbd{>} keys re-indents the line if it is a C++ style stream operator.
-
-@findex c-electric-paren
-@findex electric-paren (c-)
+@findex c-electric-lt-gt
+@findex electric-lt-gt (c-)
+A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is
+electric in two circumstances: when it is an angle bracket in a C++
+@samp{template} declaration (and similar constructs in other
+languages) and when it is the second of two @kbd{<} or @kbd{>}
+characters in a C++ style stream operator. In either case, the line
+is reindented. Angle brackets in C @samp{#include} directives are not
+electric.
+
+@item (
@kindex (
+@itemx )
@kindex )
-The normal parenthesis characters @samp{(} and @samp{)} also reindent
-the current line if they are used in normal code. This is useful for
-getting the closing parenthesis of an argument list aligned
+@findex c-electric-paren
+@findex electric-paren (c-)
+The normal parenthesis characters @samp{(} and @samp{)} (bound to
+@code{c-electric-paren}) reindent the current line. This is useful
+for getting the closing parenthesis of an argument list aligned
automatically.
+You can also configure @ccmode{} to insert a space automatically
+between a function name and the @samp{(} you've just typed, and to
+remove it automatically after typing @samp{)}, should the argument
+list be empty. You don't need to have electric minor mode enabled to
+get these actions. @xref{Clean-ups}.
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Clean-ups, , Other Electric Commands, Auto-newline Insertion
-@comment node-name, next, previous, up
-@subsection Clean-ups
-@cindex clean-ups
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@item @{
+@kindex @{
+@itemx @}
+@kindex @}
+@findex c-electric-brace
+@findex electric-brace (c-)
+Typing a brace (bound to @code{c-electric-brace}) reindents the
+current line. Also, one or more newlines might be inserted if
+auto-newline minor mode is enabled. @xref{Auto-newlines}.
+Additionally, you can configure @ccmode{} to compact excess whitespace
+inserted by auto-newline mode in certain circumstances.
+@xref{Clean-ups}.
+
+@item :
+@kindex :
+@findex c-electric-colon
+@findex electric-colon (c-)
+Typing a colon (bound to @code{c-electric-colon}) reindents the
+current line. Additionally, one or more newlines might be inserted if
+auto-newline minor mode is enabled. @xref{Auto-newlines}. If you
+type a second colon immediately after such an auto-newline, by default
+the whitespace between the two colons is removed, leaving a C++ scope
+operator. @xref{Clean-ups}.
+
+If you prefer, you can insert @samp{::} in a single operation,
+avoiding all these spurious reindentations, newlines, and clean-ups.
+@xref{Other Commands}.
+
+@item ;
+@kindex ;
+@itemx ,
+@kindex ,
+@findex c-electric-semi&comma
+@findex electric-semi&comma (c-)
+Typing a semicolon or comma (bound to @code{c-electric-semi&comma})
+reindents the current line. Also, a newline might be inserted if
+auto-newline minor mode is enabled. @xref{Auto-newlines}.
+Additionally, you can configure @ccmode{} so that when auto-newline
+has inserted whitespace after a @samp{@}}, it will be removed again
+when you type a semicolon or comma just after it. @xref{Clean-ups}.
-@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.
+@end table
-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.
+@deffn Command c-electric-continued-statement
+@findex electric-continued-statement (c-)
-@vindex 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.
+Certain keywords are electric, causing 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).
-These are the clean-ups that only are active in the auto-newline minor
-mode:
+An example:
-@itemize @bullet
-@item
-@code{brace-else-brace} --- Clean up @samp{@} else @{} constructs by
-placing the entire construct on a single line. Clean-up occurs when the
-open brace after the @samp{else} is typed. So for example, this:
@example
@group
-
-void spam(int i)
-@{
- if( i==7 )
- @{
- dosomething();
- @}
- else
- @{
-
+for (i = 0; i < 17; i++)
+ if (a[i])
+ res += a[i]->offset;
+else
@end group
@end example
-@noindent
-appears like this after the open brace is typed:
-@example
-@group
-void spam(int i)
-@{
- if( i==7 ) @{
- dosomething();
- @} else @{
+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 only
+then is it possible to decide whether it's a new statement or a
+continuation of the preceding @code{if}.
-@end group
-@end example
+@vindex abbrev-mode
+@findex abbrev-mode
+@cindex Abbrev mode
+@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}})
+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 Auto-newlines, Hungry WS Deletion, Electric Keys, Commands
+@comment node-name, next, previous, up
+@section Auto-newline Insertion
+@cindex auto-newline
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor
+Modes}), @ccmode{} inserts newlines for you automatically (in certain
+syntactic contexts) when you type a left or right brace, a colon, a
+semicolon, or a comma. Sometimes a newline appears before the
+character you type, sometimes after it, sometimes both.
+Auto-newline only triggers when the following conditions hold:
+
+@itemize @bullet
@item
-@code{brace-elseif-brace} --- Similar to the @code{brace-else-brace}
-clean-up, but this cleans up @samp{@} 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 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 open brace is typed:
-@example
-@group
-
-void spam(int i)
-@{
- if( i==7 ) @{
- dosomething();
- @} else if( i==3 ) @{
-
-@end group
-@end example
-
-@item
-@code{brace-catch-brace} --- Analogous to @code{brace-elseif-brace}, but
-cleans up @samp{@} catch (...) @{} in C++ and Java mode.
+Auto-newline minor mode is enabled, as evidenced by the indicator
+@samp{a} after the mode name on the modeline (e.g. @samp{C/a} or
+@samp{C/la}).
@item
-@code{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
-@{@}
-
-@end group
-@end example
+The character was typed at the end of a line, or with only whitespace
+after it, and possibly a @samp{\} escaping the newline.
@item
-@code{defun-close-semi} --- Clean up the terminating semi-colon on
-top-level function or class definitions when they follow a close
-brace. Clean up occurs when the semi-colon is typed.
-So for example, the following:
-@example
-@group
-
-class Spam
-@{
-@}
-;
-
-@end group
-@end example
-@noindent
-is transformed into this when the semi-colon is typed:
-
-@example
-@group
-
-class Spam
-@{
-@};
-
-@end group
-@end example
+The character is not on its own line already. (This applies only to
+insertion of a newline @emph{before} the character.)
@item
-@code{list-close-comma} --- Clean up commas following braces in array
-and aggregate initializers. Clean up occurs when the comma is typed.
+@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
-@code{scope-operator} --- Clean up double colons which may designate a
-C++ scope operator split across multiple lines@footnote{Certain C++
-constructs introduce ambiguous situations, so @code{scope-operator}
-clean-ups may not always be correct. This usually only occurs when
-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.
-
+No numeric argument was supplied to the command (i.e. it was typed as
+normal, with no @kbd{C-u} prefix).
@end itemize
-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:
-
-@itemize @bullet
-@item
-@code{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
-@code{compact-empty-funcall} --- Clean up any space between the function
-name and the opening parenthesis of a function call that have 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.
+You can configure the precise circumstances in which newlines get
+inserted (see @pxref{Custom Auto-newlines}). Typically, the style
+system (@pxref{Styles}) will have set this up for you, so you probably
+won't have to bother.
-@end itemize
+Sometimes @ccmode{} inserts an auto-newline where you don't want one,
+such as after a @samp{@}} when you're about to type a @samp{;}.
+Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can
+activate an appropriate @dfn{clean-up}, which will remove the excess
+whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a
+full description. See also @ref{Electric Keys} for a summary of
+clean-ups listed by key.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Hungry-deletion of Whitespace, , Auto-newline Insertion, Minor Modes
+@node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands
@comment node-name, next, previous, up
-@section Hungry-deletion of Whitespace
-@cindex hungry-deletion of whitespace
+@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!
+If you want to delete an entire block of whitespace at point, you can
+use @dfn{hungry deletion}. This deletes all the contiguous whitespace
+either before point or after point in a single operation.
+``Whitespace'' here includes tabs and newlines, but not comments or
+preprocessor commands. Hungry deletion can markedly cut down on the
+number of times you have to hit deletion keys when, for example,
+you've made a mistake on the preceding line and have already pressed
+@kbd{C-j}.
-@kindex DEL
-@kindex Backspace
-In a nutshell, when hungry-delete mode is enabled, hitting the
-@key{Backspace} key@footnote{I say ``hit the @key{Backspace} key'' but
-what I really mean is ``when Emacs receives the @code{BackSpace} key
-event.'' The difference usually isn't significant to most users, but
-advanced users will realize that under window systems such as X, any
-physical key (keycap) on the keyboard can be configured to generate any
-keysym, and thus any Emacs key event. Also, the use of Emacs on TTYs
-will affect which keycap generates which key event. From a pedantic
-point of view, here we are only concerned with the key event that
-Emacs receives.} will consume all preceding whitespace, including
-newlines and tabs. This can really cut down on the number of
-@key{Backspace}'s you have to type if, for example you made a mistake on
-the preceding line.
+Hungry deletion is a simple feature that some people find extremely
+useful. In fact, you might find yourself wanting it in @strong{all}
+your editing modes!
+
+Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the
+backspace key'' and @dfn{@key{DELETE}} means ``the forward delete
+key''. This is discussed in more detail below.
+
+There are two different ways you can use hungry deletion:
+
+@table @asis
+@item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d}
+Here you toggle Hungry Delete minor mode with @kbd{M-x
+c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command
+was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding
+for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This
+makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry
+deletion.
+@table @asis
+@item @kbd{@key{DEL}} (@code{c-electric-backspace})
+@kindex DEL
@findex c-electric-backspace
@findex electric-backspace (c-)
+This command is run by default when you hit the @kbd{DEL} key. When
+hungry delete mode is enabled, it deletes any amount of whitespace in
+the backwards direction. Otherwise, or when used with a prefix
+argument or in a literal (@pxref{Auto-newlines}), the command just
+deletes backwards in the usual way. (More precisely, it calls the
+function contained in the variable @code{c-backspace-function},
+passing it the prefix argument, if any.)
+
+@item @code{c-backspace-function}
@vindex c-backspace-function
@vindex backspace-function (c-)
-
-@findex c-electric-delete
-@findex electric-delete (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}
+(@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which
+deletes a single character.
+
+@item @kbd{C-d} (@code{c-electric-delete-forward})
+@kindex C-d
+@findex 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
+just does @code{delete-char}, more or less. (Strictly speaking, it
+calls the function in @code{c-delete-function} with the prefix
+argument.)
+
+@item @code{c-delete-function}
@vindex c-delete-function
@vindex delete-function (c-)
-@cindex literal
+@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 table
-@findex backward-delete-char-untabify
+@item Using Distinct Bindings
+The other (newer and recommended) way to use hungry deletion is to
+perform @code{c-hungry-delete-backwards} and
+@code{c-hungry-delete-forward} directly through their key sequences
+rather than using the minor mode toggling.
+
+@table @asis
+@item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.}
+@kindex C-c C-<backspace>
+@kindex C-c <backspace>
+@kindex C-c C-DEL
+@kindex C-c DEL
+@findex c-hungry-delete-backwards
+@findex hungry-delete-backwards (c-)
+Delete any amount of whitespace in the backwards direction (regardless
+whether hungry-delete mode is enabled or not). This command is bound
+to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more
+natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at
+a character terminal.
+
+@item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward})
+@kindex C-c C-d
+@kindex C-c C-<DELETE>
+@kindex C-c <DELETE>
+@findex 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). This command is bound
+to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the
+same reason as for @key{DEL} above.
+@end table
+@end table
+
+@kindex <delete>
+@kindex <backspace>
-By default, when you hit the @key{Backspace} key @ccmode{} runs the
-command @code{c-electric-backspace}, which deletes text in the backwards
-direction. When deleting a single character, or when @key{Backspace} is
-hit in a literal (@pxref{Auto-newline Insertion}), or when hungry-delete
-mode is disabled, the function contained in the
-@code{c-backspace-function} variable is called with one argument (the
-number of characters to delete). This variable is set to
-@code{backward-delete-char-untabify} by default.
+When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we
+actually do so without connecting them to the physical keys commonly
+known as @key{Backspace} and @key{Delete}. The default bindings to
+those two keys depends on the flavor of (X)Emacs you are using.
+@findex c-electric-delete
+@findex electric-delete (c-)
+@findex c-hungry-delete
+@findex hungry-delete (c-)
@vindex delete-key-deletes-forward
-@findex delete-char
+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.
+@c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...).
+When this variable is non-@code{nil}, @code{c-electric-delete} will do
+forward deletion with @code{c-electric-delete-forward}, otherwise it
+does backward deletion with @code{c-electric-backspace}. Similarly,
+@kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to
+@code{c-hungry-delete} which is controlled in the same way by
+@code{delete-key-deletes-forward}.
+
+@findex normal-erase-is-backspace-mode
+
+Emacs 21 and later automatically binds @key{Backspace} and
+@key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment,
+and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}}
+etc. If you need to change the bindings through
+@code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt
+its extended bindings accordingly.
+
+In earlier (X)Emacs versions, @ccmode{} doesn't bind either
+@key{Backspace} or @key{Delete} directly. Only the key codes
+@kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings
+to map the physical keys to them. You might need to modify this
+yourself if the defaults are unsuitable.
+
+Getting your @key{Backspace} and @key{Delete} keys properly set up can
+sometimes be tricky. The information in @ref{DEL Does Not
+Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having
+trouble with this in GNU Emacs.
+
-The default behavior of the @key{Delete} key depends on the flavor of
-Emacs you are using. By default in XEmacs 20.3 and beyond, the
-@key{Delete} key is bound to @code{c-electric-delete}. You control the
-direction that the @key{Delete} key deletes by setting the variable
-@code{delete-key-deletes-forward}, a standard XEmacs variable. When
-this variable is non-@code{nil} and hungry-delete mode is enabled,
-@code{c-electric-delete} will consume all whitespace @emph{following}
-point. When @code{delete-key-deletes-forward} is @code{nil}, it deletes
-all whitespace @emph{preceding} point@footnote{i.e. it literally calls
-@code{c-electric-backspace}.} When deleting a single character, or if
-@key{Delete} is hit in a literal, or hungry-delete mode is disabled, the
-function contained in @code{c-delete-function} is called with one
-argument: the number of characters to delete. This variable is set to
-@code{delete-char} by default.
-
-In Emacs 19 or Emacs 20, both the @key{Delete} and @key{Backspace} keys
-are bound to @code{c-electric-backspace}, however you can change this by
-explicitly binding @code{[delete]}@footnote{E.g. to
-@code{c-electric-delete} in your @file{.emacs} file. Note however, that
-Emacs 20 does not have a standard variable such as
-@code{delete-key-deletes-forward}.}.
-
-XEmacsen older than 20.3 behave similar to Emacs 19 and Emacs 20.
-
-
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Text Filling and Line Breaking, Commands, Minor Modes, Top
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Subword Movement, Other Commands, Hungry WS Deletion, Commands
@comment node-name, next, previous, up
-@chapter Text Filling and Line Breaking
+@section Subword Movement and Editing
@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.
+@cindex nomenclature
+@cindex subword
+In spite of the GNU Coding Standards, it is popular to name a symbol
+by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget},
+@samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call
+these mixed case symbols @dfn{nomenclatures}. Also, each capitalized
+(or completely uppercase) part of a nomenclature is called a
+@dfn{subword}. Here are some examples:
+
+@multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}}
+@headitem Nomenclature
+ @tab Subwords
+@item @samp{GtkWindow}
+ @tab @samp{Gtk} and @samp{Window}
+@item @samp{EmacsFrameClass}
+ @tab @samp{Emacs}, @samp{Frame}, and @samp{Class}
+@item @samp{NSGraphicsContext}
+ @tab @samp{NS}, @samp{Graphics}, and @samp{Context}
+@end multitable
+
+The subword minor mode replaces the basic word oriented movement and
+editing commands with variants that recognize subwords in a
+nomenclature and treat them as separate words:
+
+@findex c-forward-subword
+@findex forward-subword (c-)
+@findex c-backward-subword
+@findex backward-subword (c-)
+@findex c-mark-subword
+@findex mark-subword (c-)
+@findex c-kill-subword
+@findex kill-subword (c-)
+@findex c-backward-kill-subword
+@findex backward-kill-subword (c-)
+@findex c-transpose-subwords
+@findex transpose-subwords (c-)
+@findex c-capitalize-subword
+@findex capitalize-subword (c-)
+@findex c-upcase-subword
+@findex upcase-subword (c-)
+@findex c-downcase-subword
+@findex downcase-subword (c-)
+@multitable @columnfractions .20 .40 .40
+@headitem Key @tab Word oriented command @tab Subword oriented command
+@item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword}
+@item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword}
+@item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword}
+@item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword}
+@item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword}
+@item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords}
+@item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword}
+@item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword}
+@item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword}
+@end multitable
+
+Note that if you have changed the key bindings for the word oriented
+commands in your @file{.emacs} or a similar place, the keys you have
+configured are also used for the corresponding subword oriented
+commands.
+
+Type @kbd{C-c C-w} to toggle subword mode on and off. To make the
+mode turn on automatically, put the following code in your
+@file{.emacs}:
-@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
-variables@footnote{@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 style of line decoration that
-starts every line in a comment. The style variable
-@code{c-comment-prefix-regexp} contains the regexp used to recognize
-this @dfn{comment line prefix}. The default is @samp{//+\\|\\**}, which
-matches C++ style line comments like
@example
+(add-hook 'c-mode-common-hook
+ (lambda () (c-subword-mode 1)))
+@end example
-// blah blah
+As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{}
+buffers by typing @kbd{M-x c-subword-mode}.
-@end example
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Other Commands, , Subword Movement, Commands
+@comment node-name, next, previous, up
+@section Other Commands
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@noindent
-with two or more slashes in front of them, and C style block comments
-like
-@example
-@group
+Here are the various other commands that didn't fit anywhere else:
-/*
- * blah blah
- */
+@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 group
-@end example
+@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 end-of-line backslashes in
+the current region. These are typically used in multi-line macros.
+
+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.
+
+To customize the precise workings of this command, @ref{Custom Macros}.
+@end table
@noindent
-with zero or more stars at the beginning of every line. If you change
-that variable, please make sure it still matches the comment starter
-(i.e. @code{//}) of line comments @emph{and} the line prefix inside
-block comments. Also note that since @ccmode{} uses the value of
-@code{c-comment-prefix-regexp} to set up several other variables at mode
-initialization, you need to reinitialize the program mode if you change
-it inside a @ccmode{} buffer.
+The recommended line breaking function, @code{c-context-line-break}
+(@pxref{Filling and 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.
-@findex auto-fill-mode
-@cindex auto fill mode
-@cindex paragraph fill
-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.
+@table @asis
+@item @kbd{C-c C-e} (@code{c-macro-expand})
+@kindex C-c C-e
+@findex c-macro-expand
+@findex macro-expand (c-)
+This command expands C, C++, Objective C or Pike macros in the region,
+using an appropriate external preprocessor program. Normally it
+displays its output in a temporary buffer, but if you give it a prefix
+arg (with @kbd{C-u C-c C-e}) it will overwrite the original region
+with the expansion.
+
+The command does not work in any of the other modes, and the key
+sequence is not bound in these other modes.
+
+@code{c-macro-expand} isn't actually part of @ccmode{}, even though it
+is bound to a @ccmode{} key sequence. If you need help setting it up
+or have other problems with it, you can either read its source code or
+ask for help in the standard (X)Emacs forums.
+@end table
-@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 kept intact:
-@example
-@group
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Font Locking, Config Basics, Commands, Top
+@comment node-name, next, previous, up
+@chapter Font Locking
+@cindex font locking
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-/* 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.
- */
+@cindex Font Lock mode
-@end group
-@end example
+@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, GNU Emacs Manual}, for ways to enable font locking in
+@ccmode{} buffers.
-@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 package@footnote{It'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 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
-@group
+@strong{Please note:} The font locking in AWK mode is currently not
+integrated with the rest of @ccmode{}. Only the last section of this
+chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other
+sections apply to the other languages.
-(defun my-c-mode-common-hook ()
- (c-setup-filladapt)
- (filladapt-mode 1))
-(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+@menu
+* Font Locking Preliminaries::
+* Faces::
+* Doc Comments::
+* AWK Mode Font Locking::
+@end menu
-@end group
-@end example
-@vindex 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 clue about how the prefix should look, namely
-when a block comment is broken for the first time. The string in the
-style variable @code{c-block-comment-prefix}@footnote{In 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 in that case. It defaults to @samp{* }, which
-makes a comment
-@example
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Font Locking Preliminaries, Faces, Font Locking, Font Locking
+@comment node-name, next, previous, up
+@section Font Locking Preliminaries
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-/* Got O(n^2) here, which is a Bad Thing. */
+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 peculiarities 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} (@pxref{Font Lock,,,
+emacs, GNU Emacs Manual}).
+
+@vindex font-lock-maximum-decoration
+
+The decoration levels are used as follows:
-@end example
+@enumerate
+@comment 1
+@item
+Minimal font locking: Fontify only comments, strings and preprocessor
+directives (in the languages that use cpp).
-@noindent
-break into
-@example
-@group
+@comment 2
+@item
+Fast 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{Doc Comments}).
-/* Got O(n^2) here,
- * which is a Bad Thing. */
+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.
-@end group
-@end example
+@comment 3
+@item
+Accurate 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. Fontifying the whole
+buffer at once can easily get bothersomely slow even on contemporary
+hardware.
+@c ACM, 2005/8/28: There should be a page in the (X)Emacs manual
+@c describing these support modes. There wasn't in the
+@c fourteenth edition of the Emacs manual (released with Emacs 21.3).
+@c There might be one in the Emacs CVS for 22.1.
+@end enumerate
-Note that it won't work to justify the indentation by putting leading
-spaces in the @code{c-block-comment-prefix} string, since @ccmode{}
-still uses the normal indentation engine to indent the line. Thus, the
-right way to fix the indentation is by setting 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}.
+@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
-@vindex 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 behavior can
-be controlled with the @code{c-ignore-auto-fill} variable. It takes a
-list of symbols for the different contexts where auto-filling never
-should occur:
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Faces, Doc 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 @code{string} --- Inside a string or character literal.
-@item @code{c} --- Inside a C style block comment.
-@item @code{c++} --- Inside a C++ style line comment.
-@item @code{cpp} --- Inside a preprocessor directive.
-@item @code{code} --- Anywhere else, i.e. in normal code.
-@end itemize
+@item
+@vindex font-lock-comment-face
+Normal comments are fontified in @code{font-lock-comment-face}.
-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.
+@item
+@vindex font-lock-doc-face
+@vindex font-lock-doc-string-face
+@vindex font-lock-comment-face
+Comments that are recognized as documentation (@pxref{Doc 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.
-The commands that does the actual work follows.
+@item
+@vindex font-lock-string-face
+String and character literals are fontified in
+@code{font-lock-string-face}.
-@table @asis
+@item
+@vindex font-lock-keyword-face
+Keywords are fontified with @code{font-lock-keyword-face}.
-@kindex M-q
-@findex c-fill-paragraph
-@findex fill-paragraph (c-)
-@cindex Javadoc markup
-@cindex Pike autodoc markup
-@item @kbd{M-q} (@code{c-fill-paragraph})
-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 similarly@footnote{This 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.}.
-
-@kindex M-j
-@findex c-indent-new-comment-line
-@findex indent-new-comment-line (c-)
-@item @kbd{M-j} (@code{c-indent-new-comment-line})
-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.
+@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.
-@vindex comment-multi-line
-If inside a comment and @code{comment-multi-line} is non-@code{nil}, 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.
+@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.
-@findex c-context-line-break
-@findex context-line-break (c-)
-@item @kbd{M-x c-context-line-break}
-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.
+@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.
-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 might consider switching to this function.
+@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.
-@end table
+@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.
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Commands, Customizing Indentation, Text Filling and Line Breaking, Top
-@comment node-name, next, previous, up
-@chapter Commands
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@item
+Special markup inside documentation comments are also fontified like
+labels.
-@menu
-* Indentation Commands::
-* Movement Commands::
-* Other Commands::
-@end menu
+@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.
-See also @ref{Text Filling and Line Breaking}, for commands concerning
-that bit.
+@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 Indentation Commands, Movement Commands, , Commands
-@comment node-name, next, previous,up
-@section Indentation Commands
-@cindex indentation commands
+@node Doc Comments, AWK Mode Font Locking, Faces, Font Locking
+@comment node-name, next, previous, up
+@section Documentation Comments
+@cindex documentation comments
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-The following list of commands re-indent C constructs. Note that when
-you change your coding style, either interactively or through some other
-means, your file does @emph{not} automatically get re-indented. You
-will need to execute one of the following commands to see the effects of
-your changes.
+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.
+
+The default value for @code{c-doc-comment-style} is
+@w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}.
+
+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'll 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:
-@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 re-indenting, 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 re-arrange brace location,
-among other things.
+@table @code
+@item javadoc
+@cindex Javadoc markup
+Javadoc comments, the standard tool in Java.
-Re-indenting 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. Especially vulnerable is
-code generator output@footnote{In particular, I have had people
-complain about the speed with which @code{lex(1)} output is re-indented.
-Lex, yacc, and other code generators usually output some pretty
-perversely formatted code. Re-indenting such code will be slow.}.
+@item autodoc
+@cindex Pike autodoc markup
+For Pike autodoc markup, the standard in Pike.
-These commands are useful when indenting code:
+@item gtkdoc
+@cindex GtkDoc markup
+For GtkDoc markup, widely used in the Gnome community.
+@end table
-@table @asis
+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
+Bug Reports}).
-@kindex TAB
-@findex c-indent-command
-@findex indent-command (c-)
-@item @kbd{TAB} (@code{c-indent-command})
-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.
-
-@kindex M-C-q
-@findex c-indent-exp
-@findex indent-exp (c-)
-@item @kbd{M-C-q} (@code{c-indent-exp})
-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.
+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}.
-@kindex C-c C-q
-@findex c-indent-defun
-@findex indent-defun (c-)
-@item @kbd{C-c C-q} (@code{c-indent-defun})
-Indents the entire top-level function or class definition encompassing
-point. It leaves point unchanged. This function can't be used to
-re-indent a nested brace construct, such as a nested class or function,
-or a Java method. The top-level construct being re-indented must be
-complete, i.e. it must have both a beginning brace and an ending brace.
+If you add support for another doc comment style, please consider
+contributing it - send a note to @email{bug-cc-mode@@gnu.org}.
-@kindex M-C-\
-@findex indent-region
-@item @kbd{M-C-\} (@code{indent-region})
-Indents an arbitrary region of code. This is a standard Emacs command,
-tailored for C code in a @ccmode{} buffer. Note that of course, point
-and mark must delineate the region you want to indent.
-@kindex M-C-h
-@findex c-mark-function
-@findex mark-function (c-)
-@item @kbd{M-C-h} (@code{c-mark-function})
-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.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node AWK Mode Font Locking, , Doc Comments, Font Locking
+@comment node-name, next, previous, up
+@section AWK Mode Font Locking
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@end table
+The general appearance of font-locking in AWK mode is much like in any
+other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs
+Lisp Reference Manual}.
-These variables are also useful when indenting code:
+The following faces are, however, used in a non-standard fashion in
+AWK mode:
-@table @code
+@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:
-@vindex c-tab-always-indent
-@vindex tab-always-indent (c-)
-@kindex TAB
-@cindex literal
-@item c-tab-always-indent
-This variable controls how @kbd{TAB} @code{c-indent-command} operates.
-When this variable is @code{t}, @kbd{TAB} always just 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 the symbol @code{other}, then some whitespace is inserted
-only within strings and comments (literals), an inside preprocessor
-directives, but the line is always reindented.
-
-@vindex c-insert-tab-function
-@vindex insert-tab-function (c-)
-@findex tab-to-tab-stop
-@item c-insert-tab-function
-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.
-
-@vindex indent-tabs-mode
-@item indent-tabs-mode
-This is a standard Emacs variable that controls how line indentation is
-composed. When this variable is non-@code{nil}, then tabs can be used
-in a line's indentation, otherwise only spaces can be used.
-
-@vindex c-progress-interval
-@vindex progress-interval (c-)
-@item c-progress-interval
-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 the
-interval in seconds that progress messages are displayed.
+@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 Config Basics, Custom Filling and Breaking, Font Locking, Top
+@comment node-name, next, previous, up
+@chapter Configuration Basics
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Movement Commands, Other Commands, Indentation Commands, Commands
-@comment node-name, next, previous, up
-@section Movement Commands
-@cindex movement commands
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-@ccmode{} contains some useful command for moving around in C
-code.
+@cindex Emacs Initiliazation File
+@cindex Configuration
+You configure @ccmode{} by setting Lisp variables and calling (and
+perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't
+difficult.}, which is usually done by adding code to an Emacs
+initialization file. This file might be @file{site-start.el} or
+@file{.emacs} or @file{init.el} or @file{default.el} or perhaps some
+other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For
+the sake of conciseness, we just call this file ``your @file{.emacs}''
+throughout the rest of the manual.
+
+Several of these variables (currently 16), are known collectively as
+@dfn{style variables}. @ccmode{} provides a special mechanism, known
+as @dfn{styles} to make it easier to set these variables as a group,
+to ``inherit'' settings from one style into another, and so on. Style
+variables remain ordinary Lisp variables, whose values can be read and
+changed independently of the style system. @xref{Style Variables}.
+
+There are several ways you can write the code, depending on the
+precise effect you want---they are described further down on this page.
+If you are new to @ccmode{}, we suggest you begin with the simplest
+method, ``Top-level commands or the customization interface''.
+
+If you make conflicting settings in several of these ways, the way
+that takes precedence is the one that appears latest in this list:
+@itemize @asis
+@item
@table @asis
+@item Style
+@itemx Top-level command or ``customization interface''
+@itemx Hook
+@itemx File Style
+@end table
+@end itemize
-@findex c-beginning-of-defun
-@findex beginning-of-defun (c-)
-@findex beginning-of-defun
-@item @kbd{M-x c-beginning-of-defun}
-Moves 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.
-
-@findex c-end-of-defun
-@findex end-of-defun (c-)
-@findex end-of-defun
-@item @kbd{M-x c-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{beginning-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.
+Here is a summary of the different ways of writing your configuration
+settings:
-@kindex C-c C-u
-@findex c-up-conditional
-@findex up-conditional (c-)
-@item @kbd{C-c C-u} (@code{c-up-conditional})
-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.
+@table @asis
+@item Top-level commands or the ``customization interface''
+Most simply, you can write @code{setq} and similar commands at the top
+level of your @file{.emacs} file. When you load a @ccmode{} buffer,
+it initializes its configuration from these global values (at least,
+for those settings you have given values to), so it makes sense to
+have these @code{setq} commands run @emph{before} @ccmode{} is first
+initialized---in particular, before any call to @code{desktop-read}
+(@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For
+example, you might set c-basic-offset thus:
-@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.
+@example
+(setq c-basic-offset 4)
+@end example
-@findex c-up-conditional-with-else
-@findex up-conditional-with-else (c-)
-@item @kbd{M-x c-up-conditional-with-else}
-A variety of @code{c-up-conditional} that also stops at @samp{#else}
-lines. Normally those lines are ignored.
+You can use the more user friendly Customization interface instead,
+but this manual does not cover in detail how that works. To do this,
+start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}.
+@xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}.
+@c The following note really belongs in the Emacs manual.
+Emacs normally writes the customizations at the end of your
+@file{.emacs} file. If you use @code{desktop-read}, you should edit
+your @file{.emacs} to place the call to @code{desktop-read} @emph{after}
+the customizations.
+
+The first initialization of @ccmode{} puts a snapshot of the
+configuration settings into the special style @code{user}.
+@xref{Built-in Styles}.
+
+For basic use of Emacs, either of these ways of configuring is
+adequate. However, the settings are then the same in all @ccmode{}
+buffers and it can be clumsy to communicate them between programmers.
+For more flexibility, you'll want to use one (or both) of @ccmode{}'s
+more sophisticated facilities, hooks and styles.
+
+@item Hooks
+An Emacs @dfn{hook} is a place to put Lisp functions that you want
+Emacs to execute later in specific circumstances.
+@xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main
+hook and a language-specific hook for each language it supports - any
+functions you put onto these hooks get executed as the last part of a
+buffer's initialization. Typically you put most of your customization
+within the main hook, and use the language-specific hooks to vary the
+customization settings between language modes. For example, if you
+wanted different (non-standard) values of @code{c-basic-offset} in C
+Mode and Java Mode buffers, you could do it like this:
-@findex c-down-conditional
-@findex down-conditional (c-)
-@item @kbd{M-x c-down-conditional}
-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.
+@example
+@group
+(defun my-c-mode-hook ()
+ (setq c-basic-offset 3))
+(add-hook 'c-mode-hook 'my-c-mode-hook)
-@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.
+(defun my-java-mode-hook ()
+ (setq c-basic-offset 6))
+(add-hook 'java-mode-hook 'my-java-mode-hook)
+@end group
+@end example
-@findex c-down-conditional-with-else
-@findex down-conditional-with-else (c-)
-@item @kbd{M-x c-down-conditional-with-else}
-A variety of @code{c-down-conditional} that also stops at @samp{#else}
-lines. Normally those lines are ignored.
+See @ref{CC Hooks} for more details on the use of @ccmode{} hooks.
-@kindex C-c C-p
-@findex c-backward-conditional
-@findex backward-conditional (c-)
-@item @kbd{C-c C-p} (@code{c-backward-conditional})
-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 Styles
+A @ccmode{} @dfn{style} is a coherent collection of customizations
+with a name. At any time, exactly one style is active in each
+@ccmode{} buffer, either the one you have selected or a default.
+@ccmode{} is delivered with several existing styles. Additionally,
+you can create your own styles, possibly based on these existing
+styles. If you worked in a programming team called the ``Free
+Group'', which had its own coding standards, you might well have this
+in your @file{.emacs} file:
-@kindex C-c C-n
-@findex c-forward-conditional
-@findex forward-conditional (c-)
-@item @kbd{C-c C-n} (@code{c-forward-conditional})
-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.
+@example
+(setq c-default-style '((java-mode . "java")
+ (awk-mode . "awk")
+ (other . "free-group-style")))
+@end example
-@kindex M-a
-@findex c-beginning-of-statement
-@findex beginning-of-statement (c-)
-@item @kbd{M-a} (@code{c-beginning-of-statement})
-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{M-C-b} to move over a balanced block). With prefix
-argument @var{n}, move back @var{n} @minus{} 1 statements.
+See @ref{Styles} for fuller details on using @ccmode{} styles and how
+to create them.
-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.
+@item File Styles
+A @dfn{file style} is a rarely used variant of the ``style'' mechanism
+described above, which applies to an individual source file. To use
+it, you set certain Emacs local variables in a special block at the
+end of the source file. @xref{File Styles}.
-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 Hooks with Styles
+For ultimate flexibility, you can use hooks and styles together. For
+example, if your team were developing a product which required a
+Linux driver, you'd probably want to use the ``linux'' style for the
+driver, and your own team's style for the rest of the code. You
+could achieve this with code like this in your @file{.emacs}:
-@kindex M-e
-@findex c-end-of-statement
-@findex end-of-statement (c-)
-@item @kbd{M-e} (@code{c-end-of-statement})
-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{M-C-f} to move to the other side of the
-block). With prefix argument @var{n}, move forward @var{n} @minus{} 1
-statements.
+@example
+@group
+(defun my-c-mode-hook ()
+ (c-set-style
+ (if (and (buffer-file-name)
+ (string-match "/usr/src/linux" (buffer-file-name)))
+ "linux"
+ "free-group-style")))
+(add-hook 'c-mode-hook 'my-c-mode-hook)
+@end group
+@end example
-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.
+In a programming team, a hook is a also a good place for each member
+to put his own personal preferences. For example, you might be the
+only person in your team who likes Auto-newline minor mode. You could
+have it enabled by default by placing the following in your
+@file{.emacs}:
-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.
+@example
+@group
+(defun my-turn-on-auto-newline ()
+ (c-toggle-auto-newline 1))
+(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline)
+@end group
+@end example
+@end table
-@findex c-forward-into-nomenclature
-@findex forward-into-nomenclature (c-)
-@item @kbd{M-x c-forward-into-nomenclature}
-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}.
+@menu
+* CC Hooks::
+* Style Variables::
+* Styles::
+@end menu
-This command moves point forward to next capitalized word. With prefix
-argument @var{n}, move @var{n} times.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node CC Hooks, Style Variables, Config Basics, Config Basics
+@comment node-name, next, previous, up
+@section Hooks
+@cindex mode hooks
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@c The node name is "CC Hooks" rather than "Hooks" because of a bug in
+@c some older versions of Info, e.g. the info.el in GNU Emacs 21.3.
+@c If you go to "Config Basics" and hit <CR> on the xref to "CC
+@c Hooks" the function Info-follow-reference searches for "*Note: CC
+@c Hooks" from the beginning of the page. If this node were instead
+@c named "Hooks", that search would spuriously find "*Note:
+@c Hooks(elisp)" and go to the wrong node.
+
+@ccmode{} provides several hooks that you can use to customize the
+mode for your coding style. The main hook is
+@code{c-mode-common-hook}; typically, you'll put the bulk of your
+customizations here. In addition, each language mode has its own
+hook, allowing you to fine tune your settings individually for the
+different @ccmode{} languages, and there is a package initialization
+hook. Finally, there is @code{c-special-indent-hook}, which enables
+you to solve anomalous indentation problems. It is described in
+@ref{Other Indentation}, not here. All these hooks adhere to the
+standard Emacs conventions.
+
+When you open a buffer, @ccmode{} first initializes it with the
+currently active style (@pxref{Styles}). Then it calls
+@code{c-mode-common-hook}, and finally it calls the language-specific
+hook. Thus, any style settings done in these hooks will override
+those set by @code{c-default-style}.
+
+@defvar c-initialization-hook
+@vindex initialization-hook (c-)
+Hook run only once per Emacs session, when @ccmode{} is initialized.
+This is a good place to change key bindings (or add new ones) in any
+of the @ccmode{} key maps. @xref{Sample .emacs File}.
+@end defvar
-@findex c-backward-into-nomenclature
-@findex backward-into-nomenclature (c-)
-@item @kbd{M-x c-backward-into-nomenclature}
-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.
+@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
+
+Although these hooks are variables defined in @ccmode{}, you can give
+them values before @ccmode{}'s code is loaded - indeed, this is the
+only way to use @code{c-initialization-hook}. Their values aren't
+overwritten when @ccmode{} gets loaded.
-@end table
+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 Other Commands, , Movement Commands, Commands
+@node Style Variables, Styles, CC Hooks, Config Basics
@comment node-name, next, previous, up
-@section Other Commands
+@section Style Variables
+@cindex styles
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@ccmode{} contains a few other useful commands:
+@cindex style variables
+The variables that @ccmode{}'s style system control are called
+@dfn{style variables}. Note that style variables are ordinary Lisp
+variables, which the style system initializes; you can change their
+values at any time (e.g. in a hook function). The style system can
+also also set other variables, to some extent. @xref{Styles}.
-@table @asis
+@dfn{Style variables} are handled specially in several ways:
-@kindex C-c :
-@findex c-scope-operator
-@findex scope-operator (c-)
-@item @kbd{C-c :} (@code{c-scope-operator})
-In C++, it is also sometimes desirable to insert the double-colon scope
-operator without performing the electric behavior of colon insertion.
-@kbd{C-c :} does just this.
+@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.
-@kindex C-c C-\
-@findex c-backslash-region
-@findex backslash-region (c-)
-@item @kbd{C-c C-\} (@code{c-backslash-region})
-This function is handy when editing macros split over several lines by
-ending each line with a backslash. It inserts and aligns, or deletes
-these end-of-line backslashes in the current region.
+@item
+@vindex c-old-style-variable-behavior
+@vindex old-style-variable-behavior (c-)
+The default global binding of any style variable (with two exceptions
+- see below) is the special symbol @code{set-from-style}. When the
+style system initializes a buffer-local copy of a style variable for a
+@ccmode{} buffer, if its global binding is still that symbol then it
+will be set from the current style. Otherwise it will retain its
+global default@footnote{This 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 non-@code{nil}.}. This
+``otherwise'' happens, for example, when you've set the variable with
+@code{setq} at the top level of your @file{.emacs} (@pxref{Config
+Basics}).
-@vindex c-backslash-column
-@vindex backslash-column (c-)
-With no prefix argument, it inserts any missing backslashes and aligns
-them to the column specified by the @code{c-backslash-column} style
-variable. With a prefix argument, it deletes any backslashes.
+@item
+The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is
+an association list with an element for each syntactic symbol. It's
+handled a little differently from the other style variables. It's
+default global binding is the empty list @code{nil}, rather than
+@code{set-from-style}. Before the style system is initialized, you
+can add individual elements to @code{c-offsets-alist} by calling
+@code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set
+other style variables with @code{setq}. Those elements will then
+prevail when the style system later initializes a buffer-local copy of
+@code{c-offsets-alist}.
-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.
+@item
+The style variable @code{c-special-indent-hook} is also handled in a
+special way. Styles can only add functions to this hook, not remove
+them, so any global settings you put on it are always
+preserved@footnote{This did not change in version 5.26.}. The value
+you give this variable in a style definition can be either a function
+or a list of functions.
-@end table
+@item
+The global bindings of the style variables get captured in the special
+@code{user} style when the style system is first initialized.
+@xref{Built-in Styles}, for details.
+@end itemize
+The style variables are:@*
+@code{c-indent-comment-alist},
+@code{c-indent-comments-syntactically-p} (@pxref{Indentation
+Commands});@*
+@code{c-doc-comment-style} (@pxref{Doc Comments});@*
+@code{c-block-comment-prefix}, @code{c-comment-prefix-regexp}
+(@pxref{Custom Filling and Breaking});@*
+@code{c-hanging-braces-alist} (@pxref{Hanging Braces});@*
+@code{c-hanging-colons-alist} (@pxref{Hanging Colons});@*
+@code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and
+Commas});@*
+@code{c-cleanup-list} (@pxref{Clean-ups});@*
+@code{c-basic-offset} (@pxref{Customizing Indentation});@*
+@code{c-offsets-alist} (@pxref{c-offsets-alist});@*
+@code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@*
+@code{c-special-indent-hook}, @code{c-label-minimum-indentation}
+(@pxref{Other Indentation});@*
+@code{c-backslash-column}, @code{c-backslash-max-column}
+(@pxref{Custom Macros}).
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Customizing Indentation, Syntactic Symbols, Commands, Top
+@node Styles, , Style Variables, Config Basics
@comment node-name, next, previous, up
-@chapter Customizing Indentation
-@cindex customizing indentation
+@section Styles
+@cindex styles
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@vindex c-offsets-alist
-@vindex offsets-alist (c-)
-The style variable @code{c-offsets-alist} 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 pre-defined 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 interface@footnote{Available 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.
+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.
-@kindex C-c C-o
-@findex c-set-offset
-@findex set-offset (c-)
-You can use the command @kbd{C-c C-o} (@code{c-set-offset}) as the way
-to set offsets, both interactively and from your mode
-hook@footnote{Obviously, you use the key binding interactively, and the
-function call programmatically!}.
+@menu
+* Built-in Styles::
+* Choosing a Style::
+* Adding Styles::
+* File Styles::
+@end menu
-@vindex c-basic-offset
-@vindex basic-offset (c-)
-The offset associated with any particular syntactic symbol can be any of
-an integer, a function or lambda expression, a variable name, a vector,
-a list, or one of the following symbols: @code{+}, @code{-}, @code{++},
-@code{--}, @code{*}, or @code{/}.
-
-Those last special symbols describe an offset in multiples of the value
-of the style variable @code{c-basic-offset}. By defining a style's
-indentation in terms of this fundamental variable, you can change the
-amount of whitespace given to an indentation level while maintaining the
-same basic shape of your code. Here are the values that the special
-symbols correspond to:
-@table @code
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Built-in Styles, Choosing a Style, Styles, Styles
+@comment node-name, next, previous, up
+@subsection Built-in Styles
+@cindex styles, built-in
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@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
+If you're lucky, one of @ccmode{}'s built-in styles might be just
+what you're looking for. These are:
-@end table
+@table @code
+@item gnu
+@cindex GNU style
+Coding style blessed by the Free Software Foundation
+for C code in GNU programs.
-@cindex indentation functions
+@item k&r
+@cindex K&R style
+The classic Kernighan and Ritchie style for C code.
-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.
+@item bsd
+@cindex BSD style
+Also known as ``Allman style'' after Eric Allman.
-If the offset is a vector, its first element sets the absolute
-indentation column, which will override any relative indentation.
-
-@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 non-@code{nil} value succeeds and the evaluation stops. If
-none of the list elements return a non-@code{nil} value, then an offset
-of 0 (zero) is used@footnote{There is however a variable
-@code{c-strict-syntax-p} that, when set to non-@code{nil}, will cause an
-error to be 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 so@footnote{You 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
+@item whitesmith
+@cindex Whitesmith style
+Popularized by the examples that came with Whitesmiths C, an early
+commercial C compiler.
-@noindent
-This would change
-@example
-@group
+@item stroustrup
+@cindex Stroustrup style
+The classic Stroustrup style for C++ code.
-int add( int val, int incr, int doit )
-@{
- if( doit )
- @{
- return( val + incr );
- @}
- return( val );
-@}
+@item ellemtel
+@cindex Ellemtel style
+Popular C++ coding standards as defined by ``Programming in C++, Rules
+and Recommendations,'' Erik Nyquist and Mats Henricson,
+Ellemtel@footnote{This document is available at
+@uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
+places.}.
+@c N.B. This URL was still valid at 2005/8/28 (ACM).
-@end group
-@end example
-@noindent
-to
-@example
-@group
+@item linux
+@cindex Linux style
+C coding standard for Linux (the kernel).
-int add( int val, int incr, int doit )
-@{
- if( doit )
- @{
- return( val + incr );
- @}
- return( val );
-@}
+@item python
+@cindex Python style
+C coding standard for Python extension modules@footnote{Python is a
+high level scripting language with a C/C++ foreign function interface.
+For more information, see @uref{http://www.python.org/}.}.
-@end group
-@end example
+@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}.
-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.
+@item awk
+@cindex AWK style
+The style for editing AWK code. Note that the default value for
+@code{c-default-style} installs this style when you enter
+@code{awk-mode}.
-@menu
-* Interactive Customization::
-* Permanent Customization::
-* Hooks::
-* Styles::
-* Advanced Customizations::
-@end menu
+@item user
+@cindex User style
+This is a special style created by you. It consists of the factory
+defaults for all the style variables as modified by the customizations
+you do either with the Customization interface or by writing
+@code{setq}s and @code{c-set-offset}s at the top level of your
+@file{.emacs} file (@pxref{Config Basics}). The style system creates
+this style as part of its initialization and doesn't modify it
+afterwards.
+@end table
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Interactive Customization, Permanent Customization, , Customizing Indentation
+@node Choosing a Style, Adding Styles, Built-in Styles, Styles
@comment node-name, next, previous, up
-@section Interactive Customization
-@cindex interactive customization
+@subsection Choosing a Style
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-As an example of how to customize indentation, let's change the
-style of this example@footnote{In this an subsequent examples, the
-original code is formatted using the @samp{gnu} style unless otherwise
-indicated. @xref{Styles}.}:
-@example
-@group
+Use @kbd{C-c .} to choose a style interactively:
-1: int add( int val, int incr, int doit )
-2: @{
-3: if( doit )
-4: @{
-5: return( val + incr );
-6: @}
-7: return( val );
-8: @}
+@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:
-@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
+@kbd{C-c . @var{style-name} @key{RET}}
@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
+You can use the @key{TAB} in the normal way to do completion on the
+style name. Note that all style names are case insensitive, even the
+ones you define yourself.
-@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!
+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{Indentation Commands} and @ref{Filling and Breaking}.
+@end deffn
-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}.
+The default style in all newly created buffers is @code{gnu}, except
+in Java and AWK modes where it's @code{java} and @code{awk}.
-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
+Remember that if you set a style variable with the Customization
+interface or at the top level of your @file{.emacs} file before the
+style system is initialised (@pxref{Config Basics}), this setting will
+override the one that the style system would have given the variable.
-1: int add( int val, int incr, int doit )
-2: @{
-3: if( doit )
-4: @{
-5: return( val + incr );
-6: @}
-7: return( val );
-8: @}
+@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:
-@end group
-@end example
+@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.
-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 re-indent and see if any following lines need further
-adjustments.
+@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.
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Permanent Customization, Hooks, Interactive Customization, Customizing Indentation
-@comment node-name, next, previous, up
-@section Permanent Customization
-@cindex permanent customization
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@item
+If @samp{other} is not found then the @samp{gnu} style is used.
+@end enumerate
-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.
+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}.
-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 the setting of @code{substatement-open} permanent, add this
-to the @file{.emacs} file:
-@example
-@group
+The standard value of @code{c-default-style} is @w{@code{((java-mode
+. "java") (awk-mode . "awk") (other . "gnu"))}}.
+@end defopt
-(require 'cc-mode)
-(c-set-offset 'substatement-open 0)
+@defvar c-indentation-style
+@vindex indentation-style (c-)
+This variable always contains the buffer's current style name, as a
+string.
+@end defvar
-@end group
-@end example
-The @code{require} line is only needed once in the beginning to make
-sure @ccmode{} is loaded so that the @code{c-set-offset} function is
-defined.
-
-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-basic-offset}, 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, global variable settings isn't enough. For that you can
-use the language hooks, see @ref{Hooks}, and/or the style system, see
-@ref{Styles}.
-
-@vindex c-style-variables-are-local-p
-@vindex style-variables-are-local-p (c-)
-By default, all style variables are global, so that every buffer will
-share the same style settings. This is fine if you primarily edit one
-style of code, but if you edit several languages and want to use
-different styles for them, you need finer control by making the style
-variables buffer local. The recommended way to do this is to set the
-variable @code{c-style-variables-are-local-p} to @code{t}. The
-variables will be made buffer local when @ccmode{} is activated in a
-buffer for the first time in the Emacs session. Note that once the
-style variables are made buffer local, they cannot be made global again,
-without restarting Emacs.
-
-
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Hooks, Styles, Permanent Customization, Customizing Indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Adding Styles, File Styles, Choosing a Style, Styles
@comment node-name, next, previous, up
-@section Hooks
-@cindex hooks
+@subsection Adding and Amending Styles
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@vindex c-mode-common-hook
-@vindex mode-common-hook (c-)
-@vindex c-mode-hook
-@vindex c++-mode-hook
-@vindex objc-mode-hook
-@vindex java-mode-hook
-@vindex idl-mode-hook
-@vindex pike-mode-hook
-@vindex c-initialization-hook
-@vindex initialization-hook (c-)
-@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:
+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}. You can see an example of a style
+definition in @ref{Sample .emacs File}.
+
+@cindex style definition
+@c @defvr {List} style definition
+@table @asis
+@item Structure of a Style Definition List
+([@var{base-style}] [(@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 the table
+of factory default values@footnote{This table is stored internally in
+the variable c-fallback-style.} 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
+activated.@footnote{Note that if the variable has been given a value
+by the Customization interface or a @code{setq} at the top level of
+your @file{.emacs}, this value will override the one the style system
+tries to give it. @xref{Config Basics}.} 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.
+@c @end defvr
+
+Two variables are treated specially in the dotted pair list:
-@itemize @bullet
+@table @code
+@item c-offsets-alist
+The value is in turn a list of dotted pairs of the form
-@item
-@code{c-mode-hook} --- For C buffers only.
-@item
-@code{c++-mode-hook} --- For C++ buffers only.
-@item
-@code{objc-mode-hook} --- For Objective-C buffers only.
-@item
-@code{java-mode-hook} --- For Java buffers only.
-@item
-@code{idl-mode-hook} --- For CORBA IDL buffers only.
-@item
-@code{pike-mode-hook} --- For Pike buffers only.
-@item
-@code{c-mode-common-hook} --- Common across all languages.
-@item
-@code{c-initialization-hook} --- Hook run only once per Emacs session,
-when @ccmode{} is initialized.
+@example
+(@r{@var{syntactic-symbol}} . @r{@var{offset}})
+@end example
-@end itemize
+as described in @ref{c-offsets-alist}. 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.
-The language hooks get run as the last thing when you enter that
-language mode. The @code{c-mode-common-hook} is run by all supported
-modes @emph{before} the language specific hook, and thus can contain
-customizations that are common across all languages. Most of the
-examples in this section will assume you are using the common hook.
+@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
+@end table
-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}.
+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.
-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
-@group
+@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 non-@code{nil} then the new style is
+applied to the current buffer as well. The use of this facility is
+deprecated and it might be removed from @ccmode{} in a future release.
+You should use @code{c-set-style} instead.
-(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)
+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
-@end group
-@end example
+@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 Styles, Advanced Customizations, Hooks, Customizing Indentation
+@node File Styles, , Adding Styles, Styles
@comment node-name, next, previous, up
-@section Styles
-@cindex styles
+@subsection File Styles
+@cindex styles, file local
@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 global variables, i.e. they have the same
-value in all Emacs buffers. However, they can instead be made always
-buffer local by setting @code{c-style-variables-are-local-p} to
-non-@code{nil} before @ccmode{} is initialized.
-
-@vindex c-old-style-variable-behavior
-@vindex old-style-variable-behavior (c-)
-@item
-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 value@footnote{This 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 non-@code{nil}.}.
-
-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 preserved@footnote{This did not change
-in version 5.26.}.
+@cindex file local variables
-@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.
+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 (@pxref{File Variables,, Local Variables in Files, @emacsman{},
+@emacsmantitle{}}).
-@end itemize
+So far, you've only seen a functional interface for setting styles in
+@ccmode{}, and this can't be used here. @ccmode{} fills the gap by
+providing two variables for use in a file's local variable list.
+Don't use them anywhere else! These allow you to customize the style
+on a per-file basis:
-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-special-indent-hook},
-@code{c-label-minimum-indentation}, and
-@code{c-offsets-alist}.
+@defvar c-file-style
+@vindex file-style (c-)
+Set this variable to a style name string in the Local Variables list.
+From now on, when you visit the file, @ccmode{} will automatically set
+the file's style to this one using @code{c-set-style}.
+@end defvar
-@menu
-* Built-in Styles::
-* Adding Styles::
-* File Styles::
-@end menu
+@defvar c-file-offsets
+@vindex file-offsets (c-)
+Set this variable (in the Local Variables list) to an association list
+of the same format as @code{c-offsets-alist}. From now on, when you
+visit the file, @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})@footnote{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, even if
+@code{c-style-variables-are-local-p} is @code{nil}. Since this
+variable is virtually always non-@code{nil} anyhow, you're unlikely to
+notice this effect.}.
+
+If you set any variables, including style variables, by the file local
+variables mechanism, these settings take priority over all other
+settings, even those in your mode hooks (@pxref{CC Hooks}). If you
+use @code{c-file-style} or @code{c-file-offsets} and also explicitly
+set a style variable in a local variable block, the explicit setting
+will take priority.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Built-in Styles, Adding Styles, , Styles
+@node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top
@comment node-name, next, previous, up
-@subsection Built-in Styles
-@cindex built-in styles
+@chapter Customizing Filling and Line Breaking
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-If you're lucky, one of @ccmode{}'s built-in styles might be just
-what you're looking for. These include:
-
-@itemize @bullet
-@cindex GNU style
-@item
-@code{gnu} --- Coding style blessed by the Free Software Foundation
-for C code in GNU programs.
-
-@cindex K&R style
-@item
-@code{k&r} --- The classic Kernighan and Ritchie style for C code.
-
-@cindex BSD style
-@item
-@code{bsd} --- Also known as ``Allman style'' after Eric Allman.
+Since there's a lot of normal text in comments and string literals,
+@ccmode{} provides features to edit these like in text mode. It does
+this by hooking in on the different line breaking functions and tuning
+relevant variables as necessary.
-@cindex Whitesmith style
-@item
-@code{whitesmith} --- Popularized by the examples that came with
-Whitesmiths C, an early commercial C compiler.
+@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
+variables@footnote{@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.
-@cindex Stroustrup style
-@item
-@code{stroustrup} --- The classic Stroustrup style for C++ code.
+@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 variable is either the comment line
+prefix itself, or (more usually) an association list with different
+values for different languages. The symbol for the major mode is
+looked up in the alist to get the regexp for the language, and if it
+isn't found then the special symbol @samp{other} is looked up instead.
+
+When a comment line gets divided by @kbd{M-j} or the like, @ccmode{}
+inserts the comment line prefix from a neighbouring line at the start
+of the new line. The default value of c-comment-prefix-regexp is
+@samp{//+\\|\\**}, which matches C++ style line comments like
-@cindex Ellemtel style
-@item
-@code{ellemtel} --- Popular C++ coding standards as defined by
-``Programming in C++, Rules and Recommendations,'' Erik Nyquist and Mats
-Henricson, Ellemtel@footnote{This document is available at
-@uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
-places.}.
+@example
+// blah blah
+@end example
-@cindex Linux style
-@item
-@code{linux} --- C coding standard for Linux (the kernel).
+@noindent
+with two or more slashes in front of them, and the second and
+subsequent lines of C style block comments like
-@cindex Python style
-@item
-@code{python} --- C coding standard for Python extension
-modules@footnote{Python is a high level scripting language with a C/C++
-foreign function interface. For more information, see
-@uref{http://www.python.org/}.}.
+@example
+@group
+/*
+ * blah blah
+ */
+@end group
+@end example
-@cindex Java style
-@findex java-mode
-@item
-@code{java} --- 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}.
+@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. That's also the case if you modify
+@code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will
+already have set up these variables before calling the hook.
+@end defopt
+
+In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt
+the line prefix from the other lines in the comment.
-@cindex User style
-@item
-@code{user} --- 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.
+@vindex adaptive-fill-mode
+@cindex Adaptive Fill mode
+@ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU
+Emacs Manual}) 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:
-@end itemize
+@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
-@vindex c-default-style
-@vindex default-style (c-)
-The default style in all newly created buffers is @code{gnu}, but you
-can change this by setting variable @code{c-default-style}. 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 these settings.
-
-@code{c-default-style} takes either a style name string, or an
-association list of major mode symbols to style names. Thus you can
-control exactly which default style is used for which @ccmode{} language
-mode. Here are the rules:
-
-@vindex c-style-alist
-@vindex style-alist (c-)
-@vindex c-mode-common-hook
-@vindex mode-common-hook (c-)
-@enumerate
-@item
-When @code{c-default-style} is a string, it must be an existing style
-name as found in @code{c-style-alist}. This style is then used for all
-modes.
-
-@item
-When @code{c-default-style} is an association list, the current major
-mode is looked up to find a style name string. In this case, this style
-is always used exactly as specified and an error will occur if the named
-style does not exist.
+@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 package@footnote{It'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}.},
+@c 2005/11/22: The above is still believed to be the case.
+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}:
-@item
-If @code{c-default-style} is an association list, but the current major
-mode isn't found, then the special symbol @samp{other} is looked up. If
-this value is found, the associated style is used.
+@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
-@item
-If @samp{other} is not found, then the @samp{gnu} style is used.
+@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
+variable@footnote{In 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{*
+}@footnote{Actually, 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
-@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}.
+@example
+/* Got O(n^2) here, which is a Bad Thing. */
+@end example
-@end enumerate
+@noindent
+break into
-@findex c-set-style
-@findex set-style (c-)
-@kindex C-c .
-If you'd like to experiment with these built-in styles you can simply
-type the following in a @ccmode{} buffer:
@example
@group
-
-@kbd{C-c . @var{STYLE-NAME} RET}
-
+/* Got O(n^2) here, which
+ * is a Bad Thing. */
@end group
@end example
-@noindent
-@kbd{C-c .} runs the command @code{c-set-style}. Note that all style
-names are case insensitive, even the ones you define.
-
-Setting a style in this way does @emph{not} automatically re-indent your
-file. For commands that you can use to view the effect of your changes,
-see @ref{Commands}.
-
-@vindex c-indentation-style
-@vindex indentation-style (c-)
-Note that for BOCM compatibility, @samp{gnu} is the default style, and
-any non-style based customizations you make (i.e. in
-@code{c-mode-common-hook} in your @file{.emacs} file) will be based on
-@samp{gnu} style unless you set @code{c-default-style} or do a
-@code{c-set-style} as the first thing in your hook. The variable
-@code{c-indentation-style} always contains the buffer's current style
-name, as a string.
+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{Line-Up Functions}.
+@end defopt
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Adding Styles, File Styles, Built-in Styles, Styles
-@comment node-name, next, previous, up
-@subsection Adding Styles
-@cindex adding styles
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@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:
-@vindex c-style-alist
-@vindex style-alist (c-)
-@findex c-add-style
-@findex add-style (c-)
-If none of the built-in styles is appropriate, you'll probably want to
-add a new @dfn{style definition}. 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} that you can use to easily add new styles or change
-existing styles. This function takes two arguments, a @var{stylename}
-string, and an association list @var{description} of style
-customizations. If @var{stylename} is not already in
-@code{c-style-alist}, the new style is added, otherwise the style is
-changed to the new @var{description}.
-This function also takes an optional third argument, which if
-non-@code{nil}, automatically applies the new style to the current
-buffer.
-
-@comment TBD: The next paragraph is bogus. I really need to better
-@comment document adding styles, including setting up inherited styles.
+@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
-The sample @file{.emacs} file provides a concrete example of how a new
-style can be added and automatically set. @xref{Sample .emacs File}.
+By default, @code{c-ignore-auto-fill} is set to @code{(string cpp
+code)}, which means that when auto-fill mode is activated,
+auto-filling only occurs in comments. 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
+@vindex comment-multi-line
+If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,,
+@emacsman{}, @emacsmantitle{}} is non-@code{nil}, 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.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node File Styles, , Adding Styles, Styles
+@node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top
@comment node-name, next, previous, up
-@subsection File Styles
-@cindex file styles
+@chapter Customizing Auto-newlines
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@cindex local variables
-
-The Emacs manual describes how you can customize certain variables on a
-per-file basis by including a @dfn{Local Variable} block at the end of
-the file. So far, you've only seen a functional interface to @ccmode{}
-customization, which is highly inconvenient for use in a Local Variable
-block. @ccmode{} provides two variables that make it easier for you to
-customize your style on a per-file basis.
-
-@vindex c-file-style
-@vindex file-style (c-)
-@vindex c-file-offsets
-@vindex file-offsets (c-)
-
-The variable @code{c-file-style} can be set to a style name string.
-When the file is visited, @ccmode{} will automatically set the
-file's style to this style using @code{c-set-style}.
+@ccmode{} determines whether to insert auto-newlines in two basically
+different ways, depending on the character just typed:
-Another variable, @code{c-file-offsets}, 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}.
+@table @asis
+@item Braces and Colons
+@ccmode{} first determines the syntactic context of the brace or colon
+(@pxref{Syntactic Symbols}), then looks for a corresponding element in
+an alist. This element specifies where to put newlines - this is any
+combination of before and after the brace or colon. If no alist
+element is found, newlines are inserted both before and after a brace,
+but none are inserted around a colon. See @ref{Hanging Braces} and
+@ref{Hanging Colons}.
+
+@item Semicolons and Commas
+The variable @code{c-hanging-semi&comma-criteria} contains a list of
+functions which determine whether to insert a newline after a newly
+typed semicolon or comma. @xref{Hanging Semicolons and Commas}.
+@end table
-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.
+The names of these configuration variables contain @samp{hanging}
+because they let you @dfn{hang} the pertinent characters. A character
+which introduces a C construct is said to @dfn{hang on the right} when
+it appears at the end of a line after other code, being separated by a
+line break from the construct it introduces, like the opening brace in:
+@example
+@group
+while (i < MAX) @{
+ total += entry[i];
+ entry [i++] = 0;
+@}
+@end group
+@end example
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Advanced Customizations, , Styles, Customizing Indentation
-@comment node-name, next, previous, up
-@section Advanced Customizations
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@noindent
+A character @dfn{hangs on the left} when it appears at the start of
+the line after the construct it closes off, like the above closing
+brace.
-@vindex c-style-alist
-@vindex style-alist (c-)
-For most users, @ccmode{} will support their coding styles with
-very little need for more advanced customizations. Usually, one of the
-standard styles defined in @code{c-style-alist} will do the trick. At
-most, perhaps one of the syntactic symbol offsets will need to be
-tweaked slightly, or maybe @code{c-basic-offset} will need to be
-changed. However, some styles require a more flexible framework for
-customization, and one of the real strengths of @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.
+The next chapter, ``Clean-ups'', describes how to configure @ccmode{}
+to remove these automatically added newlines in certain specific
+circumstances. @xref{Clean-ups}.
@menu
-* Custom Indentation Functions::
-* Custom Brace and Colon Hanging::
-* Customizing Semi-colons and Commas::
-* Other Special Indentations::
+* Hanging Braces::
+* Hanging Colons::
+* Hanging Semicolons and Commas::
@end menu
+
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations
+@node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines
@comment node-name, next, previous, up
-@subsection Custom Indentation Functions
-@cindex custom indentation functions
+@section Hanging Braces
+@cindex hanging braces
@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: @}
+To specify which kinds of braces you want auto-newlines put around,
+you set the style variable @code{c-hanging-braces-alist}. Its
+structure and semantics are described in this section. Details of how
+to set it up, and its relationship to CC Mode's style system are given
+in @ref{Style Variables}.
-@end group
-@end example
+Say you wanted an auto-newline after (but not before) the following
+@samp{@{}:
-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 first
-stream operator on the first line of the statement. Here is sample
-lisp code implementing this:
@example
-@group
+if (foo < 17) @{
+@end example
-(defun c-lineup-streamop (langelem)
- ;; lineup stream operators
- (save-excursion
- (let* ((relpos (cdr langelem))
- (curcol (progn (goto-char relpos)
- (current-column))))
- (re-search-forward "<<\\|>>" (c-point 'eol) 'move)
- (goto-char (match-beginning 0))
- (- (current-column) curcol))))
+@noindent
+First you need to find the @dfn{syntactic context} of the brace---type
+a @key{RET} before the brace to get it on a line of its
+own@footnote{Also insert a @samp{\} at the end of the previous line if
+you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you
+something like:
-@end group
+@example
+((substatement-open 1061))
@end example
+
@noindent
-Indentation functions take a single argument, which is a syntactic
-component cons cell (@pxref{Syntactic Analysis}). The function returns
-an integer offset value that will be added to the running total
-indentation for the line. Note that what actually gets returned is the
-difference between the column that the first stream operator is on, and
-the column of the buffer relative position passed in the function's
-argument. Remember that @ccmode{} automatically adds in the column of
-the component's relative buffer position and we don't the column offset
-added in twice.
-
-The function should return @code{nil} if it's used in a situation where
-it doesn't want to do 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.
-
-@cindex stream-op syntactic symbol
-@findex c-lineup-streamop
-@findex lineup-streamop (c-)
-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 @code{c++-mode-hook}@footnote{It 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
+So here you need to put the entry @code{(substatement-open . (after))}
+into @code{c-hanging-braces-alist}.
-(c-set-offset 'stream-op 'c-lineup-streamop)
+If you don't want any auto-newlines for a particular syntactic symbol,
+put this into @code{c-hanging-braces-alist}:
+@example
+(brace-entry-open)
@end example
-Now the function looks like this after re-indenting (using @kbd{C-c
-C-q}):
-@example
-@group
+If some brace syntactic symbol is not in @code{c-hanging-brace-alist},
+its entry is taken by default as @code{(before after)}---insert a
+newline both before and after the brace. In place of a
+``before/after'' list you can specify a function in this alist---this
+is useful when the auto newlines depend on the code around the brace.
-1: void main(int argc, char**)
-2: @{
-3: cout << "There were "
-4: << argc
-5: << " arguments passed to the program"
-6: << endl;
-7: @}
+@defopt c-hanging-braces-alist
+@vindex hanging-braces-alist (c-)
-@end group
+This variable is an association list which maps syntactic symbols to
+lists of places to insert a newline. @xref{Association
+Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the
+syntactic symbol, the associated value is either @code{nil}, a list,
+or a function.
+
+@table @asis
+@item The Key - the syntactic symbol
+The syntactic symbols that are useful as keys in 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. Elements with any other value as a key get
+ignored.
+
+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 classes@footnote{The
+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{(@{}, @samp{@})},
+@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.
+
+@item The associated value - the ``ACTION'' list or function
+The value associated with each syntactic symbol in this association
+list is called an @var{action}, which can be either a list or a
+function which returns a list. @xref{Custom Braces}, for how to use
+a function as a brace hanging @var{action}.
+
+The list @var{action} (or the list returned by @var{action} when it's
+a function) contains some 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 hangs 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
-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.
+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 newlines
+are added neither before nor after the brace.
+@end table
+
+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)
+ (namespace-open after)
+ (module-open after)
+ (composition-open after)
+ (inexpr-class-open after)
+ (inexpr-class-close before))
+@end example
-@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}.
+@noindent which says that @code{brace-list-open},
+@code{brace-entry-open} and @code{statement-cont}@footnote{Brace 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
+@menu
+* Custom Braces::
+@end menu
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations
+@node Custom Braces, , Hanging Braces, Hanging Braces
@comment node-name, next, previous, up
-@subsection Custom Brace and Colon Hanging
+@subsection Custom Brace Hanging
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@vindex c-hanging-braces-alist
@vindex hanging-braces-alist (c-)
+@cindex action functions
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 customizing 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.
+@ccmode{} with the lisp equivalent of callback functions. Remember
+that @var{action}s are usually a list containing some combination of
+the symbols @code{before} and @code{after} (@pxref{Hanging Braces}).
+For more flexibility, you can instead specify brace ``hanginess'' by
+giving a synctactic symbol an @dfn{action function} in
+@code{c-hanging-braces-alist}; this function determines the
+``hanginess'' of a brace, usually by looking at the code near it.
+
+@cindex customization, brace hanging
+An action function is called with two arguments: the syntactic symbol
+for the brace (e.g. @code{substatement-open}), and the buffer position
+where the brace has been inserted. Point is undefined on entry to an
+action function, but the function must preserve it (e.g. by using
+@code{save-excursion}). The return value should be a list containing
+some combination of @code{before} and @code{after}, including neither
+of them (i.e. @code{nil}).
+
+@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.
+This might be, for example, @samp{((block-close 73))}. Don't ever
+give @code{c-syntactic-context} a value yourself---this would disrupt
+the proper functioning of @ccmode{}.
+
+This variable is also bound in three other circumstances:
+(i)@tie{}when calling a c-hanging-semi&comma-criteria function
+(@pxref{Hanging Semicolons and Commas}; (ii)@tie{}when calling a
+line-up function (@pxref{Custom Line-Up}; (iii)@tie{}when calling a
+c-special-indent-hook function (@pxref{Other Indentation}).
+@end defvar
As an example, @ccmode{} itself uses this feature to dynamically
determine the hanginess of braces which close ``do-while''
constructs:
-@example
-@group
+@example
void do_list( int count, char** atleast_one_string )
@{
int i=0;
i++;
@} while( i < count );
@}
-
-@end group
@end example
-@findex c-snug-do-while
-@findex snug-do-while (c-)
@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
+associate the @code{block-close} symbol with the @var{action} function
@code{c-snug-do-while}:
-@example
+@example
(defun c-snug-do-while (syntax pos)
- "Dynamically calculate brace hanginess for do-while statements.
-Using this function, `while' clauses that end a `do-while' block will
-remain on the same line as the brace that closes that block.
-
-See `c-hanging-braces-alist' for how to utilize this function as an
-ACTION associated with `block-close' syntax."
+ "Dynamically calculate brace hanginess for do-while statements."
(save-excursion
(let (langelem)
(if (and (eq syntax 'block-close)
(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.
-@vindex c-syntactic-context
-@vindex syntactic-context (c-)
-During the call to the brace hanging @var{ACTION} function, the variable
-@code{c-syntactic-context} is bound to the full syntactic analysis list.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines
+@comment node-name, next, previous, up
+@section Hanging Colons
+@cindex hanging colons
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex customization, colon hanging
+@vindex c-hanging-colons-alist
+@vindex hanging-colons-alist (c-)
+
+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} - When a colon is typed, @ccmode
+determines its syntactic context, looks this up in the alist
+@code{c-changing-colons-alist} and inserts up to two newlines
+accordingly. Here, however, If @ccmode fails to find an entry for a
+syntactic symbol in the alist, no newlines are inserted around the
+newly typed colon.
+
+@defopt c-hanging-colons-alist
+@vindex hanging-colons-alist (c-)
-@cindex customizing colon hanging
-@vindex c-hanging-colon-alist
-@vindex hanging-colon-alist (c-)
-Note that for symmetry, colon hanginess should be customizable by
-allowing function symbols as @var{ACTION}s on the
-@code{c-hanging-colon-alist} style variable. Since no use has actually
-been found for this feature, it isn't currently implemented!
+@table @asis
+@item The Key - the syntactic symbol
+The syntactic symbols appropriate as keys in this association list
+are: @code{case-label}, @code{label}, @code{access-label},
+@code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic
+Symbols}. Elements with any other value as a key get ignored.
+
+@item The associate value - the ``ACTION'' list
+The @var{action} here is simply a list containing a combination of the
+symbols @code{before} and @code{after}. Unlike in
+@code{c-hanging-braces-alist}, functions as @var{actions} are not
+supported - there doesn't seem to be any need for them.
+@end table
+@end defopt
+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.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations
+@node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines
@comment node-name, next, previous, up
-@subsection Customizing Semi-colons and Commas
-@cindex customizing semi-colons and commas
+@section Hanging Semicolons and Commas
+@cindex hanging semicolons
+@cindex hanging commas
+@cindex customization, semicolon newlines
+@cindex customization, comma newlines
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@vindex c-hanging-semi&comma-criteria
+@defopt c-hanging-semi&comma-criteria
@vindex hanging-semi&comma-criteria (c-)
-You can also customize the insertion of newlines after semi-colons and
-commas, when the auto-newline minor mode is enabled (@pxref{Minor
-Modes}). This is controlled by the style variable
-@code{c-hanging-semi&comma-criteria}, which contains a list of functions
-that are called in the order they appear. Each function is called with
-zero arguments, and is expected to return one of the following values:
-
-@itemize @bullet
-@item
-non-@code{nil} --- A newline is inserted, and no more functions from the
-list are called.
-
-@item
-@code{stop} --- No more functions from the list are called, but no
-newline is inserted.
+This style variable takes a list of functions; these get called when
+you type a semicolon or comma. The functions are called in order
+without arguments. When these functions are entered, point is just
+after the newly inserted @samp{;} or @samp{,} and they must preserve
+point (e.g., by using @code{save-excursion}). During the call, the
+variable @code{c-syntactic-context} is bound to the syntactic context
+of the current line@footnote{This was first introduced in @ccmode{}
+5.31.} @pxref{Custom Braces}. These functions don't insert newlines
+themselves, rather they direct @ccmode{} whether or not to do so.
+They should return one of the following values:
-@item
-@code{nil} --- No determination is made, and the next function in the
-list is called.
+@table @code
+@item t
+A newline is to be inserted after the @samp{;} or @samp{,}, and no
+more functions from the list are to be called.
+@item stop
+No more functions from the list are to be called, and no newline is to
+be inserted.
+@item nil
+No determination has been made, and the next function in the list is
+to be called.
+@end table
-@end itemize
+Note that auto-newlines are never inserted @emph{before} a semicolon
+or comma. If every function in the list is called without a
+determination being made, then no newline is added.
-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
-semi-colons which do not appear inside parenthesis lists (i.e. those
-that separate @code{for}-clause statements).
+In AWK mode, this variable is set by default to @code{nil}. In the
+other modes, the default value is a list containing a single function,
+@code{c-semi&comma-inside-parenlist}. This inserts newlines after all
+semicolons, apart from those separating @code{for}-clause statements.
+@end defopt
-@findex c-semi&comma-no-newlines-before-nonblanks
+@defun c-semi&comma-no-newlines-before-nonblanks
@findex semi&comma-no-newlines-before-nonblanks (c-)
-Here's an example of a criteria function, provided by @ccmode{}, that
-will prevent newlines from being inserted after semicolons when there is
-a non-blank following line. Otherwise, it makes no determination. To
-use, add this to the front of the @code{c-hanging-semi&comma-criteria}
-list.
+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
-@group
-
(defun c-semi&comma-no-newlines-before-nonblanks ()
(save-excursion
(if (and (eq last-command-char ?\;)
(not (looking-at "^[ \t]*$")))
'stop
nil)))
-
-@end group
@end example
+@end defun
-@findex c-semi&comma-inside-parenlist
-@findex c-semi&comma-no-newlines-for-oneline-inliners
+@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}
@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
-(i.e. in C++ or Java).
+(e.g. in C++ or Java).
+@end defun
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations
+@node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top
@comment node-name, next, previous, up
-@subsection Other Special Indentations
+@chapter Clean-ups
+@cindex clean-ups
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@vindex 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 the style variable
-@code{c-label-minimum-indentation}. The default value for this variable
-is 1.
+@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add)
+whitespace in specific circumstances and are complementary to colon
+and brace hanging. You enable a clean-up by adding its symbol into
+@code{c-cleanup-list}.
-@vindex c-special-indent-hook
-@vindex special-indent-hook (c-)
-One other customization variable is available in @ccmode{}: The style
-variable @code{c-special-indent-hook}. This 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 however, 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.
+On the surface, it would seem that clean-ups overlap the functionality
+provided by the @code{c-hanging-*-alist} variables. Clean-ups,
+however, are used to adjust code ``after-the-fact'', i.e. to adjust
+the whitespace in constructs later than when they were typed.
+
+Most of the clean-ups remove automatically inserted newlines, and are
+only active when auto-newline minor mode is turned on. Others will
+work all the time. Note that clean-ups are only performed when there
+is nothing but whitespace appearing between the individual components
+of the construct, and (apart from @code{comment-close-slash}) when the
+construct does not occur within a literal (@pxref{Auto-newlines}).
+
+@defopt c-cleanup-list
+@vindex cleanup-list (c-)
+@cindex literal
-@kindex M-;
-@findex indent-for-comment
-@vindex c-indent-comments-syntactically-p
-@vindex indent-comments-syntactically-p (c-)
-@vindex comment-column
-Normally, the standard Emacs command @kbd{M-;}
-(@code{indent-for-comment}) will indent comment only lines to
-@code{comment-column}. Some users however, prefer that @kbd{M-;} act
-just like @kbd{TAB} for purposes of indenting comment-only lines;
-i.e. they want the comments to always indent as they would for normal
-code, regardless of whether @kbd{TAB} or @kbd{M-;} were used. This
-behavior is controlled by the variable
-@code{c-indent-comments-syntactically-p}. When @code{nil} (the
-default), @kbd{M-;} indents comment-only lines to @code{comment-column},
-otherwise, they are indented just as they would be if @kbd{TAB} were
-typed.
+You 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.
+@end defopt
-Note that this has no effect for comment lines that are inserted with
-@kbd{M-;} at the end of regular code lines. These comments will always
-start at @code{comment-column}.
+These are the clean-ups that are only active when electric and
+auto-newline minor modes are enabled:
+@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 @samp{@} else @{} constructs by placing the entire construct on
+a single line. Clean up occurs when the open brace after the
+@samp{else} is typed. So for example, this:
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Syntactic Symbols, Indentation Functions, Customizing Indentation, Top
-@comment node-name, next, previous, up
-@chapter Syntactic Symbols
-@cindex syntactic symbols
-@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@example
+@group
+void spam(int i)
+@{
+ if( i==7 ) @{
+ dosomething();
+ @}
+ else
+ @{
+@end group
+@end example
-@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.
+@noindent
+appears like this after the last open brace is typed:
-@table @code
-@item string
-Inside a multi-line string.
-@item c
-Inside a multi-line 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.
-@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 case-label
-A @code{case} or @code{default} label.
-@item access-label
-C++ access control label.
-@item label
-Any non-special C label.
-@item do-while-closure
-The @code{while} line that ends a @code{do}-@code{while} construct.
-@item else-clause
-The @code{else} line of an @code{if}-@code{else} construct.
-@item catch-clause
-The @code{catch} or @code{finally} (in Java) line of a
-@code{try}-@code{catch} 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 C preprocessor macro definition.
-@item cpp-macro-cont
-Subsequent lines of a multi-line C preprocessor macro definition.
-@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 external language block.
-@item extern-lang-close
-Brace that closes an external language block.
-@item inextern-lang
-Analogous to @code{inclass} syntactic symbol, but used inside external
-language blocks (e.g. @code{extern "C" @{}).
-@item namespace-open
-Brace that opens a C++ namespace block.
-@item namespace-close
-Brace that closes a C++ namespace block.
-@item innamespace
-Analogous to @code{inextern-lang} syntactic symbol, but used inside C++
-namespace 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 extension of this is
-recognized. It's also used for the special functions that takes 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
-
-@cindex -open syntactic symbols
-@cindex -close syntactic 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.
-
-@cindex -intro syntactic symbols
-@cindex -cont syntactic symbols
-@cindex -block-intro syntactic 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
@group
+void spam(int i)
+@{
+ if( i==7 ) @{
+ dosomething();
+ @} else @{
+@end group
+@end 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: @}
+@item brace-elseif-brace
+Similar to the @code{brace-else-brace} clean-up, but this cleans up
+@samp{@} else if (...) @{} constructs. For example:
+@example
+@group
+void spam(int i)
+@{
+ if( i==7 ) @{
+ dosomething();
+ @}
+ else if( i==3 )
+ @{
@end group
@end example
-@cindex topmost-intro syntactic symbol
-@cindex topmost-intro-cont syntactic symbol
-@cindex defun-open syntactic symbol
-@cindex defun-close syntactic symbol
-@cindex defun-block-intro syntactic symbol
-Line 1 shows a @code{topmost-intro} since it is the first line that
-introduces a top-level construct. Line 2 is a continuation of the
-top-level construct introduction so it has the syntax
-@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.
-
-@cindex statement syntactic symbol
-@cindex statement-cont syntactic symbol
-Lines 5, 6, and 7 are all given @code{statement} syntax since there
-isn't much special about them. Note however that line 8 is given
-@code{statement-cont} syntax since it continues the statement begun
-on the previous line.
+@noindent
+appears like this after the last open parenthesis is typed:
-Here's another example, which illustrates some C++ class syntactic
-symbols:
@example
@group
+void spam(int i)
+@{
+ if( i==7 ) @{
+ dosomething();
+ @} else if(
+@end group
+@end 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: @}
+@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
-@cindex class-open syntactic symbol
-@cindex class-close syntactic symbol
-As in the previous example, line 1 has the @code{topmost-intro} syntax.
-Here however, the brace that opens a C++ class definition on line 4 is
-assigned the @code{class-open} syntax. Note that in C++, classes,
-structs, and unions are essentially equivalent syntactically (and are
-very similar semantically), so replacing the @code{class} keyword in the
-example above with @code{struct} or @code{union} would still result in a
-syntax of @code{class-open} for line 4 @footnote{This is the case even
-for C and Objective-C. For consistency, structs in all supported
-languages are syntactically equivalent to classes. Note however that
-the keyword @code{class} is meaningless in C and Objective-C.}.
-Similarly, line 18 is assigned @code{class-close} syntax.
-
-@cindex inher-intro syntactic symbol
-@cindex inher-cont syntactic symbol
-Line 2 introduces the inheritance list for the class so it is assigned
-the @code{inher-intro} syntax, and line 3, which continues the
-inheritance list is given @code{inher-cont} syntax.
+@item brace-catch-brace
+Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch
+(...) @{} in C++ and Java mode.
-@cindex access-label syntactic symbol
-@cindex inclass syntactic symbol
-Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
+@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
-
-@code{((inclass . 58) (access-label . 67))}
-
+class Spam
+@{
+@}
@end group
@end example
@noindent
-The primary syntactic symbol for this line is @code{access-label} as
-this a label keyword that specifies access protection in C++. However,
-because this line is also a top-level construct inside a class
-definition, the analysis actually shows two syntactic symbols. The
-other syntactic symbol assigned to this line is @code{inclass}.
-Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
-syntax:
+is transformed into this when the close brace is typed:
@example
@group
-
-@code{((inclass . 58) (topmost-intro . 60))}
-
+class Spam
+@{@}
@end group
@end example
-@cindex member-init-intro syntactic symbol
-@cindex member-init-cont syntactic symbol
-Line 7 introduces a C++ member initialization list and as such is given
-@code{member-init-intro} syntax. Note that in this case it is
-@emph{not} assigned @code{inclass} since this is not considered a
-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
-@cindex inline-open syntactic symbol
-@cindex inline-close syntactic symbol
-Line 11's analysis is a bit more complicated:
+@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
-@code{((inclass . 58) (inline-open))}
+@noindent
+is transformed into this when the semicolon is typed:
+@example
+@group
+class Spam
+@{
+...
+@};
@end group
@end example
-This line is assigned a syntax of both @code{inline-open} and
-@code{inclass} because it opens an @dfn{in-class} C++ inline method
-definition. This is distinct from, but related to, the C++ notion of an
-inline function in that its definition occurs inside an enclosing class
-definition, which in C++ implies that the function should be inlined.
-If though, 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:
+@item list-close-comma
+Clean up commas following braces in array and aggregate initializers.
+Clean up occurs when the comma is typed. The space before the comma
+is zapped just like the space before the semicolon in
+@code{defun-close-semi}.
+
+@item scope-operator
+Clean up double colons which might designate a C++ scope operator split
+across multiple lines@footnote{Certain C++ constructs introduce
+ambiguous situations, so @code{scope-operator} clean-ups might 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.
+
+@item one-liner-defun
+Clean up a single line of code enclosed by defun braces by removing
+the whitespace before and after the code. The clean-up happens when
+the closing brace is typed. If the variable
+@code{c-max-one-liner-length} is set, the cleanup is only done if the
+resulting line would be no longer than the value of that variable.
+
+For example, consider this AWK code:
+
@example
@group
-
-class Bass
- : public Guitar,
- public Amplifiable
-@{
-public:
- Bass();
+BEGIN @{
+ FS = "\t" # use <TAB> as a field separator
@}
+@end group
+@end example
-inline
-Bass::Bass()
- : eString( new BassString( 0.105 )),
- aString( new BassString( 0.085 )),
- dString( new BassString( 0.065 )),
- gString( new BassString( 0.045 ))
-@{
- eString.tune( 'E' );
- aString.tune( 'A' );
- dString.tune( 'D' );
- gString.tune( 'G' );
-@}
+@noindent
+It gets compacted to the following when the closing brace is typed:
+@example
+@group
+BEGIN @{FS = "\t"@} # use <TAB> as a field separator
@end group
@end example
-@cindex friend syntactic symbol
-Returning to the previous example, line 16 is given @code{inline-close}
-syntax, while line 12 is given @code{defun-block-open} syntax, and lines
-13 through 15 are all given @code{statement} syntax. Line 17 is
-interesting in that its syntactic analysis list contains three
-elements:
+@defopt c-max-one-liner-length
+@vindex max-one-liner-length (c-)
+The maximum length of the resulting line for which the clean-up
+@code{one-liner-defun} will be triggered. This length is that of the entire
+line, including any leading whitespace and any trailing comment. Its
+default value is 80. If the value is zero or @code{nil}, no limit
+applies.
+@end defopt
+@end table
-@example
+The following clean-ups are always active when they occur on
+@code{c-cleanup-list}, regardless of whether Electric minor mode or
+Auto-newline minor mode are enabled:
+
+@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@tie{}(SIGINT,
+SIG_IGN)} and @samp{abort@tie{}()}. Clean up occurs when the opening
+parenthesis is typed. This clean-up should never be active in AWK
+Mode, since such a space is syntactically invalid for user defined
+functions.
+
+@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.
+
+@item comment-close-slash
+When inside a block comment, terminate the comment when you type a
+slash at the beginning of a line (i.e. immediately after the comment
+prefix). This clean-up removes whitespace preceding the slash and if
+needed, inserts a star to complete the token @samp{*/}.
+@end table
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top
+@comment node-name, next, previous, up
+@chapter Indentation Engine Basics
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This chapter will briefly cover how @ccmode{} indents lines of code.
+It is helpful 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}.
+
+@ccmode{} has an indentation engine that provides a flexible and
+general mechanism for customizing indentation. When @ccmode{} indents
+a line of code, it separates its calculations into two steps:
+
+@enumerate
+@item
+@cindex syntactic symbol
+@cindex anchor position
+It analyzes the line to determine its @dfn{syntactic symbol(s)} (the
+kind of language construct it's looking at) and its @dfn{anchor
+position} (the position earlier in the file that @ccmode{} will indent
+the line relative to). The anchor position might be the location of
+an opening brace in the previous line, for example. @xref{Syntactic
+Analysis}.
+@item
+@cindex offsets
+@cindex indentation offset specifications
+It looks up the syntactic symbol(s) in the configuration to get the
+corresponding @dfn{offset(s)}. The symbol @code{+}, which means
+``indent this line one more level'' is a typical offset. @ccmode{}
+then applies these offset(s) to the anchor position, giving the
+indentation for the line. The different sorts of offsets are
+described in @ref{c-offsets-alist}.
+@end enumerate
+
+In exceptional circumstances, the syntax directed indentation
+described here may be a nuisance rather than a help. You can disable
+it by setting @code{c-syntactic-indentation} to @code{nil}. (To set
+the variable interactively, @ref{Minor Modes}).
+
+@defopt c-syntactic-indentation
+@vindex syntactic-indentation (c-)
+When this is non-@code{nil} (which it is by default), the indentation
+of code is done according to its syntactic structure. 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 current style
+(@pxref{Config Basics}) then has no effect on indentation, nor do any
+of the variables associated with indentation, not even
+@code{c-special-indent-hook}.
+@end defopt
+
+@menu
+* Syntactic Analysis::
+* Syntactic Symbols::
+* Indentation Calculation::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics
+@comment node-name, next, previous, up
+@section Syntactic Analysis
+@cindex syntactic analysis
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@code{((friend) (inclass . 58) (topmost-intro . 380))}
+@cindex syntactic element
+@cindex syntactic context
+The first thing @ccmode{} does when indenting a line of code, is to
+analyze the line, determining the @dfn{syntactic context} of the
+(first) construct on that line. It's a list of @dfn{syntactic
+elements}, where each syntactic element in turn is a list@footnote{In
+@ccmode 5.28 and earlier, a syntactic element was a dotted pair; the
+cons was the syntactic symbol and the cdr was the anchor position.
+For compatibility's sake, the parameter passed to a line-up function
+still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a
+brief and typical example:
+@example
+((defun-block-intro 1959))
@end example
-The @code{friend} syntactic symbol is a modifier that typically does not
-have a relative buffer position.
+@cindex syntactic symbol
+@noindent
+The first thing inside each syntactic element is always a
+@dfn{syntactic symbol}. It describes the kind of construct that was
+recognized, 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 remaining entries are various data associated
+with the recognized construct - there might be zero or more.
+
+@cindex anchor position
+Conceptually, a line of code is always indented relative to some
+position higher up in the buffer (typically the indentation of the
+previous line). That position is the @dfn{anchor position} in the
+syntactic element. If there is an entry after the syntactic symbol in
+the syntactic element list then it's either nil or that anchor position.
-Template definitions introduce yet another syntactic symbol:
+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
-@group
+ 1: void swap( int& a, int& b )
+ 2: @{
+ 3: int tmp = a;
+ 4: a = b;
+ 5: b = tmp;
+ 6: @}
+@end example
- 1: ThingManager <int,
- 2: Framework::Callback *,
- 3: Mutex> framework_callbacks;
+@noindent
+We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to
+report what the syntactic analysis is for the current line:
-@end group
+@table @asis
+@item @kbd{C-c C-s} (@code{c-show-syntactic-information})
+@kindex C-c C-s
+@findex c-show-syntactic-information
+@findex show-syntactic-information (c-)
+This command calculates the syntactic analysis of the current line and
+displays it in the minibuffer. The command also highlights the anchor
+position(s).
+@end table
+
+ Running this command on line 4 of this example, we'd see in the echo
+area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the
+analysis is inserted into the buffer as a comment on the current
+line.}:
+
+@example
+((statement 35))
@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.
+@noindent
+and the @samp{i} of @code{int} on line 3 would be highlighted. This
+tells us that the line is a statement and it is indented relative to
+buffer position 35, the highlighted position. If you were to move
+point to line 3 and hit @kbd{C-c C-s}, you would see:
-Here is another (totally contrived) example which illustrates how syntax
-is assigned to various conditional constructs:
@example
-@group
+((defun-block-intro 29))
+@end example
- 1: void spam( int index )
- 2: @{
- 3: for( int i=0; i<index; i++ )
- 4: @{
- 5: if( i == 10 )
- 6: @{
- 7: do_something_special();
- 8: @}
- 9: else
- 10: do_something( i );
- 11: @}
- 12: do @{
- 13: another_thing( i-- );
- 14: @}
- 15: while( i > 0 );
- 16: @}
+@noindent
+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:
-@end group
+@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
-Only the lines that illustrate new syntactic symbols will be discussed.
+Hitting @kbd{C-c C-s} on line 4 gives us:
-@cindex substatement-open syntactic symbol
-@cindex substatement-block-intro syntactic symbol
-@cindex block-close syntactic symbol
-Line 4 has a brace which opens a conditional's substatement block. It
-is thus assigned @code{substatement-open} syntax, and since line 5 is
-the first line in the substatement block, it is assigned
-@code{substatement-block-intro} syntax. Lines 6 and 7 are assigned
-similar syntax. Line 8 contains the brace that closes the inner
-substatement block. It is given the syntax @code{block-close},
-as are lines 11 and 14.
-
-@cindex else-clause syntactic symbol
-@cindex catch-clause syntactic symbol
-Line 9 is a little different --- since it contains the keyword
-@code{else} matching the @code{if} statement introduced on line 5, it is
-given the @code{else-clause} syntax. The @code{try}-@code{catch}
-constructs in C++ and Java are treated this way too, with the only
-difference that the @code{catch}, and in Java also @code{finally}, is
-marked with @code{catch-clause}.
-
-@cindex substatement syntactic symbol
-Line 10 is also slightly different. Because @code{else} is considered a
-conditional introducing keyword @footnote{The list of conditional
-keywords are (in C, C++, Objective-C, Java, and Pike): @code{for},
-@code{if}, @code{do}, @code{else}, @code{while}, and @code{switch}. C++
-and Java have two additional conditional keywords: @code{try} and
-@code{catch}. Java also has the @code{finally} and @code{synchronized}
-keywords.}, and because the following substatement is not a brace block,
-line 10 is assigned the @code{substatement} syntax.
-
-@cindex do-while-closure syntactic symbol
-One other difference is seen on line 15. The @code{while} construct
-that closes a @code{do} conditional is given the special syntax
-@code{do-while-closure} if it appears on a line by itself. Note that if
-the @code{while} appeared on the same line as the preceding close brace,
-that line would have been assigned @code{block-close} syntax instead.
+@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 contexts can contain more than one element, and syntactic
+elements need not have anchor positions. The most common example of
+this is a @dfn{comment-only line}:
-Switch statements have their own set of syntactic symbols. Here's an
-example:
@example
-@group
+ 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
- 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: @}
+@noindent
+Hitting @kbd{C-c C-s} on line 3 of this example gives:
-@end group
+@example
+((comment-intro) (defun-block-intro 46))
@end example
-@cindex case-label syntactic symbol
-@cindex statement-case-intro syntactic symbol
-@cindex statement-case-open syntactic symbol
-Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
-while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
-is treated slightly differently since it contains a brace that opens a
-block --- it is given @code{statement-case-open} syntax.
+@noindent
+and you can see that the syntactic context contains two syntactic
+elements. Notice that the first element, @samp{(comment-intro)}, has no
+anchor position.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics
+@comment node-name, next, previous, up
+@section Syntactic Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex syntactic symbols, brief list
+@vindex c-offsets-alist
+@vindex offsets-alist (c-)
+This section is a complete list of the syntactic symbols which appear
+in the @code{c-offsets-alist} style variable, along with brief
+descriptions. The previous section (@pxref{Syntactic Analysis})
+states what syntactic symbols are and how the indentation engine uses
+them.
+
+More detailed descriptions of these symbols, together with snippets of
+source code to which they apply, appear in the examples in the
+subsections below. Note that, in the interests of brevity, the anchor
+position associated with most syntactic symbols is @emph{not}
+specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent
+line---this highlights the anchor position.
+
+@ssindex -open symbols
+@ssindex -close symbols
+@ssindex -block-intro symbols
+The syntactic symbols which indicate brace constructs follow a general
+naming convention. When a line begins with an open or close brace,
+its syntactic symbol will contain the suffix @code{-open} or
+@code{-close} respectively. The first line within the brace block
+construct will contain the suffix @code{-block-intro}.
+
+@ssindex -intro symbols
+@ssindex -cont symbols
+In constructs which can span several lines, a distinction is usually
+made between the first line that introduces the construct and the
+lines that continue it. The syntactic symbols that indicate these
+lines will contain the suffixes @code{-intro} or @code{-cont}
+respectively.
+
+The best way to understand how all this works is by looking at some
+examples. Remember that you can see the syntax of any source code
+line by using @kbd{C-c C-s}.
+
+@table @code
+@item string
+Inside a multiline string. @ref{Literal Symbols}.
+@item c
+Inside a multiline C style block comment. @ref{Literal Symbols}.
+@item defun-open
+Brace that opens a top-level function definition. @ref{Function
+Symbols}.
+@item defun-close
+Brace that closes a top-level function definition. @ref{Function
+Symbols}.
+@item defun-block-intro
+The first line in a top-level defun. @ref{Function Symbols}.
+@item class-open
+Brace that opens a class definition. @ref{Class Symbols}.
+@item class-close
+Brace that closes a class definition. @ref{Class Symbols}.
+@item inline-open
+Brace that opens an in-class inline method. @ref{Class Symbols}.
+@item inline-close
+Brace that closes an in-class inline method. @ref{Class Symbols}.
+@item func-decl-cont
+The region between a function definition's argument list and the
+function opening brace (excluding K&R argument declarations). In C,
+you cannot put anything but whitespace and comments in this region,
+however in C++ and Java, @code{throws} declarations and other things
+can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not
+@c go somewhere better?}
+@item knr-argdecl-intro
+First line of a K&R C argument declaration. @ref{K&R Symbols}.
+@item knr-argdecl
+Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}.
+@item topmost-intro
+The first line in a ``topmost'' definition. @ref{Function Symbols}.
+@item topmost-intro-cont
+Topmost definition continuation lines. This is only used in the parts
+that aren't covered by other symbols such as @code{func-decl-cont} and
+@code{knr-argdecl}. @ref{Function Symbols}.
+@item member-init-intro
+First line in a member initialization list. @ref{Class Symbols}.
+@item member-init-cont
+Subsequent member initialization list lines. @ref{Class Symbols}.
+@item inher-intro
+First line of a multiple inheritance list. @ref{Class Symbols}.
+@item inher-cont
+Subsequent multiple inheritance lines. @ref{Class Symbols}.
+@item block-open
+Statement block open brace. @ref{Literal Symbols}.
+@item block-close
+Statement block close brace. @ref{Conditional Construct Symbols}.
+@item brace-list-open
+Open brace of an enum or static array list. @ref{Brace List Symbols}.
+@item brace-list-close
+Close brace of an enum or static array list. @ref{Brace List Symbols}.
+@item brace-list-intro
+First line in an enum or static array list. @ref{Brace List Symbols}.
+@item brace-list-entry
+Subsequent lines in an enum or static array list. @ref{Brace List
+Symbols}.
+@item brace-entry-open
+Subsequent lines in an enum or static array list where the line begins
+with an open brace. @ref{Brace List Symbols}.
+@item statement
+A statement. @ref{Function Symbols}.
+@item statement-cont
+A continuation of a statement. @ref{Function Symbols}.
+@item statement-block-intro
+The first line in a new statement block. @ref{Conditional Construct
+Symbols}.
+@item statement-case-intro
+The first line in a case block. @ref{Switch Statement Symbols}.
+@item statement-case-open
+The first line in a case block that starts with a brace. @ref{Switch
+Statement Symbols}.
+@item substatement
+The first line after a conditional or loop construct.
+@ref{Conditional Construct Symbols}.
+@item substatement-open
+The brace that opens a substatement block. @ref{Conditional Construct
+Symbols}.
+@item substatement-label
+The first line after a conditional or loop construct if it's a label.
+@ref{Conditional Construct Symbols}.
+@item case-label
+A label in a @code{switch} block. @ref{Switch Statement Symbols}.
+@item access-label
+C++ access control label. @ref{Class Symbols}.
+@item label
+Any other label. @ref{Literal Symbols}.
+@item do-while-closure
+The @code{while} line that ends a @code{do}-@code{while} construct.
+@ref{Conditional Construct Symbols}.
+@item else-clause
+The @code{else} line of an @code{if}-@code{else} construct.
+@ref{Conditional Construct Symbols}.
+@item catch-clause
+The @code{catch} or @code{finally} (in Java) line of a
+@code{try}-@code{catch} construct. @ref{Conditional Construct
+Symbols}.
+@item comment-intro
+A line containing only a comment introduction. @ref{Literal Symbols}.
+@item arglist-intro
+The first line in an argument list. @ref{Paren List Symbols}.
+@item arglist-cont
+Subsequent argument list lines when no arguments follow on the same
+line as the arglist opening paren. @ref{Paren List Symbols}.
+@item arglist-cont-nonempty
+Subsequent argument list lines when at least one argument follows on
+the same line as the arglist opening paren. @ref{Paren List Symbols}.
+@item arglist-close
+The solo close paren of an argument list. @ref{Paren List Symbols}.
+@item stream-op
+Lines continuing a stream operator (C++ only). @ref{Literal
+Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?}
+@item inclass
+The line is nested inside a class definition. @ref{Class Symbols}.
+@item cpp-macro
+The start of a preprocessor macro definition. @ref{Literal Symbols}.
+@item cpp-define-intro
+The first line inside a multiline preproprocessor macro if
+@code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro
+Symbols}.
+@item cpp-macro-cont
+All lines inside multiline preprocessor macros if
+@code{c-syntactic-indentation-in-macros} is @code{nil}.
+@ref{Multiline Macro Symbols}.
+@item friend
+A C++ friend declaration. @ref{Class Symbols}.
+@item objc-method-intro
+The first line of an Objective-C method definition. @ref{Objective-C
+Method Symbols}.
+@item objc-method-args-cont
+Lines continuing an Objective-C method definition. @ref{Objective-C
+Method Symbols}.
+@item objc-method-call-cont
+Lines continuing an Objective-C method call. @ref{Objective-C Method
+Symbols}.
+@item extern-lang-open
+Brace that opens an @code{extern} block (e.g. @code{extern "C"
+@{...@}}). @ref{External Scope Symbols}.
+@item extern-lang-close
+Brace that closes an @code{extern} block. @ref{External Scope
+Symbols}.
+@item inextern-lang
+Analogous to @code{inclass} syntactic symbol, but used inside
+@code{extern} blocks. @ref{External Scope Symbols}.
+@item namespace-open
+@itemx namespace-close
+@itemx innamespace
+These are analogous to the three @code{extern-lang} symbols above, but
+are returned for C++ namespace blocks. @ref{External Scope Symbols}.
+@item module-open
+@itemx module-close
+@itemx inmodule
+Analogous to the above, but for CORBA IDL @code{module} blocks.
+@ref{External Scope Symbols}.
+@item composition-open
+@itemx composition-close
+@itemx incomposition
+Analogous to the above, but for CORBA CIDL @code{composition} blocks.
+@ref{External Scope Symbols}.
+@item template-args-cont
+C++ template argument list continuations. @ref{Class Symbols}.
+@item inlambda
+Analogous to @code{inclass} syntactic symbol, but used inside lambda
+(i.e. anonymous) functions. Only used in Pike mode. @ref{Statement
+Block Symbols}.
+@item lambda-intro-cont
+Lines continuing the header of a lambda function, i.e. between the
+@code{lambda} keyword and the function body. Only used in Pike mode.
+@ref{Statement Block Symbols}.
+@item inexpr-statement
+A statement block inside an expression. The gcc C and C++ extension
+for this is recognized. It's also used for the special functions that
+take a statement block as an argument in Pike. @ref{Statement Block
+Symbols}.
+@item inexpr-class
+A class definition inside an expression. This is used for anonymous
+classes in Java. It's also used for anonymous array initializers in
+Java. @ref{Anonymous Class Symbol}.
+@end table
+
+@menu
+* Function Symbols::
+* Class Symbols::
+* Conditional Construct Symbols::
+* Switch Statement Symbols::
+* Brace List Symbols::
+* External Scope Symbols::
+* Paren List Symbols::
+* Literal Symbols::
+* Multiline Macro Symbols::
+* Objective-C Method Symbols::
+* Anonymous Class Symbol::
+* Statement Block Symbols::
+* K&R Symbols::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Function Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This example shows a typical function declaration.
+
+@example
+ 1: void
+ 2: swap( int& a, int& b )
+ 3: @{
+ 4: int tmp = a;
+ 5: a = b;
+ 6: b = tmp;
+ 7: int ignored =
+ 8: a + b;
+ 9: @}
+@end example
+
+@ssindex topmost-intro
+@ssindex topmost-intro-cont
+@ssindex defun-open
+@ssindex defun-close
+@ssindex defun-block-intro
+Line 1 shows a @code{topmost-intro} since it is the first line that
+introduces a top-level construct. Line 2 is a continuation of the
+top-level construct introduction so it has the syntax
+@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
+the brace that opens a top-level function definition. Line 9 is the
+corresponding
+@code{defun-close} since it contains the brace that closes the top-level
+function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
+the first line of a brace-block, enclosed in a
+top-level function definition.
+
+@ssindex statement
+@ssindex statement-cont
+Lines 5, 6, and 7 are all given @code{statement} syntax since there
+isn't much special about them. Note however that line 8 is given
+@code{statement-cont} syntax since it continues the statement begun
+on the previous line.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Class related Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Here's an example which illustrates some C++ class syntactic symbols:
+
+@example
+ 1: class Bass
+ 2: : public Guitar,
+ 3: public Amplifiable
+ 4: @{
+ 5: public:
+ 6: Bass()
+ 7: : eString( new BassString( 0.105 )),
+ 8: aString( new BassString( 0.085 )),
+ 9: dString( new BassString( 0.065 )),
+10: gString( new BassString( 0.045 ))
+11: @{
+12: eString.tune( 'E' );
+13: aString.tune( 'A' );
+14: dString.tune( 'D' );
+15: gString.tune( 'G' );
+16: @}
+17: friend class Luthier;
+18: @};
+@end example
+
+@ssindex class-open
+@ssindex class-close
+As in the previous example, line 1 has the @code{topmost-intro} syntax.
+Here however, the brace that opens a C++ class definition on line 4 is
+assigned the @code{class-open} syntax. Note that in C++, classes,
+structs, and unions are essentially equivalent syntactically (and are
+very similar semantically), so replacing the @code{class} keyword in the
+example above with @code{struct} or @code{union} would still result in a
+syntax of @code{class-open} for line 4 @footnote{This is the case even
+for C and Objective-C. For consistency, structs in all supported
+languages are syntactically equivalent to classes. Note however that
+the keyword @code{class} is meaningless in C and Objective-C.}.
+Similarly, line 18 is assigned @code{class-close} syntax.
+
+@ssindex inher-intro
+@ssindex inher-cont
+Line 2 introduces the inheritance list for the class so it is assigned
+the @code{inher-intro} syntax, and line 3, which continues the
+inheritance list is given @code{inher-cont} syntax.
+
+@ssindex access-label
+@ssindex inclass
+Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
+
+@example
+((inclass 58) (access-label 58))
+@end example
+
+@noindent
+The primary syntactic symbol for this line is @code{access-label} as
+this a label keyword that specifies access protection in C++. However,
+because this line is also a top-level construct inside a class
+definition, the analysis actually shows two syntactic symbols. The
+other syntactic symbol assigned to this line is @code{inclass}.
+Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
+syntax:
+
+@example
+((inclass 58) (topmost-intro 60))
+@end example
+
+@ssindex member-init-intro
+@ssindex member-init-cont
+Line 7 introduces a C++ member initialization list and as such is given
+@code{member-init-intro} syntax. Note that in this case it is
+@emph{not} assigned @code{inclass} since this is not considered a
+top-level construct. Lines 8 through 10 are all assigned
+@code{member-init-cont} since they continue the member initialization
+list started on line 7.
+
+@cindex in-class inline methods
+@ssindex inline-open
+@ssindex inline-close
+Line 11's analysis is a bit more complicated:
+
+@example
+((inclass 58) (inline-open))
+@end example
+
+This line is assigned a syntax of both @code{inline-open} and
+@code{inclass} because it opens an @dfn{in-class} C++ inline method
+definition. This is distinct from, but related to, the C++ notion of an
+inline function in that its definition occurs inside an enclosing class
+definition, which in C++ implies that the function should be inlined.
+However, if the definition of the @code{Bass} constructor appeared
+outside the class definition, the construct would be given the
+@code{defun-open} syntax, even if the keyword @code{inline} appeared
+before the method name, as in:
+
+@example
+ 1: class Bass
+ 2: : public Guitar,
+ 3: public Amplifiable
+ 4: @{
+ 5: public:
+ 6: Bass();
+ 7: @};
+ 8:
+ 9: inline
+10: Bass::Bass()
+11: : eString( new BassString( 0.105 )),
+12: aString( new BassString( 0.085 )),
+13: dString( new BassString( 0.065 )),
+14: gString( new BassString( 0.045 ))
+15: @{
+16: eString.tune( 'E' );
+17: aString.tune( 'A' );
+18: dString.tune( 'D' );
+19: gString.tune( 'G' );
+20: @}
+@end example
+
+@ssindex friend
+Returning to the previous example, line 16 is given @code{inline-close}
+syntax, while line 12 is given @code{defun-block-open} syntax, and lines
+13 through 15 are all given @code{statement} syntax. Line 17 is
+interesting in that its syntactic analysis list contains three
+elements:
+
+@example
+((inclass 58) (topmost-intro 380) (friend))
+@end example
+
+The @code{friend} and @code{inline-open} syntactic symbols are
+modifiers that do not have anchor positions.
+
+@ssindex template-args-cont
+Template definitions introduce yet another syntactic symbol:
+
+@example
+ 1: ThingManager <int,
+ 2: Framework::Callback *,
+ 3: Mutex> framework_callbacks;
+@end example
+
+Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
+are both analyzed as @code{template-args-cont} lines.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Conditional Construct Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Here is a (totally contrived) example which illustrates how syntax is
+assigned to various conditional constructs:
+
+@example
+ 1: void spam( int index )
+ 2: @{
+ 3: for( int i=0; i<index; i++ )
+ 4: @{
+ 5: if( i == 10 )
+ 6: do_something_special();
+ 7: else
+ 8: silly_label:
+ 9: do_something( i );
+10: @}
+11: do @{
+12: another_thing( i-- );
+13: @}
+14: while( i > 0 );
+15: @}
+@end example
+
+Only the lines that illustrate new syntactic symbols will be discussed.
+
+@ssindex substatement-open
+@ssindex statement-block-intro
+@ssindex block-close
+Line 4 has a brace which opens a conditional's substatement block. It
+is thus assigned @code{substatement-open} syntax, and since line 5 is
+the first line in the substatement block, it is assigned
+@code{statement-block-intro} syntax. Line 10 contains the brace
+that closes the inner substatement block, and is therefore given the
+syntax @code{block-close}@footnote{@code{block-open} is used only for
+``free-standing'' blocks, and is somewhat rare (@pxref{Literal
+Symbols} for an example.)}. Line 13 is treated the same way.
+
+@ssindex substatement
+Lines 6 and 9 are also substatements of conditionals, but since they
+don't start blocks they are given @code{substatement} syntax
+instead of @code{substatement-open}.
+
+@ssindex substatement-label
+Line 8 contains a label, which is normally given @code{label} syntax.
+This one is however a bit special since it's between a conditional and
+its substatement. It's analyzed as @code{substatement-label} to let you
+handle this rather odd case differently from normal labels.
+
+@ssindex else-clause
+@ssindex catch-clause
+Line 7 start with an @code{else} that matches the @code{if} statement on
+line 5. It is therefore given the @code{else-clause} syntax and is
+anchored on the matching @code{if}. The @code{try}-@code{catch}
+constructs in C++ and Java are treated this way too, except that
+@code{catch} and (in Java) @code{finally}, are marked with
+@code{catch-clause}.
+
+@ssindex do-while-closure
+The @code{while} construct on line 14 that closes a @code{do}
+conditional is given the special syntax @code{do-while-closure} if it
+appears on a line by itself. Note that if the @code{while} appeared on
+the same line as the preceding close brace, that line would still have
+@code{block-close} syntax.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Switch Statement Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Switch statements have their own set of syntactic symbols. Here's an
+example:
+
+@example
+ 1: void spam( enum Ingredient i )
+ 2: @{
+ 3: switch( i ) @{
+ 4: case Ham:
+ 5: be_a_pig();
+ 6: break;
+ 7: case Salt:
+ 8: drink_some_water();
+ 9: break;
+10: default:
+11: @{
+12: what_is_it();
+13: break;
+14: @}
+15: @}
+14: @}
+@end example
+
+@ssindex case-label
+@ssindex statement-case-intro
+@ssindex statement-case-open
+Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
+while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
+is treated slightly differently since it contains a brace that opens a
+block --- it is given @code{statement-case-open} syntax.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Brace List Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@cindex brace lists
There are a set of syntactic symbols that are used to recognize
initialize an array of structs. The three special aggregate constructs
in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
brace lists too. An example:
+
+@example
+ 1: static char* ingredients[] =
+ 2: @{
+ 3: "Ham",
+ 4: "Salt",
+ 5: NULL
+ 6: @};
+@end example
+
+@ssindex brace-list-open
+@ssindex brace-list-intro
+@ssindex brace-list-close
+@ssindex brace-list-entry
+Following convention, line 2 in this example is assigned
+@code{brace-list-open} syntax, and line 3 is assigned
+@code{brace-list-intro} syntax. Likewise, line 6 is assigned
+@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
+@code{brace-list-entry} syntax, as would all subsequent lines in this
+initializer list.
+
+@ssindex brace-entry-open
+Your static initializer might be initializing nested structures, for
+example:
+
+@example
+ 1: struct intpairs[] =
+ 2: @{
+ 3: @{ 1, 2 @},
+ 4: @{
+ 5: 3,
+ 6: 4
+ 7: @}
+ 8: @{ 1,
+ 9: 2 @},
+10: @{ 3, 4 @}
+11: @};
+@end example
+
+Here, you've already seen the analysis of lines 1, 2, 3, and 11. On
+line 4, things get interesting; this line is assigned
+@code{brace-entry-open} syntactic symbol because it's a bracelist entry
+line that starts with an open brace. Lines 5 and 6 (and line 9) are
+pretty standard, and line 7 is a @code{brace-list-close} as you'd
+expect. Once again, line 8 is assigned as @code{brace-entry-open} as is
+line 10.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection External Scope Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+External language definition blocks also have their own syntactic
+symbols. In this example:
+
+@example
+ 1: extern "C"
+ 2: @{
+ 3: int thing_one( int );
+ 4: int thing_two( double );
+ 5: @}
+@end example
+
+@ssindex extern-lang-open
+@ssindex extern-lang-close
+@ssindex inextern-lang
+@ssindex inclass
+@noindent
+line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
+the @code{extern-lang-close} syntax. The analysis for line 3 yields:
+
+@example
+((inextern-lang) (topmost-intro 14))
+@end example
+
+@noindent
+where @code{inextern-lang} is a modifier similar in purpose to
+@code{inclass}.
+
+There are various other top level blocks like @code{extern}, and they
+are all treated in the same way except that the symbols are named after
+the keyword that introduces the block. E.g. C++ namespace blocks get
+the three symbols @code{namespace-open}, @code{namespace-close} and
+@code{innamespace}. The currently recognized top level blocks are:
+
+@table @asis
+@item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
+@code{extern} blocks in C and C++.@footnote{These should logically be
+named @code{extern-open}, @code{extern-close} and @code{inextern}, but
+that isn't the case for historical reasons.}
+
+@item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
+@ssindex namespace-open
+@ssindex namespace-close
+@ssindex innamespace
+@code{namespace} blocks in C++.
+
+@item @code{module-open}, @code{module-close}, @code{inmodule}
+@ssindex module-open
+@ssindex module-close
+@ssindex inmodule
+@code{module} blocks in CORBA IDL.
+
+@item @code{composition-open}, @code{composition-close}, @code{incomposition}
+@ssindex composition-open
+@ssindex composition-close
+@ssindex incomposition
+@code{composition} blocks in CORBA CIDL.
+@end table
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Parenthesis (Argument) List Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+A number of syntactic symbols are associated with parenthesis lists,
+a.k.a argument lists, as found in function declarations and function
+calls. This example illustrates these:
+
+@example
+ 1: void a_function( int line1,
+ 2: int line2 );
+ 3:
+ 4: void a_longer_function(
+ 5: int line1,
+ 6: int line2
+ 7: );
+ 8:
+ 9: void call_them( int line1, int line2 )
+10: @{
+11: a_function(
+12: line1,
+13: line2
+14: );
+15:
+16: a_longer_function( line1,
+17: line2 );
+18: @}
+@end example
+
+@ssindex arglist-intro
+@ssindex arglist-close
+Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
+the first line following the open parenthesis, and lines 7 and 14 are
+assigned @code{arglist-close} syntax since they contain the parenthesis
+that closes the argument list.
+
+@ssindex arglist-cont-nonempty
+@ssindex arglist-cont
+Lines that continue argument lists can be assigned one of two syntactic
+symbols. For example, Lines 2 and 17
+are assigned @code{arglist-cont-nonempty} syntax. What this means
+is that they continue an argument list, but that the line containing the
+parenthesis that opens the list is @emph{not empty} following the open
+parenthesis. Contrast this against lines 6 and 13 which are assigned
+@code{arglist-cont} syntax. This is because the parenthesis that opens
+their argument lists is the last character on that line.
+
+Syntactic elements with @code{arglist-intro},
+@code{arglist-cont-nonempty}, and @code{arglist-close} contain two
+buffer positions: the anchor position (the beginning of the
+declaration or statement) and the position of the open parenthesis.
+The latter position can be used in a line-up function (@pxref{Line-Up
+Functions}).
+
+Note that there is no @code{arglist-open} syntax. This is because any
+parenthesis that opens an argument list, appearing on a separate line,
+is assigned the @code{statement-cont} syntax instead.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Comment String Label and Macro Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+A few miscellaneous syntactic symbols that haven't been previously
+covered are illustrated by this C++ example:
+
+@example
+ 1: void Bass::play( int volume )
+ 2: const
+ 3: @{
+ 4: /* this line starts a multiline
+ 5: * comment. This line should get `c' syntax */
+ 6:
+ 7: char* a_multiline_string = "This line starts a multiline \
+ 8: string. This line should get `string' syntax.";
+ 9:
+10: note:
+11: @{
+12: #ifdef LOCK
+13: Lock acquire();
+14: #endif // LOCK
+15: slap_pop();
+16: cout << "I played "
+17: << "a note\n";
+18: @}
+19: @}
+@end example
+
+The lines to note in this example include:
+
+@itemize @bullet
+@item
+@ssindex func-decl-cont
+Line 2 is assigned the @code{func-decl-cont} syntax.
+
+@item
+@ssindex comment-intro
+Line 4 is assigned both @code{defun-block-intro} @emph{and}
+@code{comment-intro} syntax. A syntactic element with
+@code{comment-intro} has no anchor point --- It is always accompanied
+by another syntactic element which does have one.
+
+@item
+@ssindex c
+Line 5 is assigned @code{c} syntax.
+
+@item
+@cindex syntactic whitespace
+Line 6 which, even though it contains nothing but whitespace, is
+assigned @code{defun-block-intro}. Note that the appearance of the
+comment on lines 4 and 5 do not cause line 6 to be assigned
+@code{statement} syntax because comments are considered to be
+@dfn{syntactic whitespace}, which are ignored when analyzing
+code.
+
+@item
+@ssindex string
+Line 8 is assigned @code{string} syntax.
+
+@item
+@ssindex label
+Line 10 is assigned @code{label} syntax.
+
+@item
+@ssindex block-open
+Line 11 is assigned @code{block-open} as well as @code{statement}
+syntax. A @code{block-open} syntactic element doesn't have an anchor
+position, since it always appears with another syntactic element which
+does have one.
+
+@item
+@ssindex cpp-macro
+Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
+normal syntactic symbols (@code{statement-block-intro} and
+@code{statement}, respectively). Normally @code{cpp-macro} is
+configured to cancel out the normal syntactic context to make all
+preprocessor directives stick to the first column, but that's easily
+changed if you want preprocessor directives to be indented like the rest
+of the code. Like @code{comment-intro}, a syntactic element with
+@code{cpp-macro} doesn't contain an anchor position.
+
+@item
+@ssindex stream-op
+Line 17 is assigned @code{stream-op} syntax.
+@end itemize
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Multiline Macro Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex multiline macros
+@cindex syntactic whitespace
+@ssindex cpp-define-intro
+@ssindex cpp-macro-cont
+Multiline preprocessor macro definitions are normally handled just like
+other code, i.e. the lines inside them are indented according to the
+syntactic analysis of the preceding lines inside the macro. The first
+line inside a macro definition (i.e. the line after the starting line of
+the cpp directive itself) gets @code{cpp-define-intro}. In this example:
+
+@example
+ 1: #define LIST_LOOP(cons, listp) \
+ 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
+ 3: if (!CONSP (cons)) \
+ 4: signal_error ("Invalid list format", listp); \
+ 5: else
+@end example
+
+@noindent
+line 1 is given the syntactic symbol @code{cpp-macro}. The first line
+of a cpp directive is always given that symbol. Line 2 is given
+@code{cpp-define-intro}, so that you can give the macro body as a whole
+some extra indentation. Lines 3 through 5 are then analyzed as normal
+code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause}
+on line 5.
+
+The syntactic analysis inside macros can be turned off with
+@code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In
+that case, lines 2 through 5 would all be given @code{cpp-macro-cont}
+with an anchor position pointing to the @code{#} which starts the cpp
+directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed
+macros.}.
+
+@xref{Custom Macros}, for more info about the treatment of macros.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Objective-C Method Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+In Objective-C buffers, there are three additional syntactic symbols
+assigned to various message calling constructs. Here's an example
+illustrating these:
+
+@example
+ 1: - (void)setDelegate:anObject
+ 2: withStuff:stuff
+ 3: @{
+ 4: [delegate masterWillRebind:self
+ 5: toDelegate:anObject
+ 6: withExtraStuff:stuff];
+ 7: @}
+@end example
+
+@ssindex objc-method-intro
+@ssindex objc-method-args-cont
+@ssindex objc-method-call-cont
+Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
+assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
+assigned @code{objc-method-call-cont} syntax.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Anonymous Class Symbol (Java)
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Java has a concept of anonymous classes which can look something like
+this:
+
+@example
+ 1: public void watch(Observable o) @{
+ 2: o.addObserver(new Observer() @{
+ 3: public void update(Observable o, Object arg) @{
+ 4: history.addElement(arg);
+ 5: @}
+ 6: @});
+ 7: @}
+@end example
+
+@ssindex inexpr-class
+The brace following the @code{new} operator opens the anonymous class.
+Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the
+@code{inclass} symbol used in normal classes. Thus, the class will be
+indented just like a normal class, with the added indentation given to
+@code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't
+have an anchor position.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection Statement Block Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+There are a few occasions where a statement block might be used inside
+an expression. One is in C or C++ code using the gcc extension for
+this, e.g:
+
+@example
+ 1: int res = (@{
+ 2: int y = foo (); int z;
+ 3: if (y > 0) z = y; else z = - y;
+ 4: z;
+ 5: @});
+@end example
+
+@ssindex inexpr-statement
+Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
+symbols they'd get in a normal block. Therefore, the indentation put on
+@code{inexpr-statement} is added to the normal statement block
+indentation. An @code{inexpr-statement} syntactic element doesn't
+contain an anchor position.
+
+In Pike code, there are a few other situations where blocks occur inside
+statements, as illustrated here:
+
+@example
+ 1: array itgob()
+ 2: @{
+ 3: string s = map (backtrace()[-2][3..],
+ 4: lambda
+ 5: (mixed arg)
+ 6: @{
+ 7: return sprintf ("%t", arg);
+ 8: @}) * ", " + "\n";
+ 9: return catch @{
+10: write (s + "\n");
+11: @};
+12: @}
+@end example
+
+@ssindex inlambda
+@ssindex lambda-intro-cont
+Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
+by the @code{lambda} keyword. If the function argument list is put
+on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
+syntax. The function body is handled as an inline method body, with the
+addition of the @code{inlambda} syntactic symbol. This means that line
+6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
+@code{inline-close}@footnote{You might wonder why it doesn't get
+@code{inlambda} too. It's because the closing brace is relative to the
+opening brace, which stands on its own line in this example. If the
+opening brace was hanging on the previous line, then the closing brace
+would get the @code{inlambda} syntax too to be indented correctly.}.
+
+@ssindex inexpr-statement
+On line 9, @code{catch} is a special function taking a statement block
+as its argument. The block is handled as an in-expression statement
+with the @code{inexpr-statement} syntax, just like the gcc extended C
+example above. The other similar special function, @code{gauge}, is
+handled like this too.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node K&R Symbols, , Statement Block Symbols, Syntactic Symbols
+@comment node-name, next, previous, up
+@subsection K&R Symbols
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@ssindex knr-argdecl-intro
+@ssindex knr-argdecl
+Two other syntactic symbols can appear in old style, non-prototyped C
+code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
+
+@example
+ 1: int add_three_integers(a, b, c)
+ 2: int a;
+ 3: int b;
+ 4: int c;
+ 5: @{
+ 6: return a + b + c;
+ 7: @}
+@end example
+
+Here, line 2 is the first line in an argument declaration list and so is
+given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
+(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
+syntax.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics
+@comment node-name, next, previous, up
+@section Indentation Calculation
+@cindex indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Indentation for a line is calculated from the syntactic context
+(@pxref{Syntactic Analysis}).
+
+First, a buffer position is found whose column will be the base for the
+indentation calculation. It's the anchor position in the first
+syntactic element that provides one that is used. If no syntactic
+element has an anchor position then column zero is used.
+
+Second, the syntactic symbols in each syntactic element are looked up
+in the @code{c-offsets-alist} style variable
+(@pxref{c-offsets-alist}), which is an association list of syntactic
+symbols and the offsets to apply for those symbols. These offsets are
+added together with the base column to produce the new indentation
+column.
+
+Let's use our two code examples above to see how this works. Here is
+our first example again:
+
+@example
+ 1: void swap( int& a, int& b )
+ 2: @{
+ 3: int tmp = a;
+ 4: a = b;
+ 5: b = tmp;
+ 6: @}
+@end example
+
+Let's say point is on line 3 and we hit the @key{TAB} key to reindent
+the line. The syntactic context for that line is:
+
+@example
+((defun-block-intro 29))
+@end example
+
+@noindent
+Since buffer position 29 is the first and only anchor position in the
+list, @ccmode{} goes there and asks for the current column. This brace
+is in column zero, so @ccmode{} uses @samp{0} as the base column.
+
+Next, @ccmode{} looks up @code{defun-block-intro} in the
+@code{c-offsets-alist} style variable. Let's say it finds the value
+@samp{4}; it adds this to the base column @samp{0}, yielding a running
+total indentation of 4 spaces.
+
+Since there is only one syntactic element on the list for this line,
+indentation calculation is complete, and the total indentation for the
+line is 4 spaces.
+
+Here's another example:
+
+@example
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+@end example
+
+If we were to hit @kbd{TAB} on line 4 in the above example, the same
+basic process is performed, despite the differences in the syntactic
+context. The context for this line is:
+
+@example
+((substatement-open 46))
+@end example
+
+Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in
+@code{if} on line 3. This character is in the fourth column on that
+line so the base column is @samp{4}. Then @ccmode{} looks up the
+@code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it
+finds the value @samp{4}. It's added with the base column and yields an
+indentation for the line of 8 spaces.
+
+Simple, huh?
+
+Actually, it's a bit more complicated than that since the entries on
+@code{c-offsets-alist} can be much more than plain offsets.
+@xref{c-offsets-alist}, for the full story.
+
+Anyway, the mode usually just does The Right Thing without you having to
+think about it in this much detail. But when customizing indentation,
+it's helpful to understand the general indentation model being used.
+
+As you configure @ccmode{}, you might want to set the variable
+@code{c-echo-syntactic-information-p} to non-@code{nil} so that the
+syntactic context and calculated offset always is echoed in the
+minibuffer when you hit @kbd{TAB}.
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top
+@comment node-name, next, previous, up
+@chapter Customizing Indentation
+@cindex customization, indentation
+@cindex indentation
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The principal variable for customizing indentation is the style
+variable @code{c-offsets-alist}, which gives an @dfn{offset} (an
+indentation rule) for each syntactic symbol. Its structure and
+semantics are completely described in @ref{c-offsets-alist}. The
+various ways you can set the variable, including the use of the
+@ccmode{} style system, are described in @ref{Config Basics} and its
+sections, in particular @ref{Style Variables}.
+
+The simplest and most used kind of ``offset'' setting in
+@code{c-offsets-alist} is in terms of multiples of
+@code{c-basic-offset}:
+
+@defopt c-basic-offset
+@vindex basic-offset (c-)
+This style variable holds the basic offset between indentation levels.
+It's factory default is 4, but all the built-in styles set it
+themselves, to some value between 2 (for @code{gnu} style) and 8 (for
+@code{bsd}, @code{linux}, and @code{python} styles).
+@end defopt
+
+The most flexible ``offset'' setting you can make in
+@code{c-offsets-alist} is a line-up function (or even a list of them),
+either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one
+you write yourself (@pxref{Custom Line-Up}).
+
+Finally, in @ref{Other Indentation} you'll find the tool of last
+resort: a hook which is called after a line has been indented. You
+can install functions here to make ad-hoc adjustments to any line's
+indentation.
+
+@menu
+* c-offsets-alist::
+* Interactive Customization::
+* Line-Up Functions::
+* Custom Line-Up::
+* Other Indentation::
+@end menu
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation
+@comment node-name, next, previous, up
+@section c-offsets-alist
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This section explains the structure and semantics of the style
+variable @code{c-offset-alist}, the principal variable for configuring
+indentation. Details of how to set it up, and its relationship to
+@ccmode{}'s style system are given in @ref{Style Variables}.
+
+@defopt c-offsets-alist
+@vindex offsets-alist (c-)
+This is an alist which associates an offset with each syntactic
+symbol. This @dfn{offset} is a rule specifying how to indent a line
+whose syntactic context matches the symbol. @xref{Syntactic
+Analysis}.
+
+Note that the buffer-local binding of this alist in a @ccmode{} buffer
+contains an entry for @emph{every} syntactic symbol. Its global
+binding and its settings within style specifications usually contain
+only a few entries. @xref{Style Variables}.
+
+The offset specification associated with any particular syntactic
+symbol can be an integer, a variable name, a vector, a function or
+lambda expression, a list, or one of the following special symbols:
+@code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The
+meanings of these values are described in detail below.
+
+Here is an example fragment of a @code{c-offsets-alist}, showing some
+of these kinds of offsets:
+
+@example
+((statement . 0)
+ (substatement . +)
+ (cpp-macro . [0])
+ (topmost-intro-cont . c-lineup-topmost-intro-cont)
+ (statement-block-intro . (add c-lineup-whitesmith-in-block
+ c-indent-multi-line-block))
+ @dots{}
+@*)
+@end example
+@end defopt
+
+@deffn Command c-set-offset (@kbd{C-c C-o})
+@findex set-offset (c-)
+@kindex C-c C-o
+This command changes the entry for a syntactic symbol in the current
+binding of @code{c-offsets-alist}, or it inserts a new entry if there
+isn't already one for that syntactic symbol.
+
+You can use @code{c-set-offsets} interactively within a @ccmode{}
+buffer to make experimental changes to your indentation settings.
+@kbd{C-c C-o} prompts you for the syntactic symbol to change
+(defaulting to that of the current line) and the new offset
+(defaulting to the current offset).
+
+@code{c-set-offsets} takes two arguments when used programmatically:
+@var{symbol}, the syntactic element symbol to change and @var{offset},
+the new offset for that syntactic element. You can call the command
+in your @file{.emacs} to change the global binding of
+@code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a
+hook function to make changes from the current style. @ccmode{}
+itself uses this function when initializing styles.
+@end deffn
+
+@cindex offset specification
+The ``offset specifications'' in @code{c-offsets-alist} can be any of
+the following:
+
+@table @asis
+@item An integer
+The integer specifies a relative offset. All relative
+offsets@footnote{The syntactic context @code{@w{((defun-block-intro
+2724) (comment-intro))}} would likely have two relative offsets.} will
+be added together and used to calculate the indentation relative to an
+anchor position earlier in the buffer. @xref{Indentation
+Calculation}, for details. Most of the time, it's probably better to
+use one of the special symbols like @code{+} than an integer (apart
+from zero).
+
+@item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}
+These special symbols describe a relative offset in multiples of
+@code{c-basic-offset}:
+
+By defining a style's indentation in terms of @code{c-basic-offset},
+you can change the amount of whitespace given to an indentation level
+while maintaining the same basic shape of your code. Here are the
+values that the special symbols correspond to:
+
+@table @code
+@item +
+@code{c-basic-offset} times 1
+@item -
+@code{c-basic-offset} times -1
+@item ++
+@code{c-basic-offset} times 2
+@item --
+@code{c-basic-offset} times -2
+@item *
+@code{c-basic-offset} times 0.5
+@item /
+@code{c-basic-offset} times -0.5
+@end table
+
+@item A vector
+The first element of the vector, an integer, sets the absolute
+indentation column. This will override any previously calculated
+indentation, but won't override relative indentation calculated from
+syntactic elements later on in the syntactic context of the line being
+indented. @xref{Indentation Calculation}. Any elements in the vector
+beyond the first will be ignored.
+
+@item A function or lambda expression
+The function will be called and its return value will in turn be
+evaluated as an offset specification. Functions are useful when more
+context than just the syntactic symbol is needed to get the desired
+indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for
+details about them.
+
+@item A symbol with a variable binding
+If the symbol also has a function binding, the function takes
+precedence over the variable. Otherwise the value of the variable is
+used. It must be an integer (which is used as relative offset) or a
+vector (an absolute offset).
+
+@item A list
+The offset can also be a list containing several offset
+specifications; these are evaluated recursively and combined. A list
+is typically only useful when some of the offsets are line-up
+functions. A common strategy is calling a sequence of functions in
+turn until one of them recognizes that it is appropriate for the
+source line and returns a non-@code{nil} value.
+
+@code{nil} values are always ignored when the offsets are combined.
+The first element of the list specifies the method of combining the
+non-@code{nil} offsets from the remaining elements:
+
+@table @code
+@item first
+Use the first offset that doesn't evaluate to @code{nil}. Subsequent
+elements of the list don't get evaluated.
+@item min
+Use the minimum of all the offsets. All must be either relative or
+absolute - they can't be mixed.
+@item max
+Use the maximum of all the offsets. All must be either relative or
+absolute - they can't be mixed.
+@item add
+Add all the evaluated offsets together. Exactly one of them may be
+absolute, in which case the result is absolute. Any relative offsets
+that preceded the absolute one in the list will be ignored in that case.
+@end table
+
+As a compatibility measure, if the first element is none of the above
+then it too will be taken as an offset specification and the whole list
+will be combined according to the method @code{first}.
+@end table
+
+@vindex c-strict-syntax-p
+@vindex strict-syntax-p (c-)
+If an offset specification evaluates to @code{nil}, then a relative
+offset of 0 (zero) is used@footnote{There is however a variable
+@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
+error to be signaled in that case. It's now considered obsolete since
+it doesn't work well with some of the alignment functions that returns
+@code{nil} instead of zero. You should therefore leave
+@code{c-strict-syntax-p} set to @code{nil}.}.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation
+@comment node-name, next, previous, up
+@section Interactive Customization
+@cindex customization, interactive
+@cindex interactive customization
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+As an example of how to customize indentation, let's change the
+style of this example@footnote{In this and subsequent examples, the
+original code is formatted using the @samp{gnu} style unless otherwise
+indicated. @xref{Styles}.}:
+
+@example
+@group
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+@end group
+@end example
+
+@noindent
+to:
+
+@example
+@group
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+@end group
+@end example
+
+In other words, we want to change the indentation of braces that open a
+block following a condition so that the braces line up under the
+conditional, instead of being indented. Notice that the construct we
+want to change starts on line 4. To change the indentation of a line,
+we need to see which syntactic symbols affect the offset calculations
+for that line. Hitting @kbd{C-c C-s} on line 4 yields:
+
+@example
+((substatement-open 44))
+@end example
+
+@noindent
+so we know that to change the offset of the open brace, we need to
+change the indentation for the @code{substatement-open} syntactic
+symbol.
+
+To do this interactively, just hit @kbd{C-c C-o}. This prompts
+you for the syntactic symbol to change, providing a reasonable default.
+In this case, the default is @code{substatement-open}, which is just the
+syntactic symbol we want to change!
+
+After you hit return, @ccmode{} will then prompt you for the new
+offset value, with the old value as the default. The default in this
+case is @samp{+}, but we want no extra indentation so enter
+@samp{0} and @kbd{RET}. This will associate the offset 0 with the
+syntactic symbol @code{substatement-open}.
+
+To check your changes quickly, just hit @kbd{C-c C-q}
+(@code{c-indent-defun}) to reindent the entire function. The example
+should now look like:
+
+@example
+@group
+ 1: int add( int val, int incr, int doit )
+ 2: @{
+ 3: if( doit )
+ 4: @{
+ 5: return( val + incr );
+ 6: @}
+ 7: return( val );
+ 8: @}
+@end group
+@end example
+
+Notice how just changing the open brace offset on line 4 is all we
+needed to do. Since the other affected lines are indented relative to
+line 4, they are automatically indented the way you'd expect. For more
+complicated examples, this might not always work. The general approach
+to take is to always start adjusting offsets for lines higher up in the
+file, then reindent and see if any following lines need further
+adjustments.
+
+@c Move this bit to "Styles" (2005/10/7)
+@deffn Command c-set-offset symbol offset
+@findex set-offset (c-)
+@kindex C-c C-o
+This is the command bound to @kbd{C-c C-o}. It provides a convenient
+way to set offsets on @code{c-offsets-alist} both interactively (see
+the example above) and from your mode hook.
+
+It takes two arguments when used programmatically: @var{symbol} is the
+syntactic element symbol to change and @var{offset} is the new offset
+for that syntactic element.
+@end deffn
+@c End of MOVE THIS BIT.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation
+@comment node-name, next, previous, up
+@section Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+@cindex line-up function
+@cindex indentation function
+Often there are cases when a simple offset setting on a syntactic
+symbol isn't enough to get the desired indentation---for example, you
+might want to line up a closing parenthesis with the matching opening
+one rather than indenting relative to its ``anchor point''. @ccmode{}
+provides this flexibility with @dfn{line-up functions}.
+
+The way you associate a line-up function with a syntactic symbol is
+described in @ref{c-offsets-alist}. @ccmode{} comes with many
+predefined line-up functions for common situations. If none of these
+does what you want, you can write your own. @xref{Custom Line-Up}.
+Sometimes, it is easier to tweak the standard indentation by adding a
+function to @code{c-special-indent-hook} (@pxref{Other Indentation}).
+
+The line-up functions haven't been adapted for AWK buffers or tested
+with them. Some of them might work serendipitously. There shouldn't be
+any problems writing custom line-up functions for AWK mode.
+
+The calling convention for line-up functions is described fully in
+@ref{Custom Line-Up}. Roughly speaking, the return value is either an
+offset itself (such as @code{+} or @code{[0]}) or it's @code{nil},
+meaning ``this function is inappropriate in this case - try a
+different one''. @xref{c-offsets-alist}.
+
+The subsections below describe all the standard line-up functions,
+categorized by the sort of token the lining-up centres around. For
+each of these functions 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
+<--> @i{c-basic-offset}@c
+@end macro
+
+@macro sssTsssTBasicOffset
+<--><--> @i{c-basic-offset}@c
+@end macro
+
+@macro hereFn{func}
+<- @i{\func\}@c
+@end macro
+
+@c The TeX backend seems to insert extra spaces around the argument. :P
+@iftex
+@unmacro hereFn
+@macro hereFn{func}
+<-@i{\func\}@c
+@end macro
+@end iftex
+
+@menu
+* Brace/Paren Line-Up::
+* List Line-Up::
+* Operator Line-Up::
+* Comment Line-Up::
+* Misc Line-Up::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions
+@comment node-name, next, previous, up
+@subsection Brace and Parenthesis Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The line-up functions here calculate the indentation for braces,
+parentheses and statements within brace blocks.
+
+@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
-
- 1: static char* ingredients[] =
- 2: @{
- 3: "Ham",
- 4: "Salt",
- 5: NULL
- 6: @}
-
+main (int,
+ char **
+ ) @hereFn{c-lineup-close-paren}
@end group
@end example
-@cindex brace-list-open syntactic symbol
-@cindex brace-list-intro syntactic symbol
-@cindex brace-list-close syntactic symbol
-@cindex brace-list-entry syntactic symbol
-Following convention, line 2 in this example is assigned
-@code{brace-list-open} syntax, and line 3 is assigned
-@code{brace-list-intro} syntax. Likewise, line 6 is assigned
-@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.
+@noindent
+and
-@cindex brace-entry-open syntactic symbol
-Your static initializer might be initializing nested structures, for
-example:
@example
@group
-
- 1: struct intpairs[] =
- 2: @{
- 3: @{ 1, 2 @},
- 4: @{
- 5: 3,
- 6: 4
- 7: @}
- 8: @{ 1,
- 9: 2 @},
- 10: @{ 3, 4 @}
- 11: @}
-
+main (
+ int, char **
+) @hereFn{c-lineup-close-paren}
@end group
@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.
+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.
-External language definition blocks also have their own syntactic
-symbols. In this example:
-@example
-@group
+@workswith All @code{*-close} symbols.
+@end defun
- 1: extern "C"
- 2: @{
- 3: int thing_one( int );
- 4: int thing_two( double );
- 5: @}
+@comment ------------------------------------------------------------
-@end group
-@end example
+@anchor{c-lineup-arglist-close-under-paren}
+@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.
-@cindex extern-lang-open syntactic symbol
-@cindex extern-lang-close syntactic symbol
-@cindex inextern-lang syntactic symbol
-@cindex inclass syntactic symbol
-@noindent
-line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
-the @code{extern-lang-close} syntax. The analysis for line 3 yields:
-@code{((inextern-lang) (topmost-intro . 14))}, where
-@code{inextern-lang} is a modifier similar in purpose to @code{inclass}.
+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.
-Similarly, C++ namespace constructs have their own associated syntactic
-symbols. In this example:
-@example
-@group
+@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 ------------------------------------------------------------
- 1: namespace foo
- 2: @{
- 3: void xxx() @{@}
- 4: @}
+@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
-@cindex namespace-open syntactic symbol
-@cindex namespace-close syntactic symbol
-@cindex innamespace syntactic symbol
@noindent
-line 2 is given the @code{namespace-open} syntax, while line 4 is given
-the @code{namespace-close} syntax. The analysis for line 3 yields:
-@code{((innamespace) (topmost-intro . 17))}, where @code{innamespace} is
-a modifier similar in purpose to @code{inextern-lang} and @code{inclass}.
+and
-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
@group
-
- 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: @}
-
+if (n > 0)
+@{ @hereFn{c-indent-one-line-block}
+ m+=n; n=0;
+@}
@end group
@end example
-@cindex arglist-intro syntactic symbol
-@cindex arglist-close syntactic symbol
-Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
-the first line following the open parenthesis, and lines 7 and 14 are
-assigned @code{arglist-close} syntax since they contain the parenthesis
-that closes the argument list.
+The 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.
-@cindex arglist-cont-nonempty syntactic symbol
-@cindex arglist-cont syntactic symbol
-Lines that continue argument lists can be assigned one of two syntactic
-symbols. For example, Lines 2 and 17
-are assigned @code{arglist-cont-nonempty} syntax. What this means
-is that they continue an argument list, but that the line containing the
-parenthesis that opens the list is @emph{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.
+@workswith Almost all syntactic symbols, but most useful on the
+@code{-open} symbols.
+@end defun
-Note that there is no @code{arglist-open} syntax. This is because any
-parenthesis that opens an argument list, appearing on a separate line,
-is assigned the @code{statement-cont} syntax instead.
+@comment ------------------------------------------------------------
+
+@defun c-indent-multi-line-block
+@findex indent-multi-line-block (c-)
+Indent a multiline block @code{c-basic-offset} extra. E.g:
-A few miscellaneous syntactic symbols that haven't been previously
-covered are illustrated by this C++ example:
@example
@group
-
- 1: void Bass::play( int volume )
- 2: const
- 3: @{
- 4: /* this line starts a multi-line
- 5: * comment. This line should get `c' syntax */
- 6:
- 7: char* a_multiline_string = "This line starts a multi-line \
- 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: @}
-
+int *foo[] = @{
+ NULL,
+ @{17@}, @hereFn{c-indent-multi-line-block}
@end group
@end example
-The lines to note in this example include:
-
-@itemize @bullet
+@noindent
+and
-@cindex func-decl-cont syntactic symbol
-@item
-Line 2 is assigned the @code{func-decl-cont} syntax.
+@example
+@group
+int *foo[] = @{
+ NULL,
+ @{ @hereFn{c-indent-multi-line-block}
+ 17
+ @},
+ @sssTBasicOffset{}
+@end group
+@end example
-@cindex comment-intro syntactic symbol
-@item
-Line 4 is assigned both @code{defun-block-intro} @emph{and}
-@code{comment-intro} syntax.
+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.
-@cindex c syntactic symbol
-@item
-Line 5 is assigned @code{c} syntax.
+@workswith Almost all syntactic symbols, but most useful on the
+@code{-open} symbols.
+@end defun
-@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.
+@comment ------------------------------------------------------------
-@cindex string syntactic symbol
-@item
-Line 8 is assigned @code{string} syntax.
+@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 brace@footnote{Run-in
+style doesn't really work too well. You might need to write your own
+custom line-up functions to better support this style.}. E.g:
-@cindex label syntactic symbol
-@item
-Line 10 is assigned @code{label} syntax.
+@example
+@group
+int main()
+@{ puts ("Hello!");
+ return 0; @hereFn{c-lineup-runin-statements}
+@}
+@end group
+@end example
-@cindex block-open syntactic symbol
-@item
-Line 11 is assigned @code{block-open} syntax.
+If there is no statement after the opening brace to align with,
+@code{nil} is returned. This makes the function usable in list
+expressions.
-@cindex cpp-macro syntactic symbol
-@cindex cpp-macro-cont syntactic symbol
-@item
-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.
+@workswith The @code{statement} syntactic symbol.
+@end defun
-@cindex stream-op syntactic symbol
-@item
-Line 17 is assigned @code{stream-op} syntax.
+@comment ------------------------------------------------------------
-@end itemize
+@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.
-@cindex multi-line macros
-@cindex syntactic whitespace
-Multi-line C preprocessor macros are now (somewhat) supported. At least
-@ccmode{} now recognizes the fact that it is inside a multi-line macro,
-and it properly skips such macros as syntactic whitespace. In this
-example:
-@example
-@group
+@workswith @code{inlambda}, @code{inexpr-statement},
+@code{inexpr-class}.
+@end defun
- 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
+@comment ------------------------------------------------------------
-@end group
-@end example
-@noindent
-line 1 is given the syntactic symbol @code{cpp-macro}. This first line
-of a macro is always given this symbol. The second and subsequent lines
-(e.g. lines 2 through 5) are given the @code{cpp-macro-cont} syntactic
-symbol, with a relative buffer position pointing to the @code{#} which
-starts the macro definition.
+@defun c-lineup-after-whitesmith-blocks
+@findex lineup-after-whitesmith-blocks (c-)
+Compensate for Whitesmith style indentation of blocks. Due to the way
+@ccmode{} calculates anchor positions for normal lines inside blocks,
+this function is necessary for those lines to get correct Whitesmith
+style indentation. Consider the following examples:
-In Objective-C buffers, there are three additional syntactic symbols
-assigned to various message calling constructs. Here's an example
-illustrating these:
@example
@group
-
- 1: - (void)setDelegate:anObject
- 2: withStuff:stuff
- 3: @{
- 4: [delegate masterWillRebind:self
- 5: toDelegate:anObject
- 6: withExtraStuff:stuff];
- 7: @}
-
+int foo()
+ @{
+ a;
+ x; @hereFn{c-lineup-after-whitesmith-blocks}
@end group
@end example
-@cindex objc-method-intro syntactic symbol
-@cindex objc-method-args-cont syntactic symbol
-@cindex objc-method-call-cont syntactic symbol
-Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
-assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
-assigned @code{objc-method-call-cont} syntax.
-
-Java has a concept of anonymous classes, which may look something like
-this:
@example
@group
-
- 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: @}
-
+int foo()
+ @{
+ @{
+ a;
+ @}
+ x; @hereFn{c-lineup-after-whitesmith-blocks}
@end group
@end example
-@cindex inexpr-class syntactic symbol
-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}.
+The fact that the line with @code{x} is preceded by a Whitesmith style
+indented block in the latter case and not the first should not affect
+its indentation. But since CC Mode in cases like this uses the
+indentation of the preceding statement as anchor position, the @code{x}
+would in the second case be indented too much if the offset for
+@code{statement} was set simply to zero.
-There are a few occasions where a statement block may be used inside an
-expression. One is in C code using the gcc extension for this, e.g:
-@example
-@group
+This lineup function corrects for this situation by detecting if the
+anchor position is at an open paren character. In that case, it instead
+indents relative to the surrounding block just like
+@code{c-lineup-whitesmith-in-block}.
- 1: int res = (@{
- 2: int y = foo (); int z;
- 3: if (y > 0) z = y; else z = - y;
- 4: z;
- 5: @});
+@workswith @code{brace-list-entry}, @code{brace-entry-open},
+@code{statement}, @code{arglist-cont}.
+@end defun
-@end group
-@end example
+@comment ------------------------------------------------------------
-@cindex inexpr-statement syntactic symbol
-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.
+@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:
-In Pike code, there are a few other situations where blocks occur inside
-statements, as illustrated here:
@example
@group
-
- 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: @}
-
+something
+ @{
+ foo; @hereFn{c-lineup-whitesmith-in-block}
+ @}
@end group
@end example
-@cindex inlambda syntactic symbol
-@cindex lambda-intro-cont syntactic symbol
-Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
-by the @code{lambda} keyword. If the function argument list is put
-on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
-syntax. The function body is handled as an inline method body, with the
-addition of the @code{inlambda} syntactic symbol. This means that line
-6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
-@code{inline-close}@footnote{You might wonder why it doesn't get
-@code{inlambda} too. It's because the closing brace is relative to the
-opening brace, which stands on its own line in this example. If the
-opening brace was hanging on the previous line, then the closing brace
-would get the @code{inlambda} syntax too to be indented correctly.}.
-
-@cindex inexpr-statement syntactic symbol
-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.
+@noindent
+and
-@cindex knr-argdecl-intro syntactic symbol
-@cindex knr-argdecl syntactic symbol
-Two other syntactic symbols can appear in old style, non-prototyped C
-code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
@example
@group
-
- 1: int add_three_integers(a, b, c)
- 2: int a;
- 3: int b;
- 4: int c;
- 5: @{
- 6: return a + b + c;
- 7: @}
-
+something @{
+ foo; @hereFn{c-lineup-whitesmith-in-block}
+ @}
+@sssTBasicOffset{}
@end group
@end example
-Here, line 2 is the first line in an argument declaration list and so is
-given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
-(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
-syntax.
+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{inline-close}, @code{block-close}, @code{brace-list-close},
+@code{brace-list-intro}, @code{statement-block-intro},
+@code{arglist-intro}, @code{arglist-cont-nonempty},
+@code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass}
+and @code{inextern-lang}.
+@end defun
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Indentation Functions, Performance Issues, Syntactic Symbols, Top
+@node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions
@comment node-name, next, previous, up
-@chapter Indentation Functions
-@cindex indentation functions
-@cindex line-up functions
+@subsection List Line-Up Functions
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-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 a @dfn{indentation function} (a.k.a. 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
-
-@table @code
-
-@findex c-lineup-arglist
-@findex lineup-arglist (c-)
-@item c-lineup-arglist
-Line up the current argument line under the first argument.
-
-@workswith @code{arglist-cont-nonempty}.
-
-@findex c-lineup-arglist-intro-after-paren
-@findex lineup-arglist-intro-after-paren (c-)
-@item c-lineup-arglist-intro-after-paren
-Line up a line just after the open paren of the surrounding paren or
-brace block.
+The line-up functions here calculate the indentation for lines which
+form lists of items, usually separated by commas.
-@workswith @code{defun-block-intro}, @code{brace-list-intro},
-@code{statement-block-intro}, @code{statement-case-intro},
-@code{arglist-intro}.
+The function @ref{c-lineup-arglist-close-under-paren}, which is mainly
+for indenting a close parenthesis, is also useful for the lines
+contained within parentheses.
-@findex c-lineup-arglist-close-under-paren
-@findex lineup-arglist-close-under-paren (c-)
-@item c-lineup-arglist-close-under-paren
-Set e.g. 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.
+@defun c-lineup-arglist
+@findex lineup-arglist (c-)
+Line up the current argument line under the first argument.
-@workswith @code{defun-close}, @code{class-close}, @code{inline-close},
-@code{block-close}, @code{brace-list-close}, @code{arglist-close},
-@code{extern-lang-close}, @code{namespace-close} (for most of these, a
-zero offset will normally produce the same result, though).
+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 contain statement blocks, e.g:
-@findex c-lineup-close-paren
-@findex lineup-close-paren (c-)
-@item c-lineup-close-paren
-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 **
- ) // c-lineup-close-paren
-
+A_VERY_LONG_MACRO_NAME (@{
+ some (code, with + long, lines * in[it]);
+ @});
+@sssTBasicOffset{}
@end group
@end example
-@noindent
-and
-@example
-@group
-main (
- int, char **
-) // c-lineup-close-paren
+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.
-@end group
-@end example
+@workswith @code{arglist-cont-nonempty}, @code{arglist-close}.
+@end defun
-@workswith @code{defun-close}, @code{class-close}, @code{inline-close},
-@code{block-close}, @code{brace-list-close}, @code{arglist-close},
-@code{extern-lang-close}, @code{namespace-close}.
+@comment ------------------------------------------------------------
-@findex c-lineup-streamop
-@findex lineup-streamop (c-)
-@item c-lineup-streamop
-Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}).
+@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{stream-op}.
+@workswith @code{defun-block-intro}, @code{brace-list-intro},
+@code{statement-block-intro}, @code{statement-case-intro},
+@code{arglist-intro}.
+@end defun
-@findex c-lineup-multi-inher
+@comment ------------------------------------------------------------
+
+@defun c-lineup-multi-inher
@findex lineup-multi-inher (c-)
-@item c-lineup-multi-inher
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) // c-lineup-multi-inher
-
+ Bar (b) @hereFn{c-lineup-multi-inher}
@end group
@end example
+
@noindent
and
+
@example
@group
-
class Foo
: public Cyphr,
- public Bar // c-lineup-multi-inher
-
+ 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) // c-lineup-multi-inher
-
+ , Bar (b) @hereFn{c-lineup-multi-inher}
@end group
@end example
@workswith @code{inher-cont}, @code{member-init-cont}.
+@end defun
-@findex c-lineup-java-inher
+@comment ------------------------------------------------------------
+
+@defun c-lineup-java-inher
@findex lineup-java-inher (c-)
-@item c-lineup-java-inher
Line up Java implements and extends declarations. If class names
-follows on the same line as the @samp{implements}/@samp{extends}
+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 // c-lineup-java-inher
-
- <--> c-basic-offset
-
+ extends
+ Bar @hereFn{c-lineup-java-inher}
+ @sssTBasicOffset{}
@end group
@end example
+
@noindent
and
+
@example
@group
-
class Foo
extends Cyphr,
- Bar // c-lineup-java-inher
-
+ Bar @hereFn{c-lineup-java-inher}
@end group
@end example
@workswith @code{inher-cont}.
+@end defun
+
+@comment ------------------------------------------------------------
-@findex c-lineup-java-throws
+@defun c-lineup-java-throws
@findex lineup-java-throws (c-)
-@item c-lineup-java-throws
-Line up Java throws declarations. If exception names follows on the
+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 // c-lineup-java-throws
- Bar // c-lineup-java-throws
-
-<--><--> c-basic-offset
-
+ 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, // c-lineup-java-throws
- Vlod // c-lineup-java-throws
-
+ Bar, @hereFn{c-lineup-java-throws}
+ Vlod @hereFn{c-lineup-java-throws}
@end group
@end example
@workswith @code{func-decl-cont}.
+@end defun
-@findex c-indent-one-line-block
-@findex indent-one-line-block (c-)
-@item c-indent-one-line-block
-Indent a one line block @code{c-basic-offset} extra. E.g:
-@example
-@group
+@comment ------------------------------------------------------------
-if (n > 0)
- @{m+=n; n=0;@} // c-indent-one-line-block
-
-<--> c-basic-offset
+@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{<}.
-@end group
-@end example
-@noindent
-and
-@example
-@group
+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.
-if (n > 0)
-@{ // c-indent-one-line-block
- m+=n; n=0;
-@}
+@workswith @code{template-args-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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions
+@comment node-name, next, previous, up
+@subsection Operator Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The line-up functions here calculate the indentation for lines which
+start with an operator, by lining it up with something on the previous
+line.
+@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
-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.
+Only continuation lines like this are touched, @code{nil} is returned on
+lines which are the start of an argument.
-@workswith Almost all syntactic symbols, but most useful on the
-@code{-open} symbols.
+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-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 line-up functions. Example:
-@findex c-indent-multi-line-block
-@findex indent-multi-line-block (c-)
-@item c-indent-multi-line-block
-Indent a multi line block @code{c-basic-offset} extra. E.g:
@example
@group
+if ( x < 10
+ || at_limit (x, @hereFn{c-lineup-arglist-operators}
+ list) @hereFn{c-lineup-arglist-operators@r{ returns nil}}
+ )
+@end group
+@end example
-int *foo[] = @{
- NULL,
- @{17@}, // c-indent-multi-line-block
+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):
-@end group
+@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
-@noindent
-and
+
+@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
+@end defun
+
+@comment ------------------------------------------------------------
+
+@defun c-lineup-assignments
+@findex lineup-assignments (c-)
+Line up the current line after the assignment operator on the first line
+in the statement. If there isn't any, return nil to allow stacking with
+other line-up functions. If the current line contains an assignment
+operator 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-math
+@findex lineup-math (c-)
+Like @code{c-lineup-assignments} but indent with @code{c-basic-offset}
+if no assignment operator was found on the first line. I.e. this
+function is the same as specifying a list @code{(c-lineup-assignments
++)}. It's provided for compatibility with old configurations.
+
+@workswith @code{topmost-intro-cont}, @code{statement-cont},
+@code{arglist-cont}, @code{arglist-cont-nonempty}.
+@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; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}}
+@end group
+@end example
-int *foo[] = @{
- NULL,
- @{ // c-indent-multi-line-block
- 17
- @},
+In any other situation @code{nil} is returned to allow use in list
+expressions.
- <--> c-basic-offset
+@workswith @code{topmost-intro-cont}, @code{statement-cont},
+@code{arglist-cont}, @code{arglist-cont-nonempty}.
+@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
-The block may be surrounded by any kind of parenthesis characters.
-@code{nil} is returned if the line doesn't start with a multi line
-block, which makes the function usable in list expressions.
+@code{nil} is returned in other situations, to allow stacking with other
+lineup functions.
-@workswith Almost all syntactic symbols, but most useful on the
-@code{-open} symbols.
+@workswith @code{topmost-intro-cont}, @code{statement-cont},
+@code{arglist-cont}, @code{arglist-cont-nonempty}.
+@end defun
+
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions
+@comment node-name, next, previous, up
+@subsection Comment Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The lineup functions here calculate the indentation for several types
+of comment structure.
-@findex c-lineup-C-comments
+@defun c-lineup-C-comments
@findex lineup-C-comments (c-)
-@item c-lineup-C-comments
Line up C block comment continuation lines. Various heuristics are used
to handle most of the common comment styles. Some examples:
-@example
+@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:
@code{comment-start-skip} regexp.
**************************************************/
@end group
-
@end example
The style variable @code{c-comment-prefix-regexp} is used to recognize
line inside a comment.
@workswith The @code{c} syntactic symbol.
+@end defun
+
+@comment ------------------------------------------------------------
-@findex c-lineup-comment
+@defun c-lineup-comment
@findex lineup-comment (c-)
-@item c-lineup-comment
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.
-@vindex c-comment-only-line-offset
-@vindex comment-only-line-offset (c-)
-@code{c-comment-only-line-offset} specifies the extra offset for the
-line. It can contain an integer or a cons cell of the form
-@example
+@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
+(@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}})
+@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{(@r{@var{value}} . -1000)}.
+@end defopt
+
+@workswith @code{comment-intro}.
+@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Misc Line-Up, , Comment Line-Up, Line-Up Functions
+@comment node-name, next, previous, up
+@subsection Miscellaneous Line-Up Functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The line-up functions here are the odds and ends which didn't fit into
+any earlier category.
+
+@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-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[] = @hereFn{@r{The 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) @hereFn{@r{The 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 non-@code{nil}, 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-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 ------------------------------------------------------------
- (@r{<non-anchored-offset>} . @r{<anchored-offset>})
+@defun c-lineup-topmost-intro-cont
+@findex lineup-topmost-intro-cont (c-)
+Line up declaration continuation lines zero or one indentation
+step@footnote{This 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
-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{(@r{<value>} . -1000)}.
-
-@workswith @code{comment-intro}.
+and
-@findex c-lineup-runin-statements
-@findex lineup-runin-statements (c-)
-@item c-lineup-runin-statements
-Line up statements for coding standards which place the first statement
-in a block on the same line as the block opening brace@footnote{Run-in
-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 world!\");
- return 0; // c-lineup-runin-statements
+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
-If there is no statement after the opening brace to align with,
-@code{nil} is returned. This makes the function usable in list
-expressions.
+@noindent
+and
-@workswith The @code{statement} syntactic symbol.
+@example
+@group
+struct larch
+the_larch, @hereFn{c-lineup-topmost-intro-cont}
+ another_larch; @hereFn{c-lineup-topmost-intro-cont}
+@end group
+@end example
-@findex c-lineup-math
-@findex lineup-math (c-)
-@item c-lineup-math
-Line up the current line 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}.
+@end defun
-@workswith @code{statement-cont}.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation
+@comment node-name, next, previous, up
+@section Custom Line-Up Functions
+@cindex customization, indentation functions
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@findex c-lineup-template-args
-@findex lineup-template-args (c-)
-@item c-lineup-template-args
-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{<}.
+The most flexible way to customize indentation is by writing custom
+line-up functions, and associating them with specific syntactic
+symbols (@pxref{c-offsets-alist}). Depending on the effect you want,
+it might be better to write a @code{c-special-indent-hook} function
+rather than a line-up function (@pxref{Other Indentation}).
+
+@ccmode{} comes with an extensive set of predefined line-up functions,
+not all of which are used by the default styles. So there's a good
+chance the function you want already exists. @xref{Line-Up
+Functions}, for a list of them. If you write your own line-up
+function, it's probably a good idea to start working from one of these
+predefined functions, which can be found in the file
+@file{cc-align.el}. If you have written a line-up function that you
+think is generally useful, you're very welcome to contribute it;
+please contact @email{bug-cc-mode@@gnu.org}.
+
+ Line-up functions are passed a single argument, the syntactic
+element (see below). The return value is a @code{c-offsets-alist}
+offset specification: for example, an integer, a symbol such as
+@code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful
+when the offset specification for a syntactic element is a list
+containing the line-up function (@pxref{c-offsets-alist}).}, or even
+another line-up function. Full details of these are in
+@ref{c-offsets-alist}.
+
+Line-up functions must not move point or change the content of the
+buffer (except temporarily). They are however allowed to do
+@dfn{hidden buffer changes}, i.e. setting text properties for caching
+purposes etc. Buffer undo recording is disabled while they run.
+
+The syntactic element passed as the parameter to a line-up function is
+a cons cell of the form
-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.
+@example
+(@r{@var{syntactic-symbol}} . @r{@var{anchor-position}})
+@end example
-@workswith @code{template-args-cont}.
+@noindent
+@c FIXME!!! The following sentence might be better omitted, since the
+@c information is in the cross reference "Syntactic Analysis". 2005/10/2.
+where @var{syntactic-symbol} is the symbol that the function was
+called for, and @var{anchor-position} is the anchor position (if any)
+for the construct that triggered the syntactic symbol
+(@pxref{Syntactic Analysis}). This cons cell is how the syntactic
+element of a line used to be represented in @ccmode{} 5.28 and
+earlier. Line-up functions are still passed this cons cell, so as to
+preserve compatibility with older configurations. In the future, we
+may decide to convert to using the full list format---you can prepare
+your setup for this by using the access functions
+(@code{c-langelem-sym}, etc.) described below.
+
+@vindex c-syntactic-element
+@vindex syntactic-element (c-)
+@vindex c-syntactic-context
+@vindex syntactic-context (c-)
+Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more
+info in the syntactic element - typically other positions that can be
+interesting besides the anchor position. That info can't be accessed
+through the passed argument, which is a cons cell. Instead, you can
+get this information from the variable @code{c-syntactic-element},
+which is dynamically bound to the complete syntactic element. The
+variable @code{c-syntactic-context} might also be useful - it gets
+dynamically bound to the complete syntactic context. @xref{Custom
+Braces}.
+
+@ccmode{} provides a few functions to access parts of syntactic
+elements in a more abstract way. Besides making the code easier to
+read, they also hide the difference between the old cons cell form
+used in the line-up function argument and the new list form used in
+@code{c-syntactic-element} and everywhere else. The functions are:
+
+@defun c-langelem-sym langelem
+@findex langelem-sym (c-)
+Return the syntactic symbol in @var{langelem}.
+@end defun
+
+@defun c-langelem-pos langelem
+@findex langelem-pos (c-)
+Return the anchor position in @var{langelem}, or nil if there is none.
+@end defun
+
+@defun c-langelem-col langelem &optional preserve-point
+@findex langelem-col (c-)
+Return the column of the anchor position in @var{langelem}. Also move
+the point to that position unless @var{preserve-point} is
+non-@code{nil}.
+@end defun
+
+@defun c-langelem-2nd-pos langelem
+@findex langelem-2nd-pos (c-)
+Return the secondary position in @var{langelem}, or @code{nil} if there
+is none.
+
+Note that the return value of this function is always @code{nil} if
+@var{langelem} is in the old cons cell form. Thus this function is
+only meaningful when used on syntactic elements taken from
+@code{c-syntactic-element} or @code{c-syntactic-context}.
+@end defun
+
+Custom line-up 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 line-up function associated with it.
-@findex c-lineup-ObjC-method-call
-@findex lineup-ObjC-method-call (c-)
-@item c-lineup-ObjC-method-call
-For Objective-C code, line up selector args as @code{elisp-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.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Other Indentation, , Custom Line-Up, Customizing Indentation
+@comment node-name, next, previous, up
+@section Other Special Indentations
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@workswith @code{objc-method-call-cont}.
+Here are the remaining odds and ends regarding indentation:
-@findex c-lineup-ObjC-method-args
-@findex lineup-ObjC-method-args (c-)
-@item c-lineup-ObjC-method-args
-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.
+@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 code blocks. This minimum indentation is
+controlled by this style variable. The default value is 1.
+
+@findex c-gnu-impose-minimum
+@findex gnu-impose-minimum (c-)
+It's the function @code{c-gnu-impose-minimum} that enforces this minimum
+indentation. It must be present on @code{c-special-indent-hook} to
+work.
+@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{}. It is called only if
+@code{c-syntactic-indentation} is non-@code{nil} (which it is by
+default (@pxref{Indentation Engine Basics})). You can put a function
+on this hook to do any special indentation or ad hoc line adjustments
+your style dictates, such as adding extra indentation to constructors
+or destructor declarations in a class definition, etc. Sometimes it
+is better to write a custom Line-up Function instead (@pxref{Custom
+Line-Up}).
+
+When the indentation engine calls this hook, the variable
+@code{c-syntactic-context} is bound to the current syntactic context
+(i.e. what you would get by typing @kbd{C-c C-s} on the source line.
+@xref{Custom Braces}.). Note that you should not change point or mark
+inside a @code{c-special-indent-hook} function, i.e. you'll probably
+want to wrap your function in a @code{save-excursion}@footnote{The
+numerical value returned by @code{point} will change if you change the
+indentation of the line within a @code{save-excursion} form, but point
+itself will still be over the same piece of text.}.
+
+Setting @code{c-special-indent-hook} in style definitions is handled
+slightly differently from other variables---A style can only add
+functions to this hook, not remove them. @xref{Style Variables}.
+@end defopt
-@workswith @code{objc-method-args-cont}.
-@findex c-lineup-ObjC-method-args-2
-@findex lineup-ObjC-method-args-2 (c-)
-@item c-lineup-ObjC-method-args-2
-Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on
-the current line with the colon on the previous line.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Custom Macros, Odds and Ends, Customizing Indentation, Top
+@comment node-name, next, previous, up
+@chapter Customizing Macros
+@cindex macros
+@cindex preprocessor directives
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@workswith @code{objc-method-args-cont}.
+Normally, the lines in a multi-line macro are indented relative to
+eachother as though they were code. You can suppress this behaviour
+by setting the following user option:
-@findex c-lineup-inexpr-block
-@findex lineup-inexpr-block (c-)
-@item c-lineup-inexpr-block
-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.
+@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
-@workswith @code{inlambda}, @code{inexpr-statement},
-@code{inexpr-class}.
+@ccmode{} provides some tools to help keep the line continuation
+backslashes in macros neat and tidy. Their precise action is
+customized with these variables:
-@findex c-lineup-whitesmith-in-block
-@findex lineup-whitesmith-in-block (c-)
-@item c-lineup-whitesmith-in-block
-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
+@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 goes past this column, then the
+next tab stop (i.e. next multiple of @code{tab-width}) in that line is
+used as the alignment column for all the backslashes, so that they
+remain in a single column. However, if any lines go past
+@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.
+
+Don't ever set these variables to @code{nil}. If you want to disable
+the automatic alignment of backslashes, use
+@code{c-auto-align-backslashes}.
+@end defopt
+
+@defopt c-auto-align-backslashes
+@vindex auto-align-backslashes (c-)
+Align automatically inserted line continuation backslashes if
+non-@code{nil}. 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.
+
+If @code{c-auto-align-backslashes} is @code{nil}, automatically
+inserted backslashes are preceded by a single space, and backslashes
+get aligned only when you explicitly invoke the command
+@code{c-backslash-region} (@kbd{C-c C-\}).
+@end defopt
-something
- @{
- foo; // c-lineup-whitesmith-in-block
- @}
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Odds and Ends, Sample .emacs File, Custom Macros, Top
+@comment node-name, next, previous, up
+@chapter Odds and Ends
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@end group
-@end example
-@noindent
-and
-@example
-@group
+The stuff that didn't fit in anywhere else is documented here.
-something @{
- foo; // c-lineup-whitesmith-in-block
- @}
+@defopt c-require-final-newline
+@vindex require-final-newline (c-)
+Controls whether a final newline is enforced 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} (@pxref{Saving
+Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a
+language isn't present on the association list, CC Mode won't touch
+@code{require-final-newline} in buffers for that language.
-<--> c-basic-offset
+The default is to set @code{require-final-newline} to @code{t} in the
+languages that mandate that source files should end with newlines.
+These are C, C++ and Objective-C.
+@end defopt
-@end group
-@end example
+@defopt c-echo-syntactic-information-p
+@vindex echo-syntactic-information-p (c-)
+If non-@code{nil}, 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 non-@code{nil}, 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
-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}, @code{inclass}, @code{inextern-lang},
-@code{innamespace}.
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Sample .emacs File, Performance Issues, Odds and Ends, Top
+@comment node-name, next, previous, up
+@appendix Sample .emacs File
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@findex c-lineup-dont-change
-@findex lineup-dont-change (c-)
-@item c-lineup-dont-change
-This lineup function makes the line stay at whatever indentation it
-already has; think of it as an identity function for lineups. It is
-used for @code{cpp-macro-cont} lines.
+@verbatim
+;; Here's a sample .emacs file fragment that might help you along the
+;; way. Just copy this region and paste it into your .emacs file.
+;; You might want to change some of the actual values.
-@workswith Any syntactic symbol.
+;; Make some non-standard key bindings. We can put these in
+;; c-mode-base-map because c-mode-map, c++-mode-map, and so on,
+;; inherit from it.
+(defun my-c-initialization-hook ()
+ (define-key c-mode-base-map "\C-m" 'c-context-line-break)
+ (define-key c-mode-base-map [?\C-\M-a] 'c-beginning-of-defun)
+ (define-key c-mode-base-map [?\C-\M-e] 'c-end-of-defun)
+(add-hook 'c-initialization-hook 'my-c-initialization-hook)
-@end table
+;; offset customizations not in my-c-style
+;; This will take precedence over any setting of the syntactic symbol
+;; made by a style.
+(setq c-offsets-alist '((member-init-intro . ++)))
+
+;; Create my personal style.
+(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")
+(c-add-style "PERSONAL" my-c-style)
+;; Customizations for all modes in CC Mode.
+(defun my-c-mode-common-hook ()
+ ;; set my personal style for the current buffer
+ (c-set-style "PERSONAL")
+ ;; other customizations
+ (setq tab-width 8
+ ;; this will make sure spaces are used instead of tabs
+ indent-tabs-mode nil)
+ ;; we like auto-newline, but not hungry-delete
+ (c-toggle-auto-newline 1))
+(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
+@end verbatim
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Performance Issues, Limitations and Known Bugs, Indentation Functions, Top
+@node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top
@comment node-name, next, previous, up
-@chapter Performance Issues
-@cindex performance issues
+@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@footnote{such as the output of @code{lex(1)}!}
-can cause @ccmode{} to perform fairly badly.
-This section identifies some of the coding styles to watch out for, and
-suggests some workarounds that you can use to improve performance.
+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 is sometimes 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.
-The farther this position is from the current insertion point, the
-slower the mode gets. Some coding styles can even force @ccmode{}
-to scan from the beginning of the buffer for every line of code!
+position higher up in the buffer from which to begin a forward scan
+(it's typically an opening or closing parenthesis 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 construct@footnote{E.g. 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 insist on hanging 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.
+In earlier versions of @ccmode{}, we used to recommend putting the
+opening brace of a top-level construct@footnote{E.g. a function in C,
+or outermost class definition in C++ or Java.} into the leftmost
+column. Earlier still, this used to be a rigid Emacs constraint, as
+embodied in the @code{beginning-of-defun} function. @ccmode now
+caches syntactic information much better, so that the delay caused by
+searching for such a brace when it's not in column 0 is minimal,
+except perhaps when you've just moved a long way inside the file.
+Don't forget to rebind @kbd{C-M-a} and @kbd{C-M-e} to the @ccmode{}
+functions @code{beginning-of-defun} and @code{end-of-defun} if you're
+going to be hanging your braces! @xref{Sample .emacs File}.
+@findex defun-prompt-regexp
@vindex c-Java-defun-prompt-regexp
@vindex Java-defun-prompt-regexp (c-)
-A special note about @code{defun-prompt-regexp} in Java mode: while much
-of the early sample Java code seems to encourage a style where the brace
-that opens a class is hung on the right side of the line, this is not a
-good style to pursue in Emacs. @ccmode{} comes with a variable
+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 constant
@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 hang@footnote{This
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 rely on @code{defun-prompt-regexp} will definitely slow
-things down anyway because you'll be doing regular expression searches
-for every line you indent, so you're probably screwed either way!
+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-)
-Another alternative for XEmacs users, is to set the variable
+XEmacs users can set the variable
@code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This
tells @ccmode{} to use XEmacs-specific built-in functions which, in some
-circumstances, can locate the top-most opening brace much quicker than
+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 20.2 or 20.3 as of
-this writing 27-Apr-1998).
-
-You will probably notice pathological behavior from @ccmode{} when
-working in files containing large amounts of C preprocessor macros.
-This is because Emacs cannot skip backwards over these lines as quickly
-as it can comments.
-
-@vindex c-recognize-knr-p
-@vindex recognize-knr-p (c-)
-Previous versions of @ccmode{} had potential performance problems
-when recognizing K&R style function argument declarations. This was
-because there are ambiguities in the C syntax when K&R style argument
-lists are used@footnote{It is hard to distinguish them from top-level
-declarations.}. @ccmode{} has adopted BOCM's convention for
-limiting the search: it assumes that argdecls are indented at least one
-space, and that the function headers are not indented at all. With
-current versions of @ccmode{}, user customization of
-@code{c-recognize-knr-p} is deprecated. Just don't put argdecls in
-column zero!
-
-@cindex @file{cc-lobotomy.el} file
-@vindex cc-lobotomy-pith-list
-You might want to investigate the speed-ups contained in the
-file @file{cc-lobotomy.el}, which comes as part of the @ccmode{}
-distribution, but is completely unsupported.
-As mentioned previous, @ccmode{} always trades speed for accuracy,
-however it is recognized that sometimes you need speed and can sacrifice
-some accuracy in indentation. The file @file{cc-lobotomy.el} contains
-hacks that will ``dumb down'' @ccmode{} in some specific ways, making
-that trade-off of accurancy for speed. I won't go into details of its
-use here; you should read the comments at the top of the file, and look
-at the variable @code{cc-lobotomy-pith-list} for details.
+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
+@node Limitations and Known Bugs, FAQ, Performance Issues, Top
@comment node-name, next, previous, up
-@chapter Limitations and Known Bugs
+@chapter Limitations and Known Bugs
@cindex limitations
@cindex bugs
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@itemize @bullet
@item
-Re-indenting large regions or expressions can be slow.
+There is no way to apply auto newline settings (@pxref{Auto-newlines})
+on already typed lines. That's only a feature to ease interactive
+editing.
-@findex c-indent-exp
-@findex indent-exp (c-)
-@item
-@code{c-indent-exp} has not been fully optimized. It essentially
-equivalent to hitting @kbd{TAB} (@code{c-indent-command}) on every
-line. Some information is cached from line to line, but such caching
-invariable causes inaccuracies in analysis in some bizarre situations.
+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.
-@vindex signal-error-on-buffer-boundary
-@item
-XEmacs versions from 19.15 until (as of this writing 12-Mar-1998) 20.4
-contain a variable called @code{signal-error-on-buffer-boundary}. This
-was intended 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 had the
-deleterious side effect of breaking many built-in primitive functions.
-Most users will not be affected since they never change the value of
-this variable. @strong{Do not set this variable to @code{nil}}; you
-will cause serious problems in @ccmode{} and probably other XEmacs
-packages! As of at least XEmacs 20.4, the effects this variable tried
-to correct have been fixed in other, better ways.
+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
+The support for C++ templates (in angle brackets) is not yet complete.
+When a non-nested template is used in a declaration, @ccmode{} indents
+it and font-locks it OK. Templates used in expressions, and nested
+templates do not fare so well. Sometimes a workaround is to refontify
+the expression after typing the closing @samp{>}.
@end itemize
-
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Frequently Asked Questions, Getting the Latest CC Mode Release, Limitations and Known Bugs, Top
+@node FAQ, Updating CC Mode, Limitations and Known Bugs, Top
@comment node-name, next, previous, up
@appendix Frequently Asked Questions
-@cindex frequently asked questions
-@cindex FAQ
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@kindex C-x h
-@kindex C-M-\
-@kindex C-M-x
-@kindex C-M-q
-@kindex C-M-u
+@itemize @bullet
+@item
+@emph{How can I change the indent level from 4 spaces to 2 spaces?}
+
+Set the variable @code{c-basic-offset}. @xref{Getting Started}.
+
+@item
@kindex RET
@kindex C-j
-@quotation
-
-@strong{Q.} @emph{How do I re-indent the whole file?}
+@emph{Why doesn't the @kbd{RET} key indent the new line?}
-@strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole
-buffer. Then hit @kbd{C-M-\}.
+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-initialization-hook}:
-@sp 1
-@strong{Q.} @emph{How do I re-indent the entire function?
-@kbd{C-M-x} doesn't work.}
+@example
+(define-key c-mode-base-map "\C-m" 'c-context-line-break)
+@end example
-@strong{A.} @kbd{C-M-x} is reserved for future Emacs use.
-To re-indent the entire function hit @kbd{C-c C-q}.
+@xref{Getting Started}. This is a very common question. If you want
+this to be the default behavior, don't lobby us, lobby RMS! @t{:-)}
-@sp 1
-@strong{Q.} @emph{How do I re-indent the current block?}
+@item
+@emph{How do I stop my code jumping all over the place when I type?}
-@strong{A.} First move to the brace which opens the block with
-@kbd{C-M-u}, then re-indent that expression with
-@kbd{C-M-q}.
+Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting
+Started}.
-@sp 1
-@strong{Q.} @emph{Why doesn't the @kbd{RET} key indent the new line?}
+@item
+@kindex C-x h
+@kindex C-M-\
+@emph{How do I reindent the whole file?}
-@strong{A.} 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
+Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit
+@kbd{C-M-\}. @xref{Indentation Commands}.
-(define-key c-mode-base-map "\C-m" 'c-context-line-break)
+@item
+@kindex C-M-q
+@kindex C-M-u
+@emph{How do I reindent the current block?}
-@end example
+First move to the brace which opens the block with @kbd{C-M-u}, then
+reindent that expression with @kbd{C-M-q}. @xref{Indentation
+Commands}.
-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?}
-@sp 1
-@strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)}
-in my @file{.emacs} file but I get an error saying that
-@code{c-set-offset}'s function definition is void.}
+This means that @ccmode{} hasn't yet been loaded into your Emacs
+session by the time the @code{c-set-offset} call is 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-initialization-hook} (@pxref{CC Hooks}), or simply
+modify @code{c-offsets-alist} directly:
-@strong{A.} 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
-@sp 1
-@strong{Q.} @emph{How do I make strings, comments, keywords, and other
-constructs appear in different colors, or in bold face, etc.?}
-
-@strong{A.} ``Syntax Colorization'' is a standard Emacs feature,
-controlled by @code{font-lock-mode}. @ccmode{} does not contain
-font-lock definitions for any of its supported languages.
-
-@sp 1
-@strong{Q.} @emph{@kbd{M-a} 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?}
-
-@strong{A.} 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.
-
-@sp 1
-@strong{Q.} @emph{Whenever I try to indent a line or type an
-``electric'' key such as @kbd{;}, @kbd{@{}, or @kbd{@}}, I get an error
-that look like this: @code{Invalid function: (macro . #[...}. What
-gives?}
-
-@strong{A.} This is a common error when @ccmode{} hasn't been compiled
-correctly, especially under Emacs 19.34@footnote{Technically, it's
-because some macros 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 macros as functions, 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).
+@ifset XEMACS
+@xref{Defuns,,, xemacs, XEmacs User's Manual}, for details.
+@end ifset
+@ifclear XEMACS
+@xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details
+(@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual).
+@end ifclear
+
+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.1 it became possible to turn it off@footnote{Using the variable
+@code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so
+there since it's got its own system to keep track of blocks.
-@end quotation
+@end itemize
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Getting the Latest CC Mode Release, Mailing Lists and Submitting Bug Reports, Frequently Asked Questions, Top
+@node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top
@comment node-name, next, previous, up
@appendix Getting the Latest CC Mode Release
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@ccmode{} is standard with all versions of Emacs since 19.34 and of
-XEmacs since 19.16.
+@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
+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 via the Web at:
-
-@example
-@group
+compatibility, etc. are all available on the web site:
- @uref{http://cc-mode.sourceforge.net/}
-
-@end group
-@end example
-
-@emph{Old URLs, including the FTP URLs, should no longer be used.}
-
-There are many files under these directories; you can pick up the entire
-distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of
-the individual files, including PostScript documentation.
+@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
+@node Mailing Lists and Bug Reports, Command and Function Index, Updating CC Mode, Top
@comment node-name, next, previous, up
@appendix Mailing Lists and Submitting Bug Reports
-@cindex mailing lists
-@cindex reporting bugs
@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} (@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.
+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 @code{-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.
+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 triggers the bug and include it in your report.
@cindex bug report mailing list
-Bug reports are now sent to the following email addresses:
-@email{bug-cc-mode@@gnu.org} and @email{bug-gnu-emacs@@gnu.org}; the
-latter is mirrored on the Usenet newsgroup @code{gnu.emacs.bug}. You
-can send other questions and suggestions (kudos? @t{;-)} to
-@email{bug-cc-mode@@gnu.org}.
+Bug reports should be 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}. 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, Concept Index, Mailing Lists and Submitting Bug Reports, Top
-@comment node-name, next, previous, up
-@appendix Sample .emacs file
+@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},
+@code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++},
+@code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools},
+@code{comp.lang.idl}, and @code{comp.lang.awk}.
+@c There is no newsgroup for Pike. :-(
+
+@c Removed the tentative node "Mode Initialization" from here, 2005/8/27.
@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 Concept Index, Command Index, Sample .emacs File, Top
+@node Command and Function Index, Variable Index, Mailing Lists and Bug Reports, Top
@comment node-name, next, previous, up
-@unnumbered Concept Index
+@unnumbered Command and Function Index
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@printindex cp
+Since most @ccmode{} commands are prepended with the string
+@samp{c-}, each appears under its @code{c-@var{thing}} name and its
+@code{@var{thing} (c-)} name.
+@iftex
+@sp 2
+@end iftex
+@printindex fn
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Command Index, Key Index, Concept Index, Top
+@node Variable Index, Concept and Key Index, Command and Function Index, Top
@comment node-name, next, previous, up
-@unnumbered Command Index
+@unnumbered Variable Index
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-Since most @ccmode{} commands are prepended with the string
-@samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
-@code{@var{<thing>} (c-)} name.
+Since most @ccmode{} variables are prepended with the string
+@samp{c-}, each appears under its @code{c-@var{thing}} name and its
+@code{@var{thing} (c-)} name.
@iftex
@sp 2
@end iftex
-@printindex fn
+@printindex vr
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Key Index, Variable Index, Command Index, Top
+@node Concept and Key Index, , Variable Index, Top
@comment node-name, next, previous, up
-@unnumbered Key Index
+@unnumbered Concept and Key Index
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@printindex ky
+@printindex cp
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Variable Index, , Key Index, Top
-@comment node-name, next, previous, up
-@unnumbered Variable Index
+@comment Epilogue.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-Since most @ccmode{} variables are prepended with the string
-@samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
-@code{@var{<thing>} (c-)} name.
-@iftex
-@sp 2
-@end iftex
-@printindex vr
-
@iftex
@page
@summarycontents
@end iftex
@bye
+
+@ignore
+ arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0
+@end ignore