comparison man/programs.texi @ 67676:76931aba1936

Amend the file for CC Mode 5.31. In particular, relax the injunction that all braces/parens at column zero start defuns.

67675:131310d593c0

place to set up customizations for that major mode.  @xref{Hooks}.

@node Defuns
@section Top-Level Definitions, or Defuns

  In Emacs, a major definition at the top level in the buffer is
called a @dfn{defun}.  The name comes from Lisp, but in Emacs we use
it for all languages.

  In most programming language modes, Emacs assumes that a defun is
any pair of parentheses (or braces, if the language uses braces this
way) that starts at the left margin.  For example, in C, the body of a
function definition is normally a defun, because the open-brace that
begins it is normally at the left margin.  A variable's initializer
can also count as a defun, if the open-brace that begins the
initializer is at the left margin.

  However, some language modes provide their own code for recognizing
defuns in a way that suits the language syntax and conventions better.

@menu

@node Left Margin Paren
@subsection Left Margin Convention

@cindex open-parenthesis in leftmost column
@cindex ( in leftmost column
  In most major modes, Emacs assumes that any opening delimiter found
at the left margin is the start of a top-level definition, or defun.
Therefore, @strong{never put an opening delimiter at the left margin
unless it should have that significance.}  For instance, never put an
open-parenthesis at the left margin in a Lisp file unless it is the
start of a top-level list.  Never put an open-brace or other opening
delimiter at the beginning of a line of C code unless it is at top
level.

  If you don't follow this convention, not only will you have trouble
when you explicitly use the commands for motion by defuns; other
features that use them will also give you trouble.  This includes
the indentation commands (@pxref{Program Indent}) and Font Lock
mode (@pxref{Font Lock}).

  The most likely problem case is when you want an opening delimiter
at the start of a line inside a string.  To avoid trouble, put an
escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some
other Lisp dialects) before the opening delimiter.  This will not
affect the contents of the string, but will prevent that opening
delimiter from starting a defun.  Here's an example:

@example
  (insert "Foo:
\(bar)
")
@end example

  To help you catch violations of this convention, Font Lock mode
highlights confusing opening delimiters (those that ought to be
quoted) in bold red.

  In the earliest days, the original Emacs found defuns by moving
upward a level of parentheses or braces until there were no more
levels to go up.  This always required scanning all the way back to
the beginning of the buffer, even for a small function.  To speed up
the operation, we changed Emacs to assume that any opening delimiter
at the left margin is the start of a defun.  This heuristic is nearly
always right, and avoids the need to scan back to the beginning of the
buffer.  However, it mandates following the convention described
above.

@node Moving by Defuns
@subsection Moving by Defuns
@cindex defuns

nonstandard indentation, the lines below will tend to follow it.  This
behavior is convenient in cases where you have overridden the standard
result of @key{TAB} because you find it unaesthetic for a particular
line.

  Remember that an open-parenthesis, open-brace or other opening delimiter
at the left margin is assumed by Emacs (including the indentation routines)
to be the start of a function.  Therefore, you must never have an opening
delimiter in column zero that is not the beginning of a function, not even
inside a string.  This restriction is vital for making the indentation
commands fast; you must simply accept it.  @xref{Left Margin Paren},
for more information on this.

  Normally, lines are indented with tabs and spaces.  If you want Emacs
to use spaces only, see @ref{Just Spaces}.

@node Multi-line Indent

@table @kbd
@item C-c . @key{RET} @var{style} @key{RET}
Select a predefined style @var{style} (@code{c-set-style}).
@end table

  A @dfn{style} is a named collection of customizations that can
be used in C mode and the related modes.  Emacs comes with several
predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
@code{stroustrup}, @code{linux}, @code{python}, @code{java},
@code{whitesmith}, @code{ellemtel}, @code{cc-mode}, and @code{user}.
Some of these styles are primarily intended for one language, but any
of them can be used with any of the languages supported by these
modes.  To find out what a style looks like, select it and reindent
some code, e.g., by typing @key{C-M-q} at the start of a function
definition.

@kindex C-c . @r{(C mode)}
@findex c-set-style
  To choose a style for the current buffer, use the command @kbd{C-c
.}.  Specify a style name as an argument (case is not significant).
This command affects the current buffer only, and it affects only
future invocations of the indentation commands; it does not reindent
the code in the buffer.  To reindent the whole buffer in the new
style, you can type @kbd{C-x h C-M-\}.

@vindex c-default-style
  You can also set the variable @code{c-default-style} to specify the
default style for various major modes.  Its value should be either the
style's name (a string) or an alist, in which each element specifies
one major mode and which indentation style to use for it.  For
example,

@example
(setq c-default-style
      '((java-mode . "java") (other . "gnu")))
@end example

@noindent
specifies an explicit choice for Java mode, and the default @samp{gnu}
style for the other C-like modes.  (These settings are actually the
defaults.)  This variable takes effect when you select one of the
C-like major modes; thus, if you specify a new default style for Java
mode, you can make it take effect in an existing Java mode buffer by
typing @kbd{M-x java-mode} there.

  The @code{gnu} style specifies the formatting recommended by the GNU
Project for C; it is the default, so as to encourage use of our
recommended style.

  @xref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for
more information on customizing indentation for C and related modes,
including how to override parts of an existing style and how to define
your own styles.

@node Parentheses
@section Commands for Editing with Parentheses

@kindex C-M-t
@findex transpose-sexps
  A somewhat random-sounding command which is nevertheless handy is
@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous
balanced expression across the next one.  An argument serves as a
repeat count, and a negative argument drags the previous balanced
expression backwards across those before it (thus canceling out the
effect of @kbd{C-M-t} with a positive argument).  An argument of zero,
rather than doing nothing, transposes the balanced expressions ending
at or after point and the mark.

@kindex C-M-@@
@kindex C-M-@key{SPC}
@findex mark-sexp
  To set the region around the next balanced expression in the buffer,
use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place
that @kbd{C-M-f} would move to.  @kbd{C-M-@@} takes arguments like
@kbd{C-M-f}.  In particular, a negative argument is useful for putting
the mark at the beginning of the previous balanced expression.  The
alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}.  If you use
this command repeatedly, or in Transient Mark mode whenever the mark
is active, it extends the region by one sexp each time.

  In languages that use infix operators, such as C, it is not possible
to recognize all balanced expressions as such because there can be
multiple possibilities at a given position.  For example, C mode does
not treat @samp{foo + bar} as a single expression, even though it

@item @kbd{C-x ;}
Set comment column (@code{comment-set-column}).
@item @kbd{C-M-j}
@itemx @kbd{M-j}
Like @key{RET} followed by inserting and aligning a comment
(@code{comment-indent-new-line}).
@item @kbd{M-x comment-region}
@itemx @kbd{C-c C-c} (in C-like modes)
Add or remove comment delimiters on all the lines in the region.
@end table

;;; And now, the first part of the function:
  ;; The following line adds one.
  (1+ x))           ; This line adds one.
@end example

  In C code, a comment preceded on its line by nothing but whitespace
is indented like a line of code.

@node Multi-Line Comments
@subsection Multiple Lines of Comments

@kindex C-M-j
@kindex M-j
@cindex blank lines in programs
@findex comment-indent-new-line
  If you are typing a comment and wish to continue it on another line,
you can use the command @kbd{C-M-j} or @kbd{M-j}
(@code{comment-indent-new-line}).  This terminates the comment you are
typing, creates a new blank line afterward, and begins a new comment
indented under the old one.  When Auto Fill mode is on, going past the
fill column while typing a comment causes the comment to be continued
in just this fashion.  If point is not at the end of the line when you
type the command, the text on the rest of the line becomes part of the
new comment line.

@kindex C-c C-c (C mode)
@findex comment-region
  To turn existing lines into comment lines, use the @kbd{M-x
comment-region} command.  It adds comment delimiters to the lines that start
in the region, thus commenting them out.  With a negative argument, it
does the opposite---it deletes comment delimiters from the lines in the
region.

  With a positive argument, @code{comment-region} duplicates the last
character of the comment start sequence it adds; the argument specifies
how many copies of the character to insert.  Thus, in Lisp mode,
@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line.  Duplicating
the comment delimiter is a way of calling attention to the comment.  It
can also affect how the comment is indented.  In Lisp, for proper
indentation, you should use an argument of two or three, if between defuns;
if within a defun, it must be three.

@node Options for Comments
@subsection Options Controlling Comments

@vindex comment-column

can hold the actual string to insert.

@vindex comment-multi-line
  The variable @code{comment-multi-line} controls how @kbd{C-M-j}
(@code{indent-new-comment-line}) behaves when used inside a comment.
Specifically, when @code{comment-multi-line} is @code{nil} (the
default value), the command inserts a comment terminator, begins a new
line, and finally inserts a comment starter.  Otherwise it does not
insert the terminator and starter, so it effectively continues the
current comment across multiple lines.  In languages that allow
multi-line comments, the choice of value for this variable is a matter
of taste.

@vindex comment-indent-function
  The variable @code{comment-indent-function} should contain a function
that will be called to compute the indentation for a newly inserted
comment or for aligning an existing comment.  It is set differently by

@kbd{M-a} except that it moves in the other direction
(@code{c-end-of-statement}).

@item M-x c-backward-into-nomenclature
@findex c-backward-into-nomenclature
Move point backward to beginning of a C++ nomenclature section or word.
With prefix argument @var{n}, move @var{n} times.  If @var{n} is
negative, move forward.  C++ nomenclature means a symbol name in the
style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter
begins a section or word.

In the GNU project, we recommend using underscores to separate words
within an identifier in C or C++, rather than using case distinctions.

@item M-x c-forward-into-nomenclature

@node Electric C
@subsection Electric C Characters

  In C mode and related modes, certain printing characters are
``electric''---in addition to inserting themselves, they also reindent
the current line, and optionally also insert newlines.  The
``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
@kbd{)}.

  Electric characters insert newlines only when the @dfn{auto-newline}
feature is enabled (indicated by @samp{/a} in the mode line after the
mode name).  This feature is controlled by the variable
@code{c-auto-newline}.  You can turn this feature on or off with the
command @kbd{C-c C-a}:

@table @kbd
@item C-c C-a
@kindex C-c C-a @r{(C mode)}
@findex c-toggle-auto-state
Toggle the auto-newline feature (@code{c-toggle-auto-state}).  With a
prefix argument, this command turns the auto-newline feature on if the
argument is positive, and off if it is negative.
@end table

  The colon character is electric because that is appropriate for a
single colon.  But when you want to insert a double colon in C++, the
electric behavior of colon is inconvenient.  You can insert a double
colon with no reindentation or newlines by typing @kbd{C-c :}:

inserted.

@vindex c-cleanup-list
   Electric characters can also delete newlines automatically when the
auto-newline feature is enabled.  This feature makes auto-newline more
acceptable, by deleting the newlines in the most common cases where you
do not want them.  Emacs can recognize several cases in which deleting a
newline might be desirable; by setting the variable
@code{c-cleanup-list}, you can specify @emph{which} of these cases that
should happen.  The variable's value is a list of symbols, each
describing one case for possible deletion of a newline.  Here are the
meaningful symbols, and their meanings:

@table @code
@item brace-catch-brace
Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the
entire construct on a single line.  The clean-up occurs when you type

@item list-close-comma
Clean up commas following braces in array and aggregate
initializers.  Clean-up occurs when you type the comma.

@item scope-operator
Clean up double colons which may designate a C++ scope operator, by
placing the colons together.  Clean-up occurs when you type the second
colon, but only when the two colons are separated by nothing but
whitespace.

@node Hungry Delete
@subsection Hungry Delete Feature in C
@cindex hungry deletion (C Mode)

  When the @dfn{hungry-delete} feature is enabled (indicated by
@samp{/h} or @samp{/ah} in the mode line after the mode name), a single
@key{DEL} command deletes all preceding whitespace, not just one space.
To turn this feature on or off, use @kbd{C-c C-d}:

@table @kbd
@item C-c C-d
@kindex C-c C-d @r{(C mode)}
@findex c-toggle-hungry-state
Toggle the hungry-delete feature (@code{c-toggle-hungry-state}).  With a
prefix argument, this command turns the hungry-delete feature on if the
argument is positive, and off if it is negative.

@item C-c C-t
@kindex C-c C-t @r{(C mode)}
@findex c-toggle-auto-hungry-state
Toggle the auto-newline and hungry-delete features, both at once
(@code{c-toggle-auto-hungry-state}).
@end table

@vindex c-hungry-delete-key
   The variable @code{c-hungry-delete-key} controls whether the
hungry-delete feature is enabled.

@node Other C Commands
@subsection Other Commands for C Mode

@table @kbd
@item M-x c-context-line-break
@findex c-context-line-break
This command inserts a line break and indents the new line in a manner
appropriate to the context.  In normal code, it does the work of
@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it
additionally inserts a @samp{\} at the line break, and within comments
it's like @kbd{M-j} (@code{c-indent-new-comment-line}).

@code{c-context-line-break} isn't bound to a key by default, but it
needs a binding to be useful.  The following code will bind it to
@kbd{C-j}.
@example
(define-key c-mode-base-map "\C-j" 'c-context-line-break)
@end example

@item C-M-h
Put mark at the end of a function definition, and put point at the
beginning (@code{c-mark-function}).

67676:76931aba1936

place to set up customizations for that major mode.  @xref{Hooks}.

@node Defuns
@section Top-Level Definitions, or Defuns

  In Emacs, a major definition at the top level in the buffer,
something like a function, is called a @dfn{defun}.  The name comes
from Lisp, but in Emacs we use it for all languages.

  In many programming language modes, Emacs assumes that a defun is
any pair of parentheses (or braces, if the language uses braces this
way) that starts at the left margin.  For example, in C, the body of a
function definition is a defun, usually recognized as an open-brace
that begins at the left margin@footnote{Alternatively, you can set up
C Mode to recognize a defun at an opening brace at the outermost
level.  @xref{Movement Commands,,, ccmode, the CC Mode Manual}.}.  A
variable's initializer can also count as a defun, if the open-brace
that begins the initializer is at the left margin.

  However, some language modes provide their own code for recognizing
defuns in a way that suits the language syntax and conventions better.

@menu

@node Left Margin Paren
@subsection Left Margin Convention

@cindex open-parenthesis in leftmost column
@cindex ( in leftmost column
  Emacs assumes by default that any opening delimiter found at the
left margin is the start of a top-level definition, or defun.  You can
override this default by setting this user option:

@defvar open-paren-in-column-0-is-defun-start
If this user option is set to @code{t} (the default), opening
parentheses or braces at column zero always start defuns.  When it's
@code{nil}, defuns are found by searching for parens or braces at the
outermost level.
@end defvar

In buffers where @code{open-paren-in-column-0-is-defun-start} is
@code{t}, @strong{don't put an opening delimiter at the left margin
unless it is a defun start}.  For instance, never put an
open-parenthesis at the left margin in a Lisp file unless it is the
start of a top-level list.

  If you don't follow this convention, not only will you have trouble
when you explicitly use the commands for motion by defuns; other
features that use them will also give you trouble.  This includes
the indentation commands (@pxref{Program Indent}) and Font Lock
mode (@pxref{Font Lock}).

  The most likely problem case is when you want an opening delimiter
at the start of a line inside a string.  To avoid trouble, put an
escape character (@samp{\}, in Emacs Lisp, @samp{/} in some other Lisp
dialects) before the opening delimiter.  This will not affect the
contents of the string, but will prevent that opening delimiter from
starting a defun.  Here's an example:

@example
  (insert "Foo:
\(bar)
")
@end example

  To help you catch violations of this convention, Font Lock mode
highlights confusing opening delimiters (those that ought to be
quoted) in bold red.

  Some major modes, including C and related modes, set
@code{open-paren-in-column-0-is-defun-start} buffer-locally to
@code{nil}, thus freeing you from all these restrictions.  This makes
some commands run more slowly, though.

  In the earliest days, the original Emacs found defuns by moving
upward a level of parentheses or braces until there were no more
levels to go up.  This always required scanning all the way back to
the beginning of the buffer, even for a small function.  To speed up
the operation, we changed Emacs to assume that any opening delimiter
at the left margin is the start of a defun.  This heuristic is nearly
always right, and avoids the need to scan back to the beginning of the
buffer.  However, now that modern computers are so powerful, this
scanning is rarely slow enough to annoy, so we've given you a way to
disable the heuristic.

@node Moving by Defuns
@subsection Moving by Defuns
@cindex defuns

nonstandard indentation, the lines below will tend to follow it.  This
behavior is convenient in cases where you have overridden the standard
result of @key{TAB} because you find it unaesthetic for a particular
line.

  By default, an open-parenthesis, open-brace or other opening
delimiter at the left margin is assumed by Emacs (including the
indentation routines) to be the start of a function.  This speeds up
indentation commands.  If you will be editing text which contains
opening delimiters in column zero that aren't the beginning of a
functions, even inside strings or comments, you must set
@code{open-paren-in-column-0-is-defun-start}.  @xref{Left Margin
Paren}, for more information on this.

  Normally, lines are indented with tabs and spaces.  If you want Emacs
to use spaces only, see @ref{Just Spaces}.

@node Multi-line Indent

@table @kbd
@item C-c . @key{RET} @var{style} @key{RET}
Select a predefined style @var{style} (@code{c-set-style}).
@end table

  A @dfn{style} is a named collection of customizations that can be
used in C mode and the related modes.  @ref{Styles,,, ccmode, The CC
Mode Manual}, for a complete description.  Emacs comes with several
predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
@code{stroustrup}, @code{linux}, @code{python}, @code{java},
@code{whitesmith}, @code{ellemtel}, and @code{awk}.  Some of these
styles are primarily intended for one language, but any of them can be
used with any of the languages supported by these modes.  To find out
what a style looks like, select it and reindent some code, e.g., by
typing @key{C-M-q} at the start of a function definition.

@kindex C-c . @r{(C mode)}
@findex c-set-style
  To choose a style for the current buffer, use the command @kbd{C-c
.}.  Specify a style name as an argument (case is not significant).
This command affects the current buffer only, and it affects only
future invocations of the indentation commands; it does not reindent
the code already in the buffer.  To reindent the whole buffer in the
new style, you can type @kbd{C-x h C-M-\}.

@vindex c-default-style
  You can also set the variable @code{c-default-style} to specify the
default style for various major modes.  Its value should be either the
style's name (a string) or an alist, in which each element specifies
one major mode and which indentation style to use for it.  For
example,

@example
(setq c-default-style
      '((java-mode . "java") (awk-mode . "awk") (other . "gnu")))
@end example

@noindent
specifies explicit choices for Java and AWK modes, and the default
@samp{gnu} style for the other C-like modes.  (These settings are
actually the defaults.)  This variable takes effect when you select
one of the C-like major modes; thus, if you specify a new default
style for Java mode, you can make it take effect in an existing Java
mode buffer by typing @kbd{M-x java-mode} there.

  The @code{gnu} style specifies the formatting recommended by the GNU
Project for C; it is the default, so as to encourage use of our
recommended style.

  @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
information on customizing indentation for C and related modes,
including how to override parts of an existing style and how to define
your own styles.

@node Parentheses
@section Commands for Editing with Parentheses

@kindex C-M-t
@findex transpose-sexps
  A somewhat random-sounding command which is nevertheless handy is
@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous
balanced expression across the next one.  An argument serves as a
repeat count, moving the previous expression over that many following
ones.  A negative argument drags the previous balanced expression
backwards across those before it (thus canceling out the effect of
@kbd{C-M-t} with a positive argument).  An argument of zero, rather
than doing nothing, transposes the balanced expressions ending at or
after point and the mark.

@kindex C-M-@@
@kindex C-M-@key{SPC}
@findex mark-sexp
  To set the region around the next balanced expression in the buffer,
use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place
that @kbd{C-M-f} would move to.  @kbd{C-M-@@} takes arguments like
@kbd{C-M-f}.  In particular, a negative argument is useful for putting
the mark at the beginning of the previous balanced expression.  The
alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}.  When you
repeat this command, or use it in Transient Mark mode when the mark is
active, it extends the region by one sexp each time.

  In languages that use infix operators, such as C, it is not possible
to recognize all balanced expressions as such because there can be
multiple possibilities at a given position.  For example, C mode does
not treat @samp{foo + bar} as a single expression, even though it

@item @kbd{C-x ;}
Set comment column (@code{comment-set-column}).
@item @kbd{C-M-j}
@itemx @kbd{M-j}
Like @key{RET} followed by inserting and aligning a comment
(@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
@item @kbd{M-x comment-region}
@itemx @kbd{C-c C-c} (in C-like modes)
Add or remove comment delimiters on all the lines in the region.
@end table

;;; And now, the first part of the function:
  ;; The following line adds one.
  (1+ x))           ; This line adds one.
@end example

  For C-like buffers, you can configure the exact effect of @kbd{M-;}
more flexibly than for most buffers by setting the user options
@code{c-indent-comment-alist} and
@code{c-indent-comments-syntactically-p}.  For example, on a line
ending in a closing brace, @kbd{M-;} puts the comment one space after
the brace rather than at @code{comment-column}.  For full details see
@ref{Comment Commands,,, ccmode, The CC Mode Manual}. 

@node Multi-Line Comments
@subsection Multiple Lines of Comments

@kindex C-M-j
@kindex M-j
@cindex blank lines in programs
@findex comment-indent-new-line

  If you are typing a comment and wish to continue it on another line,
you can use the command @kbd{C-M-j} or @kbd{M-j}
(@code{comment-indent-new-line}).  This terminates the comment you are
typing, creates a new blank line afterward, and begins a new comment
indented under the old one.  Or, if the language syntax permits
comments to extend beyond ends of lines, it may instead continue the
existing comment on the new blank line---this is controlled by the
setting of @code{comment-multi-line} (@pxref{Options for Comments}).
If point is not at the end of the line when you type the command, the
text on the rest of the line becomes part of the new comment line.
When Auto Fill mode is on, going past the fill column while typing a
comment causes the comment to be continued in just this fashion.

@kindex C-c C-c (C mode)
@findex comment-region
  To turn existing lines into comment lines, use the @kbd{M-x
comment-region} command (or type @kbd{C-c C-c} in C-like buffers).  It
adds comment delimiters to the lines that start in the region, thus
commenting them out.  With a negative argument, it does the
opposite---it deletes comment delimiters from the lines in the region.

  With a positive argument, @code{comment-region} duplicates the last
character of the comment start sequence it adds; the argument specifies
how many copies of the character to insert.  Thus, in Lisp mode,
@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line.  Duplicating
the comment delimiter is a way of calling attention to the comment.  It
can also affect how the comment is indented.  In Lisp, for proper
indentation, you should use an argument of two or three, if between defuns;
if within a defun, it must be three.

  You can configure C Mode such that when you type a @samp{/} at the
start of a line in a multi-line block comment, this closes the
comment.  Enable the @code{comment-close-slash} clean-up for this.
@xref{Clean-ups,,, ccmode, The CC Mode Manual}.

@node Options for Comments
@subsection Options Controlling Comments

@vindex comment-column

can hold the actual string to insert.

@vindex comment-multi-line
  The variable @code{comment-multi-line} controls how @kbd{C-M-j}
(@code{indent-new-comment-line}) behaves when used inside a comment.
Specifically, when @code{comment-multi-line} is @code{nil}, the
command inserts a comment terminator, begins a new line, and finally
inserts a comment starter.  Otherwise it does not insert the
terminator and starter, so it effectively continues the current
comment across multiple lines.  In languages that allow multi-line
comments, the choice of value for this variable is a matter of taste.
The default for this variable depends on the major mode.

@vindex comment-indent-function
  The variable @code{comment-indent-function} should contain a function
that will be called to compute the indentation for a newly inserted
comment or for aligning an existing comment.  It is set differently by

@kbd{M-a} except that it moves in the other direction
(@code{c-end-of-statement}).

@item M-x c-backward-into-nomenclature
@findex c-backward-into-nomenclature
Move point backward to beginning of a C++ nomenclature section or
word.  With prefix argument @var{n}, move @var{n} times.  If @var{n}
is negative, move forward.  C++ nomenclature means a symbol name in
the style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital
letter begins a section or word.  Rather than this command, you might
well prefer the newer ``Subword Mode'', which does the same thing
better.  @xref{Other C Commands}.

In the GNU project, we recommend using underscores to separate words
within an identifier in C or C++, rather than using case distinctions.

@item M-x c-forward-into-nomenclature

@node Electric C
@subsection Electric C Characters

  In C mode and related modes, certain printing characters are
@dfn{electric}---in addition to inserting themselves, they also
reindent the current line, and optionally also insert newlines.  The
``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
@kbd{)}.  @xref{Electric Keys,,, ccmode, The CC Mode Manual}.

  You might find electric indentation inconvenient if you are editing
chaotically indented code.  If you are new to CC Mode, you might find
it disconcerting.  You can toggle electric action with the command
@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line
after the mode name:

@table @kbd
@item C-c C-l
@kindex C-c C-l @r{(C mode)}
@findex c-toggle-electric-state
Toggle electric action (@code{c-toggle-electric-state}).  With a
prefix argument, this command enables electric action if the argument
is positive, disables it if it is negative.
@end table

  Electric characters insert newlines only when, in addition to the
electric state, the @dfn{auto-newline} feature is enabled (indicated
by @samp{/la} in the mode line after the mode name).  You can turn
this feature on or off with the command @kbd{C-c C-a}:

@table @kbd
@item C-c C-a
@kindex C-c C-a @r{(C mode)}
@findex c-toggle-auto-newline
Toggle the auto-newline feature (@code{c-toggle-auto-newline}).  With a
prefix argument, this command turns the auto-newline feature on if the
argument is positive, and off if it is negative.
@end table

  Usually the CC Mode style system (@pxref{Styles,,, ccmode, The CC
Mode Manual}) configures the exact circumstances in which Emacs
inserts auto-newlines, but you can configure this directly instead.
Full details are at @ref{Custom Auto-newlines,,, ccmode, The CC Mode
Manual}, but there is a short summary below.

  The colon character is electric because that is appropriate for a
single colon.  But when you want to insert a double colon in C++, the
electric behavior of colon is inconvenient.  You can insert a double
colon with no reindentation or newlines by typing @kbd{C-c :}:

inserted.

@vindex c-cleanup-list
   Electric characters can also delete newlines automatically when the
auto-newline feature is enabled.  This feature makes auto-newline more
acceptable, by deleting the newlines in the most common cases where
you do not want them.  Emacs can recognize several cases in which
deleting a newline might be desirable; by setting the variable
@code{c-cleanup-list}, you can specify @emph{which} of these cases
that should happen.  @xref{Clean-ups,,, ccmode, The CC Mode Manual}.
The variable's value is a list of symbols, each describing one case
for possible deletion of a newline.  Here is a summary of the
meaningful symbols and their meanings:

@table @code
@item brace-catch-brace
Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the
entire construct on a single line.  The clean-up occurs when you type

@item list-close-comma
Clean up commas following braces in array and aggregate
initializers.  Clean-up occurs when you type the comma.

@item one-line-defun
Remove space and newlines from a defun if this would leave it short
enough to fit on a single line.  This is useful for AWK pattern/action
pairs.  ``Short enough'' means not longer than the value of the user
option @code{c-max-one-liner-length}.  Clean-up occurs when you type
the closing brace.

@item scope-operator
Clean up double colons which may designate a C++ scope operator, by
placing the colons together.  Clean-up occurs when you type the second
colon, but only when the two colons are separated by nothing but
whitespace.

@node Hungry Delete
@subsection Hungry Delete Feature in C
@cindex hungry deletion (C Mode)

  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.
@dfn{Whitespace} here includes tabs and newlines, but not comments or
preprocessor commands.

@table @kbd
@item C-c C-@key{BS}
@itemx C-c @key{BS}
@findex c-hungry-backspace
@kindex C-c C-@key{BS} (C Mode)
@kindex C-c @key{BS} (C Mode)
@code{c-hungry-backspace}---Delete the entire block of whitespace
preceding point.

@item C-c C-d
@itemx C-c C-@key{DEL}
@itemx C-c @key{DEL}
@findex c-hungry-delete-forward
@kindex C-c C-d (C Mode)
@kindex C-c C-@key{DEL} (C Mode)
@kindex C-c @key{DEL} (C Mode)
@code{c-hungry-delete-forward}---Delete the entire block of whitespace
following point.
@end table

  As an alternative to the above commands, you can enable @dfn{hungry
delete mode}.  When this feature is enabled (indicated by @samp{/h} in
the mode line after the mode name), a single @key{BS} command deletes
all preceding whitespace, not just one space, and a single @kbd{C-c
C-d} (but @emph{not} @key{delete}) deletes all following whitespace.

@table @kbd
@item M-x c-toggle-hungry-state
@findex c-toggle-hungry-state
Toggle the hungry-delete feature
(@code{c-toggle-hungry-state})@footnote{This command had the binding
@kbd{C-c C-d} in earlier versions of Emacs.  @kbd{C-c C-d} is now
bound to @code{c-hungry-delete-forward}.}.  With a prefix argument,
this command turns the hungry-delete feature on if the argument is
positive, and off if it is negative.
@end table

@vindex c-hungry-delete-key
   The variable @code{c-hungry-delete-key} controls whether the
hungry-delete feature is enabled.

@node Other C Commands
@subsection Other Commands for C Mode

@table @kbd
@item C-c C-w
@itemx M-x c-subword-mode
@findex c-subword-mode
Enable (or disable) @dfn{subword mode} - Emacs's word commands then
recognize upper case letters in @samp{StudlyCapsIdentifiers} as word
boundaries.  This is indicated by the flag @samp{/w} on the mode line
after the mode name (e.g. @samp{C/law}).  You can even use @kbd{M-x
c-subword-mode} in non-CC Mode buffers.

@item M-x c-context-line-break
@findex c-context-line-break
This command inserts a line break and indents the new line in a manner
appropriate to the context.  In normal code, it does the work of
@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it
additionally inserts a @samp{\} at the line break, and within comments
it's like @kbd{M-j} (@code{c-indent-new-comment-line}).

@code{c-context-line-break} isn't bound to a key by default, but it
needs a binding to be useful.  The following code will bind it to
@kbd{C-j}.  We use @code{c-initialization-hook} here to make sure
the keymap is loaded before we try to change it.

@example
(defun my-bind-clb ()
  (define-key c-mode-base-map "\C-j" 'c-context-line-break))
(add-hook 'c-initialization-hook 'my-bind-clb)
@end example

@item C-M-h
Put mark at the end of a function definition, and put point at the
beginning (@code{c-mark-function}).