root/trunk/man/cc-mode.texi

\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

@setfilename  ../info/ccmode
@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
@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@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 Combine key, syntactic symbol and concept indices into one.
@syncodeindex ss cp
@syncodeindex ky cp

@copying
This manual is for CC Mode in Emacs.

Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
2003, 2004, 2005, 2006, 2007, 2008  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.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
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying

@comment Info directory entry for use by install-info. The indentation
@comment here is by request from the FSF folks.
@dircategory Emacs
@direntry
* CC Mode: (ccmode).    Emacs mode for editing C, C++, Objective-C,
                        Java, Pike, AWK, and CORBA IDL code.
@end direntry

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment TeX title page
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@titlepage
@sp 10

@center @titlefont{CC Mode 5.31}
@sp 2
@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
@sp 2
@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie

@page
@vskip 0pt plus 1filll
@insertcopying

This manual was generated from $Revision$ of $RCSfile$, which can be
downloaded from
@url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/man/cc-mode.texi}.
@end titlepage

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment The Top node contains the master menu for the Info file.
@comment This appears only in the Info file, not the printed manual.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@node    Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up

@ifinfo
@top @ccmode{}

@ccmode{} is a GNU Emacs mode for editing files containing C, C++,
Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
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::
* 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::
* GNU Free Documentation License::
* Command and Function Index::
* Variable Index::
* Concept and Key Index::

@detailmenu
 --- The Detailed Node Listing ---

Commands

* Indentation Commands::
* Comment Commands::
* Movement Commands::
* Filling and Breaking::
* Minor Modes::
* Electric Keys::
* Auto-newlines::
* Hungry WS Deletion::
* Subword Movement::
* Other Commands::

Font Locking

* Font Locking Preliminaries::
* Faces::
* Doc Comments::
* AWK Mode Font Locking::

Configuration Basics

* CC Hooks::
* Style Variables::
* Styles::

Styles

* Built-in Styles::
* Choosing a Style::
* Adding Styles::
* File Styles::

Customizing Auto-newlines

* Hanging Braces::
* Hanging Colons::
* Hanging Semicolons and Commas::

Hanging Braces

* Custom Braces::

Indentation Engine Basics

* 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, Overview, Top, Top
@comment node-name, next, previous, up
@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 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
version 5.31.
@comment Release.py script can update the version number automatically

@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
Java, CORBA's Interface Definition Language, 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 objc-mode
@findex java-mode
@findex idl-mode
@findex pike-mode
@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
@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
provided.  This package is intended to be a replacement for
@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.

A special word of thanks goes to Krishna Padmasola for his work in
converting the original @file{README} file to Texinfo format.  I'd
also like to thank all the @ccmode{} victims who help enormously
during the early beta stages of @ccmode{}'s development.

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Overview, Getting Started, Introduction, Top
@comment  node-name,  next,  previous,  up@cindex organization of the manual
@chapter Overview of the Manual
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@noindent
The manual starts with several introductory chapters (including this
one).

@noindent
The next chunk of the manual describes the day to day @emph{use} of
@ccmode{} (as contrasted with how to customize it).

@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.

@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

@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.

@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.

@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

@noindent
The manual ends with ``this and that'', things that don't fit cleanly
into any of the previous chunks.

@itemize @bullet
@item
Two chapters discuss the performance of @ccmode{} and known
bugs/limitations.

@item
The FAQ contains a list of common problems and questions.

@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    Getting Started, Commands, Overview, Top
@comment node-name, next, previous, up
@chapter Getting Started
@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 might not
have the latest @ccmode{} release and might want to upgrade your copy
(see below).

You should probably start by skimming through the entire Commands chapter
(@pxref{Commands}) to get an overview of @ccmode{}'s capabilities.

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:

@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}:

@example
(setq c-basic-offset 6)
@end example

@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 available 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

@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.}:

@example
(setq-default c-electric-flag nil)
@end example

@noindent
Details of this and other similar ``Minor Modes'' appear in the
section @ref{Minor Modes}.

@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 would fail if the pertinent keymap didn't yet
exist---we thus need to delay the action until after @ccmode{} has
been loaded.  Put the following code into your @file{.emacs}:

@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
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

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
where @samp{XX} is the minor release number.
@end deffn

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Commands, Font Locking, Getting Started, Top
@comment node-name, next, previous, up
@chapter Commands
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

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.

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.


@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

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Indentation Commands, Comment Commands, Commands, Commands
@comment node-name, next, previous,up
@section Indentation Commands
@cindex indentation
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

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.

@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.

These commands indent code:

@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.

@code{c-indent-command} does different things, depending on the
setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
Basics}):

@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.

@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

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{}}.

@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

@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

@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

@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.

@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.

@item @kbd{C-c C-q} (@code{c-indent-defun})
@kindex C-c C-q
@findex c-indent-defun
@findex indent-defun (c-)
Indents the entire top-level function, class or macro definition
encompassing point.  It leaves point unchanged.  This function can't be
used to reindent a nested brace construct, such as a nested class or
function, or a Java method.  The top-level construct being reindented
must be complete, i.e. it must have both a beginning brace and an ending
brace.

@item @kbd{C-M-\} (@code{indent-region})
@kindex C-M-\
@findex indent-region
Indents an arbitrary region of code.  This is a standard Emacs command,
tailored for C code in a @ccmode{} buffer.  Note, of course, that point
and mark must delineate the region you want to indent.

@item @kbd{C-M-h} (@code{c-mark-function})
@kindex C-M-h
@findex c-mark-function
@findex mark-function (c-)
While not strictly an indentation command, this is useful for marking
the current top-level function or class definition as the current
region.  As with @code{c-indent-defun}, this command operates on
top-level constructs, and can't be used to mark say, a Java method.
@end table

These variables are also useful when indenting code:

@defopt 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    Comment Commands, Movement Commands, Indentation Commands, Commands
@comment node-name, next, previous, up
@section Comment Commands
@cindex comments (insertion of)
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@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 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

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Movement Commands, Filling and Breaking, Comment Commands, Commands
@comment node-name, next, previous, up
@section Movement Commands
@cindex movement
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@ccmode{} contains some useful commands for moving around in C code.

@table @asis
@item @kbd{C-M-a} (@code{c-beginning-of-defun})
@itemx @kbd{C-M-e} (@code{c-end-of-defun})
@findex c-beginning-of-defun
@findex c-end-of-defun

Move to the beginning or end of the current or next function.  Other
constructs (such as a structs or classes) which have a brace block
also count as ``functions'' here.  To move over several functions, you
can give these commands a repeat count.

The start of a function is at its header.  The end of the function is
after its closing brace, or after the semicolon of a construct (such
as a @code{struct}) which doesn't end at the brace.  These two
commands try to leave point at the beginning of a line near the actual
start or end of the function.  This occasionally causes point not to
move at all.

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.

@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 to the beginning or end of the current or next AWK defun.  These
commands 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.

@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.

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.

@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.

This key sequence is not bound in AWK Mode, which doesn't have
preprocessor statements.

@item @kbd{M-x c-up-conditional-with-else}
@findex c-up-conditional-with-else
@findex up-conditional-with-else (c-)
A variety of @code{c-up-conditional} that also stops at @samp{#else}
lines.  Normally those lines are ignored.

@item @kbd{M-x c-down-conditional}
@findex c-down-conditional
@findex down-conditional (c-)
Move 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.

@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
function stops at them when going forward, but not when going backward.

@item @kbd{M-x c-down-conditional-with-else}
@findex c-down-conditional-with-else
@findex down-conditional-with-else (c-)
A variety of @code{c-down-conditional} that also stops at @samp{#else}
lines.  Normally those lines are ignored.

@item @kbd{C-c C-p} (@code{c-backward-conditional})
@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.

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.

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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

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.

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.

@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})}.

@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.

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.

@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}.

@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.  In a
string, a backslash is inserted only if the string is within a
macro@footnote{In GCC, unescaped line breaks within strings are
valid.}.

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


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Minor Modes, Electric Keys, Filling and Breaking, Commands
@comment node-name, next, previous, up
@section Minor Modes
@cindex Minor Modes
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@ccmode{} contains several minor-mode-like features that you might
find useful while writing new code or editing old code:

@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

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}.

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.}.

Here are the commands to toggle these modes:

@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.

@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    Electric Keys, Auto-newlines, Minor Modes, Commands
@comment node-name, next, previous, up
@section Electric Keys and Keywords
@cindex electric characters
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

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 behavior described here by disabling
electric minor mode (@pxref{Minor Modes}).

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
@findex electric-pound (c-)
@vindex c-electric-pound-behavior
@vindex elect