@cindex C editing
@cindex program editing
- Emacs provides many features to facilitate editing programs. These
-features can:
+ Emacs provides many features to facilitate editing programs. Some
+of these features can
@itemize @bullet
@item
Highlight program syntax (@pxref{Font Lock}).
@end itemize
+ This chapter describes these features and many more.
+
@menu
* Program Modes:: Major modes for editing programs.
* Defuns:: Commands to operate on major top-level parts
@xref{Major Modes}. A programming language major mode typically
specifies the syntax of expressions, the customary rules for
indentation, how to do syntax highlighting for the language, and how
-to find the beginning of a function definition. They often provide
-facilities for compiling and debugging programs as well.
+to find the beginning of a function definition. It often customizes
+or provides facilities for compiling and debugging programs as well.
Ideally, Emacs should provide a major mode for each programming
language that you might want to edit; if it doesn't have a mode for
your favorite language, you can contribute one. But often the mode
for one language can serve for other syntactically similar languages.
The major mode for language @var{l} is called @code{@var{l}-mode},
-and you can enable it by typing @kbd{M-x @var{l}-mode @key{RET}}.
+and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}.
@xref{Choosing Modes}.
@cindex Perl mode
@cindex Icon mode
-@cindex Awk mode
@cindex Makefile mode
@cindex Tcl mode
@cindex CPerl mode
@cindex PostScript mode
The existing programming language major modes include Lisp, Scheme (a
variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
-Awk, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
+AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
companion for font creation), Modula2, Objective-C, Octave, Pascal,
Perl, Pike, PostScript, Prolog, Simula, Tcl, and VHDL. There is
also a major mode for makefiles, called Makefile mode. An alternative
mode for Perl is called CPerl mode. Modes are available for the
-scripting languages of the common Unix shells, VMS DCL, and
+scripting languages of the common GNU and Unix shells, VMS DCL, and
MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for
editing various sorts of configuration files.
@findex c-electric-backspace
In most programming languages, indentation should vary from line to
line to illustrate the structure of the program. So the major modes
-for program languages arrange for @key{TAB} to update the indentation
-of the current line. They also rebind @key{DEL} to treat a tab as if
-it were the equivalent number of spaces. This makes it possible to
-reduce indentation one column at a time without worrying whether it is
-made up of spaces or tabs. Use @kbd{C-b C-d} to delete a tab
-character before point, in these modes.
+for programming languages arrange for @key{TAB} to update the
+indentation of the current line. They also rebind @key{DEL} to treat
+a tab as if it were the equivalent number of spaces; this lets you
+delete one column of indentation without worrying whether the
+whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a
+tab character before point, in these modes.
Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
-Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL
+Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK
(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).
")
@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
In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
which is almost the same as @code{mark-defun}; the difference is that
it backs up over the argument declarations, function name and returned
-data type so that the entire C function is inside the region.
-@xref{Marking Objects}. This is an example of how major modes adjust
-the standard key bindings so that they do their standard jobs in a way
-better fitting a particular language. Other major modes may adjust
-any or all of these key bindings for that purpose.
+data type so that the entire C function is inside the region. This is
+an example of how major modes adjust the standard key bindings so that
+they do their standard jobs in a way better fitting a particular
+language. Other major modes may replace any or all of these key
+bindings for that purpose.
@node Imenu
@subsection Imenu
-@cindex indexes of buffer contents
-@cindex buffer content indexes
+@cindex index of buffer definitions
+@cindex buffer definitions index
@cindex tags
- The Imenu facility offers a way to find the the major definitions in
+ The Imenu facility offers a way to find the major definitions in
a file by name. It is also useful in text formatter major modes,
where it treats each chapter, section, etc., as a definition.
-(@pxref{Tags}, for a more powerful feature that handles multiple files
+(@xref{Tags}, for a more powerful feature that handles multiple files
together.)
@findex imenu
If you type @kbd{M-x imenu}, it reads the name of a definition using
-the minibuffer, then goes to that definition. You can use completion
-to specify the name, and a complete list of possible names is always
-displayed.
+the minibuffer, then moves point to that definition. You can use
+completion to specify the name; the command always displays the whole
+list of valid names.
@findex imenu-add-menubar-index
Alternatively, you can bind the command @code{imenu} to a mouse
-click. Then it displays mouse menus for you to select the definition
-you want. You can also add the buffer's index to the menu bar by
-calling @code{imenu-add-menubar-index}. If you want to have this
-menu bar item available for all buffers in a certain major mode, you
-can do this by adding @code{imenu-add-menubar-index} to its mode
-hook. But then you will have to wait for the buffer to be searched
-for definitions, each time you visit a file which uses that mode.
+click. Then it displays mouse menus for you to select a definition
+name. You can also add the buffer's index to the menu bar by calling
+@code{imenu-add-menubar-index}. If you want to have this menu bar
+item available for all buffers in a certain major mode, you can do
+this by adding @code{imenu-add-menubar-index} to its mode hook. But
+if you have done that, you will have to wait each time you visit a
+file in that mode, while Emacs finds all the definitions in that
+buffer.
@vindex imenu-auto-rescan
When you change the contents of a buffer, if you add or delete
-definitions, you can update the buffer's index to correspond to the
+definitions, you can update the buffer's index based on the
new contents by invoking the @samp{*Rescan*} item in the menu.
-Rescanning happens automatically if @code{imenu-auto-rescan} is
-non-@code{nil}. There is no need to rescan because of small changes
-in the text.
+Rescanning happens automatically if you set @code{imenu-auto-rescan} to
+a non-@code{nil} value. There is no need to rescan because of small
+changes in the text.
@vindex imenu-sort-function
You can customize the way the menus are sorted by setting the
-variable @code{imenu-sort-function}. By default names are ordered as
+variable @code{imenu-sort-function}. By default, names are ordered as
they occur in the buffer; if you want alphabetic sorting, use the
symbol @code{imenu--sort-by-name} as the value. You can also
define your own comparison function by writing Lisp code.
@node Which Function
@subsection Which Function Mode
+@cindex current function name in mode line
Which Function mode is a minor mode that displays the current
function name in the mode line, updating it as you move around in a
@vindex which-func-modes
To enable (or disable) Which Function mode, use the command @kbd{M-x
which-function-mode}. This command is global; it applies to all
-buffers, both existing ones and those yet to be created. However, this
-only affects certain major modes, those listed in the value of
-@code{which-func-modes}. If the value is @code{t}, then Which Function
-mode applies to all major modes that know how to support it---which are
-the major modes that support Imenu.
+buffers, both existing ones and those yet to be created. However,
+it only takes effect in certain major modes, those listed in the value of
+@code{which-func-modes}. If the value is @code{t}, then Which
+Function mode applies to all major modes that know how to support
+it---in other words, all the major modes that support Imenu.
@node Program Indent
@section Indentation for Programs
@item C-j
Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
@item @key{LINEFEED}
-This key is a way to enter @kbd{C-j}, on some keyboards.
+This key, if the keyboard has it, is another way to enter @kbd{C-j}.
@end table
@kindex TAB @r{(programming modes)}
@table @kbd
@item C-M-q
Reindent all the lines within one parenthetical grouping(@code{indent-sexp}).
+@item C-M-\
+Reindent all lines in the region (@code{indent-region}).
@item C-u @key{TAB}
Shift an entire parenthetical grouping rigidly sideways so that its
first line is properly indented.
-@item C-M-\
-Reindent all lines in the region (@code{indent-region}).
@item M-x indent-code-rigidly
Shift all the lines in the region rigidly sideways, but do not alter
lines that start inside comments and strings.
changes only the relative indentation within the grouping, not its
overall indentation. To correct that as well, type @key{TAB} first.
+ Another way to specify the range to be reindented is with the
+region. The command @kbd{C-M-\} (@code{indent-region}) applies
+@key{TAB} to every line whose first character is between point and
+mark.
+
@kindex C-u TAB
If you like the relative indentation within a grouping, but not the
indentation of its first line, you can type @kbd{C-u @key{TAB}} to
reindents the current line as usual, then reindents by the same amount
all the lines in the parenthetical grouping starting on the current
line. It is clever, though, and does not alter lines that start
-inside strings, or C preprocessor lines when in C mode.
+inside strings. Neither does it alter C preprocessor lines when in C
+mode, but it does reindent any continuation lines that may be attached
+to them.
@findex indent-code-rigidly
- Another way to specify the range to be reindented is with the region.
-The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to
-every line whose first character is between point and mark. The command
-@kbd{M-x indent-code-rigidly} rigidly shifts all the lines in the region
-sideways, like @code{indent-rigidly} does (@pxref{Indentation
-Commands}), except that it doesn't alter the indentation of lines that
-start inside a comment or a string, unless the region starts inside that
-comment or string.
+ You can also perform this operation on the region, using the command
+@kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the
+region sideways, like @code{indent-rigidly} does (@pxref{Indentation
+Commands}). It doesn't alter the indentation of lines that start
+inside a string, unless the region also starts inside that string.
@node Lisp Indent
@subsection Customizing Lisp Indentation
@vindex lisp-body-indent
Certain functions override the standard pattern. Functions whose
-names start with @code{def} treat the the second lines as the start of
+names start with @code{def} treat the second lines as the start of
a @dfn{body}, by indenting the second line @code{lisp-body-indent}
additional columns beyond the open-parenthesis that starts the
expression.
+@cindex @code{lisp-indent-function} property
You can override the standard pattern in various ways for individual
-functions, according to the @code{lisp-indent-function} property of the
-function name. There are four possibilities for this property:
-
-@table @asis
-@item @code{nil}
-This is the same as no property---use the standard indentation pattern.
-@item @code{defun}
-Handle this function like a @samp{def} construct: treat the second
-line the start of a @dfn{body}.
-@item a number, @var{number}
-The first @var{number} arguments of the function are
-@dfn{distinguished} arguments; the rest are considered the body
-of the expression. A line in the expression is indented according to
-whether the first argument on it is distinguished or not. If the
-argument is part of the body, the line is indented @code{lisp-body-indent}
-more columns than the open-parenthesis starting the containing
-expression. If the argument is distinguished and is either the first
-or second argument, it is indented @emph{twice} that many extra columns.
-If the argument is distinguished and not the first or second argument,
-the line uses the standard pattern.
-@item a symbol, @var{symbol}
-@var{symbol} should be a function name; that function is called to
-calculate the indentation of a line within this expression. The
-function receives two arguments:
-@table @asis
-@item @var{state}
-The value returned by @code{parse-partial-sexp} (a Lisp primitive for
-indentation and nesting computation) when it parses up to the
-beginning of this line.
-@item @var{pos}
-The position at which the line being indented begins.
-@end table
-@noindent
-It should return either a number, which is the number of columns of
-indentation for that line, or a list whose car is such a number. The
-difference between returning a number and returning a list is that a
-number says that all following lines at the same nesting level should
-be indented just like this one; a list says that following lines might
-call for different indentations. This makes a difference when the
-indentation is being computed by @kbd{C-M-q}; if the value is a
-number, @kbd{C-M-q} need not recalculate indentation for the following
-lines until the end of the list.
-@end table
+functions, according to the @code{lisp-indent-function} property of
+the function name. Normally you would use this for macro definitions
+and specify it using the @code{declare} construct (@pxref{Defining
+Macros,,, elisp, the Emacs Lisp Reference Manual}).
@node C Indent
@subsection Commands for C Indentation
@kindex C-M-q @r{(C mode)}
@findex c-indent-exp
Reindent each line in the balanced expression that follows point
-(@code{c-indent-exp}). A prefix argument inhibits error checking and
-warning messages about invalid syntax.
+(@code{c-indent-exp}). A prefix argument inhibits warning messages
+about invalid syntax.
@item @key{TAB}
@findex c-indent-command
Reindent the current line, and/or in some cases insert a tab character
(@code{c-indent-command}).
+@vindex c-tab-always-indent
If @code{c-tab-always-indent} is @code{t}, this command always reindents
the current line and does nothing else. This is the default.
if @code{indent-tabs-mode} is @code{nil}).
Any other value (not @code{nil} or @code{t}) means always reindent the
-line, and also insert a tab if within a comment, a string, or a
-preprocessor directive.
+line, and also insert a tab if within a comment or a string.
@end table
To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
@subsection Customizing C Indentation
@cindex style (for indentation)
- C mode and related modes use a simple yet flexible mechanism for
-customizing indentation. The mechanism works in two steps: first it
-classifies the line syntactically according to its contents and context;
-second, it associates each kind of syntactic construct with an
-indentation offset based on your selected @dfn{style}.
+ C mode and related modes use a flexible mechanism for customizing
+indentation. C mode indents a source line in two steps: first it
+classifies the line syntactically according to its contents and
+context; second, it determines the indentation offset associated by
+your selected @dfn{style} with the syntactic construct and adds this
+onto the indentation of the @dfn{anchor statement}.
@table @kbd
-@item M-x c-set-style @key{RET} @var{style} @key{RET}
-Select predefined indentation style @var{style}.
+@item C-c . @key{RET} @var{style} @key{RET}
+Select a predefined style @var{style} (@code{c-set-style}).
@end table
- A style is a named collection of indentation customizations that can
+ 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},
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{M-x
-c-set-style}. 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 change the indentation of the code in the buffer. To reindent the
-whole buffer in the new style, you can type @kbd{C-x h C-M-\}.
+ 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 an alist,
-in which each element specifies one major mode and which indentation
-style to use for it. For example,
+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
@noindent
specifies an explicit choice for Java mode, and the default @samp{gnu}
style for the other C-like modes. This variable takes effect when you
-switch to one of the C-like major modes; thus, if you specify a new
+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.
Project for C; it is the default, so as to encourage use of our
recommended style.
- @xref{Customizing Indentation,, cc-mode, the CC Mode Manual}, for
+ @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.
When talking about these facilities, the term ``parenthesis'' also
includes braces, brackets, or whatever delimiters are defined to match
-in pairs. This is controlled by the major mode, through the syntax
-table (@pxref{Syntax}). In Lisp, only parentheses count; in C, these
-commands apply to braces and brackets too.
+in pairs. The major mode controls which delimiters are significant,
+through the syntax table (@pxref{Syntax}). In Lisp, only parentheses
+count; in C, these commands apply to braces and brackets too.
You can use @kbd{M-x check-parens} to find any unbalanced
parentheses and unbalanced string quotes in the buffer.
Move backward over a balanced expression(@code{backward-sexp}).
@item C-M-k
Kill balanced expression forward (@code{kill-sexp}).
-@item C-M-@key{DEL}
-Kill balanced expression backward (@code{backward-kill-sexp}).
@item C-M-t
Transpose expressions (@code{transpose-sexps}).
@item C-M-@@
+@itemx C-M-@key{SPC}
Put mark after following expression (@code{mark-sexp}).
@end table
Each programming language major mode customizes the definition of
balanced expressions to suit that language. Balanced expressions
typically include symbols, numbers, and string constants, as well as
-anything contained in parentheses, brackets or braces. Some languages
+any pair of matching delimiters and their contents. Some languages
have obscure forms of expression syntax that nobody has bothered to
implement in Emacs.
@cindex Control-Meta
- By convention, the keys for these commands are always Control-Meta
-characters. They usually act like the corresponding Meta characters,
-except that they take note of parentheses and their contents. For
-instance, the command @kbd{C-M-b} moves backward over a balanced
-expression, just as @kbd{M-b} moves back over a word.
+ By convention, the keys for these commands are all Control-Meta
+characters. They usually act on expressions just as the corresponding
+Meta characters act on words. For instance, the command @kbd{C-M-b}
+moves backward over a balanced expression, just as @kbd{M-b} moves
+back over a word.
@kindex C-M-f
@kindex C-M-b
@cindex killing expressions
@kindex C-M-k
@findex kill-sexp
-@kindex C-M-DEL
-@findex backward-kill-sexp
Killing a whole balanced expression can be done with @kbd{C-M-k}
-(@code{kill-sexp}) or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}).
-@kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over, and
-@kbd{C-M-@key{DEL}} kills the characters that @kbd{C-M-b} would move
-over. On some machines, @kbd{C-M-@key{DEL}} typed on the console is a
-command to reboot; when that is so, you cannot use it as an Emacs
-command. This conflict is rare, though: usually the @key{DEL} key for
-Emacs is really @key{BACKSPACE}, and the reboot command is
-@kbd{C-M-@key{DELETE}}, so there is no conflict.
+(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f}
+would move over.
@cindex transposition of expressions
@kindex C-M-t
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 backwards (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 after point and the mark.
+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-@@}.
In languages that use infix operators, such as C, it is not possible
to recognize all balanced expressions as such because there can be
expression and @samp{bar} as another, with the @samp{+} as punctuation
between them. Both @samp{foo + bar} and @samp{foo} are legitimate
choices for ``the expression following point'' when point is at the
-@samp{f}. Note that @samp{(foo + bar)} does act as a single
-expression in C mode.
+@samp{f}, so the expression commands must perforce choose one or the
+other to operate on. Note that @samp{(foo + bar)} is recognized as a
+single expression in C mode, because of the parentheses.
@node Moving by Parens
@subsection Moving in the Parenthesis Structure
the text. Whenever you type a self-inserting character that is a
closing delimiter, the cursor moves momentarily to the location of the
matching opening delimiter, provided that is on the screen. If it is
-not on the screen, Emacs displays some text near it in the echo area.
-Either way, you can tell what grouping you are closing off.
+not on the screen, Emacs displays some of the text near it in the echo
+area. Either way, you can tell which grouping you are closing off.
If the opening delimiter and closing delimiter are mismatched---such
as in @samp{[x)}---a warning message is displayed in the echo area.
@cindex comments
Because comments are such an important part of programming, Emacs
-provides special commands for editing and inserting comments.
+provides special commands for editing and inserting comments. It can
+also do spell checking on comments with Flyspell Prog mode
+(@pxref{Spelling}).
@menu
* Comment Commands:: Inserting, killing, and indenting comments.
The comment commands in this table insert, kill and align comments.
They are described in this section and following sections.
-@table @kbd
-@item M-;
+@table @asis
+@item @kbd{M-;}
Insert or realign comment on current line; alternatively, comment or
uncomment the region (@code{comment-dwim}).
-@item C-u M-;
+@item @kbd{C-u M-;}
Kill comment on current line (@code{comment-kill}).
-@item C-x ;
+@item @kbd{C-x ;}
Set comment column (@code{comment-set-column}).
-@item C-M-j
+@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 M-x comment-region
+@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
@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} (@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 @kbd{C-M-j} is typed, the text on
-the rest of the line becomes part of the new comment 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
@vindex comment-column
@kindex C-x ;
@findex comment-set-column
- The comment column is stored in the variable @code{comment-column}. You
-can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
-(@code{comment-set-column}) sets the comment column to the column point is
-at. @kbd{C-u C-x ;} sets the comment column to match the last comment
-before point in the buffer, and then does a @kbd{M-;} to align the
-current line's comment under the previous one.
+ The @dfn{comment column}, the column at which Emacs tries to place
+comments, is stored in the variable @code{comment-column}. You can
+set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
+(@code{comment-set-column}) sets the comment column to the column
+point is at. @kbd{C-u C-x ;} sets the comment column to match the
+last comment before point in the buffer, and then does a @kbd{M-;} to
+align the current line's comment under the previous one.
The variable @code{comment-column} is per-buffer: setting the variable
in the normal fashion affects only the current buffer, but there is a
than the comment starting delimiter in the strictest sense of the word;
for example, in C mode the value of the variable is
@c This stops M-q from breaking the line inside that @code.
-@code{@w{"/\\*+ *\\|//+ *""}}, which matches extra stars and spaces
+@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces
after the @samp{/*} itself, and accepts C++ style comments also.
(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
the string, which is needed to deny the first star its special meaning
@vindex comment-padding
The variable @code{comment-padding} specifies how many spaces
-@code{comment-region} should insert on each line between the
-comment delimiter and the line's original text. The default is 1,
-to insert one space.
+@code{comment-region} should insert on each line between the comment
+delimiter and the line's original text. The default is 1, to insert
+one space. @code{nil} means 0. Alternatively, @code{comment-padding}
+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. If
-@code{comment-multi-line} is @code{nil}, as it normally is, then the
-comment on the starting line is terminated and a new comment is started
-on the new following line. If @code{comment-multi-line} is not
-@code{nil}, then the new following line is set up as part of the same
-comment that was found on the starting line. This is done by not
-inserting a terminator on the old line, and not inserting a starter on
-the new line. In languages where multi-line comments work, the choice
-of value for this variable is a matter of taste.
+(@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
@findex info-lookup-symbol
@findex info-lookup-file
-@kindex C-h C-i
+@kindex C-h S
For C, Lisp, and other languages that have documentation in Info,
-you can use @kbd{C-h C-i} (@code{info-lookup-symbol}) to view the Info
+you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the Info
documentation for a symbol. You specify the symbol with the
minibuffer; the default is the symbol appearing in the buffer at
point.
You can also use @kbd{M-x info-lookup-file} to look for documentation
for a file name.
- This feature currently supports the modes Awk, Autoconf, Bison, C,
+ This feature currently supports the modes AWK, Autoconf, Bison, C,
Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme, and Texinfo,
provided you have installed the relevant Info files, which are
typically available with the appropriate GNU package.
@node Man Page
@subsection Man Page Lookup
- Eventually the GNU project hopes to replace most man pages in the
-GNU operating system with better-organized manuals that you can browse
-with Info (@pxref{Misc Help}). Since this process is not finished, it
-is still useful to read manual pages.
+@cindex manual page
+ On Unix, the main form of on-line documentation was the @dfn{manual
+page} or @dfn{man page}. In the GNU operating system, we hope to
+replace man pages with better-organized manuals that you can browse
+with Info (@pxref{Misc Help}). This process is not finished, so it is
+still useful to read manual pages.
@findex manual-entry
-@cindex manual pages
- You can read the ``man page'' for an operating system command,
-library function, or system call, with the @kbd{M-x manual-entry}
-command. It runs the @code{man} program to format the man page, and
-runs it asynchronously if your system permits, so that you can keep on
-editing while the page is being formatted. (MS-DOS and MS-Windows 3
-do not permit asynchronous subprocesses, so on these systems you
-cannot edit while Emacs waits for @code{man} to finish.) The result
-goes in a buffer named @samp{*Man @var{topic}*}. These buffers use a
-special major mode, Man mode, that facilitates scrolling and jumping
-to other manual pages. For details, type @kbd{C-h m} while in a man
-page buffer.
+ You can read the man page for an operating system command, library
+function, or system call, with the @kbd{M-x man} command. It
+runs the @code{man} program to format the man page; if the system
+permits, it runs @code{man} asynchronously, so that you can keep on
+editing while the page is being formatted. (On MS-DOS and MS-Windows
+3, you cannot edit while Emacs waits for @code{man} to finish.) The
+result goes in a buffer named @samp{*Man @var{topic}*}. These buffers
+use a special major mode, Man mode, that facilitates scrolling and
+jumping to other manual pages. For details, type @kbd{C-h m} while in
+a man page buffer.
@cindex sections of manual pages
- Each man page belongs to one of around ten @dfn{sections}; sometimes
-there are multiple man pages with the same name in different sections.
-To read a man page from a specific section, type
+ Each man page belongs to one of ten or more @dfn{sections}, each
+named by a digit or by a digit and a letter. Sometimes there are
+multiple man pages with the same name in different sections. To read
+a man page from a specific section, type
@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}}
when @kbd{M-x manual-entry} prompts for the topic. For example, to
read the man page for the C library function @code{chmod} (as opposed
-to a command by the same name), type @kbd{M-x manual-entry @key{RET}
-chmod(2v) @key{RET}} (assuming @code{chmod} is in section @samp{2v}).
+to a command of the same name), type @kbd{M-x manual-entry @key{RET}
+chmod(2) @key{RET}} (@code{chmod} is a system call, so it is in
+section @samp{2}).
+@vindex Man-switches
If you do not specify a section, the results depend on how the
-@code{man} command works on your system. Some of them display only
+@code{man} program works on your system. Some of them display only
the first man page they find. Others display all man pages that have
the specified name, so you can move between them with the @kbd{M-n}
-and @kbd{M-p} keys. The mode line shows how many manual pages are
-present in the Man buffer.
+and @kbd{M-p} keys@footnote{On some systems, the @code{man} program
+accepts a @samp{-a} command-line option which tells it to display all
+the man pages for the specified topic. If you want this behavior, you
+can add this option to the value of the variable @code{Man-switches}.}.
+The mode line shows how many manual pages are present in the Man buffer.
@vindex Man-fontify-manpage-flag
- By default, Emacs uses faces in man pages if Emacs can display
-different fonts or colors. For a long man page, setting the faces
-properly can take substantial time. You can turn off use of faces in
-man pages by setting the variable @code{Man-fontify-manpage-flag} to
-@code{nil}.
+ By default, Emacs highlights the text in man pages. For a long man
+page, highlighting can take substantial time. You can turn off
+highlighting of man pages by setting the variable
+@code{Man-fontify-manpage-flag} to @code{nil}.
@findex Man-fontify-manpage
If you insert the text of a man page into an Emacs buffer in some
directories specified in the @code{MANPATH} environment variable. (If
@code{MANPATH} is not set, @code{woman} uses a suitable default value,
which can be customized.) More precisely, @code{woman} looks for
-subdirectories that match the shell wildcard @file{man*} in each one
+subdirectories that match the shell wildcard pattern @file{man*} in each one
of these directories, and tries to find the manual pages in those
subdirectories. When first invoked, @kbd{M-x woman} converts the
value of @code{MANPATH} to a list of directory names and stores that
The value should be one of these four symbols.
@table @code
-@item block
-Open only blocks.
+@item code
+Open only code blocks.
@item comment
Open only comments.
@item t
-Open both blocks and comments.
+Open both code blocks and comments.
@item nil
-Open neither blocks nor comments.
+Open neither code blocks nor comments.
@end table
@item hs-special-modes-alist
-A list of elements, each Specifying how to initialize Hideshow
+A list of elements, each specifying how to initialize Hideshow
variables for one major mode. See the variable's documentation string
for more information.
@end table
@section Completion for Symbol Names
@cindex completion (symbol names)
- Usually completion happens in the minibuffer. But one kind of completion
-is available in all buffers: completion for symbol names.
+ In Emacs, completion is something you normally do in the minibuffer.
+But one kind of completion is available in all buffers: completion for
+symbol names.
@kindex M-TAB
- The character @kbd{M-@key{TAB}} runs a command to complete the partial
-symbol before point against the set of meaningful symbol names. Any
-additional characters determined by the partial name are inserted at
-point.
+ The character @kbd{M-@key{TAB}} runs a command to complete the
+partial symbol before point against the set of meaningful symbol
+names. This command inserts at point any additional characters that
+it can determine from the partial name.
- If the partial name in the buffer has more than one possible completion
-and they have no additional characters in common, a list of all possible
-completions is displayed in another window.
+ If the partial name in the buffer has multiple possible completions
+that differ in the very next character, so that it is impossible to
+complete even one more character, @kbd{M-@key{TAB}} displays a list of
+all possible completions in another window.
@cindex tags-based completion
@cindex Info index completion
@findex glasses-mode
Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
-readable by altering the display. It knows two different ways to do
-this: by displaying underscores between a lower-case letter and the
-following capital letter, or by emboldening the capital letters. It
-does not alter the buffer text, only the way they display, so you can
-use it even on read-only buffers. You can use the command @kbd{M-x
-glasses-mode} to enable or disable the mode; you can also add
-@code{glasses-mode} to the mode hook of appropriate programming
-language major modes.
+readable by altering the way they display. It knows two different
+ways to do this: by displaying underscores between a lower-case letter
+and the following capital letter, and by emboldening the capital
+letters. It does not alter the buffer text, only the way they
+display, so you can use it even on read-only buffers. You can use the
+command @kbd{M-x glasses-mode} to enable or disable the mode in the
+current buffer; you can also add @code{glasses-mode} to the mode hook
+of the programming language major modes in which you normally want
+to use Glasses mode.
@node Misc for Programs
@section Other Features Useful for Editing Programs
A number of Emacs commands that aren't designed specifically for
-editing programs are useful for it nonetheless.
+editing programs are useful for that nonetheless.
The Emacs commands that operate on words, sentences and paragraphs
are useful for editing code. Most symbols names contain words
(@pxref{Words}); sentences can be found in strings and comments
-(@pxref{Sentences}). Paragraphs in the strict sense may be found in
+(@pxref{Sentences}). Paragraphs in the strict sense can be found in
program code (in long comments), but the paragraph commands are useful
in other places too, because programming language major modes define
paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
@cindex CORBA IDL mode
@cindex Objective C mode
@cindex C++ mode
+@cindex AWK mode
@cindex mode, Java
@cindex mode, C
+@cindex mode, C++
@cindex mode, Objective C
@cindex mode, CORBA IDL
@cindex mode, Pike
+@cindex mode, AWK
This section gives a brief description of the special features
-available in C, C++, Objective-C, Java, CORBA IDL, and Pike modes.
-(These are called ``C mode and related modes.'') @xref{Top, CC Mode,
-ccmode, , CC Mode}, for a more extensive description of these modes
+available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
+(These are called ``C mode and related modes.'') @xref{Top, , CC Mode,
+ccmode, CC Mode}, for a more extensive description of these modes
and their special features.
@menu
-* Motion in C:: Commands to move by C statements, etc.
-* Electric C:: Colon and other chars can automatically reindent.
-* Hungry Delete:: A more powerful DEL command.
-* Other C Commands:: Filling comments, viewing expansion of macros,
- and other neat features.
-* Comments in C:: Options for customizing comment style.
+* Motion in C:: Commands to move by C statements, etc.
+* Electric C:: Colon and other chars can automatically reindent.
+* Hungry Delete:: A more powerful DEL command.
+* Other C Commands:: Filling comments, viewing expansion of macros,
+ and other neat features.
@end menu
@node Motion in C
related modes.
@table @code
+@item M-x c-beginning-of-defun
+@itemx M-x c-end-of-defun
+@findex c-beginning-of-defun
+@findex c-end-of-defun
+Move point to the beginning or end of the current function or
+top-level definition. These are found by searching for the least
+enclosing braces. (By contrast, @code{beginning-of-defun} and
+@code{end-of-defun} search for braces in column zero.) If you are
+editing code where the opening brace of a function isn't placed in
+column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to
+these commands. @xref{Moving by Defuns}.
+
@item C-c C-u
@kindex C-c C-u @r{(C mode)}
@findex 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. When going backwards, @code{#elif} is treated
-like @code{#else} followed by @code{#if}. When going forwards,
-@code{#elif} is ignored.@refill
+preprocessor conditional.
+
+@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
+the function will stop at a @samp{#elif} when going backward, but not
+when going forward.
@item C-c C-p
@kindex C-c C-p @r{(C mode)}
argument, move backward.
@item M-a
-@kindex ESC a
+@kindex M-a (C mode)
@findex c-beginning-of-statement
Move point to the beginning of the innermost C statement
(@code{c-beginning-of-statement}). If point is already at the beginning
of a statement, move to the beginning of the preceding statement. With
prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
-If point is within a string or comment, or next to a comment (only
-whitespace between them), this command moves by sentences instead of
-statements.
-
-When called from a program, this function takes three optional
-arguments: the numeric prefix argument, a buffer position limit
-(don't move back before that place), and a flag that controls whether
-to do sentence motion when inside of a comment.
+In comments or in strings which span more than one line, this command
+moves by sentences instead of statements.
@item M-e
-@kindex ESC e
+@kindex M-e (C mode)
@findex c-end-of-statement
-Move point to the end of the innermost C statement; like @kbd{M-a}
-except that it moves in the other direction (@code{c-end-of-statement}).
+Move point to the end of the innermost C statement or sentence; like
+@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
@table @kbd
@item C-c :
+@ifinfo
+@c This uses ``colon'' instead of a literal `:' because Info cannot
+@c cope with a `:' in a menu
+@kindex C-c @key{colon} @r{(C mode)}
+@end ifinfo
+@ifnotinfo
@kindex C-c : @r{(C mode)}
+@end ifnotinfo
@findex c-scope-operator
Insert a double colon scope operator at point, without reindenting the
line or adding any newlines (@code{c-scope-operator}).
@end table
+@vindex c-electric-pound-behavior
The electric @kbd{#} key reindents the line if it appears to be the
beginning of a preprocessor directive. This happens when the value of
@code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn
this feature off by setting @code{c-electric-pound-behavior} to
@code{nil}.
+@vindex c-hanging-braces-alist
The variable @code{c-hanging-braces-alist} controls the insertion of
newlines before and after inserted braces. It is an association list
with elements of the following form: @code{(@var{syntactic-symbol}
after, or both. If not found, the default is to insert a newline both
before and after braces.
+@vindex c-hanging-colons-alist
The variable @code{c-hanging-colons-alist} controls the insertion of
newlines before and after inserted colons. It is an association list
with elements of the following form: @code{(@var{syntactic-symbol}
If the syntactic symbol is not found in this list, no newlines are
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
@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
@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}).
@itemx M-x global-cwarn-mode
@findex cwarn-mode
@findex global-cwarn-mode
+@vindex global-cwarn-mode
@cindex CWarn mode
@cindex suspicious constructions in C, C++
CWarn minor mode highlights certain suspicious C and C++ constructions:
names.
@end table
-@node Comments in C
-@subsection Comments in C Modes
-
- C mode and related modes use a number of variables for controlling
-comment format.
-
-@table @code
-@item c-comment-only-line-offset
-@vindex c-comment-only-line-offset
-Extra offset for line which contains only the start of a comment. It
-can be either an integer or a cons cell of the form
-@code{(@var{non-anchored-offset} . @var{anchored-offset})}, where
-@var{non-anchored-offset} is the amount of offset given to
-non-column-zero anchored comment-only lines, and @var{anchored-offset}
-is the amount of offset to give column-zero anchored comment-only lines.
-Just an integer as value is equivalent to @code{(@var{val} . 0)}.
-
-@item c-comment-start-regexp
-@vindex c-comment-start-regexp
-This buffer-local variable specifies how to recognize the start of a comment.
-
-@item c-hanging-comment-ender-p
-@vindex c-hanging-comment-ender-p
-If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
-comment terminator of a block comment on a line by itself. The default
-value is @code{t}, which puts the comment-end delimiter @samp{*/} at the
-end of the last line of the comment text.
-
-@item c-hanging-comment-starter-p
-@vindex c-hanging-comment-starter-p
-If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
-starting delimiter of a block comment on a line by itself. The default
-value is @code{t}, which puts the comment-start delimiter @samp{/*} at
-the beginning of the first line of the comment text.
-@end table
-
@node Fortran
@section Fortran Mode
@cindex Fortran mode
@cindex Fortran77 and Fortran90
@findex f90-mode
@findex fortran-mode
- Fortan mode is meant for editing Fortran77 ``fixed format'' source
+ Fortran mode is meant for editing Fortran77 ``fixed format'' source
code. For editing the modern Fortran90 ``free format'' source code,
use F90 mode (@code{f90-mode}). Emacs normally uses Fortran mode for
files with extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode
@code{fortran-comment-indent-char} to the single-character string you want
to use.
+@vindex fortran-directive-re
+ Compiler directive lines, or preprocessor lines, have much the same
+appearance as comment lines. It is important, though, that such lines
+never be indented at all, no matter what the value of
+@code{fortran-comment-indent-style}. The variable
+@code{fortran-directive-re} is a regular expression that specifies which
+lines are directives. Matching lines are never indented, and receive
+distinctive font-locking.
+
@vindex comment-line-start
@vindex comment-line-start-skip
Fortran mode introduces two variables @code{comment-line-start} and
The variable @code{asm-comment-char} specifies which character
starts comments in assembler syntax.
+
+@ignore
+ arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0
+@end ignore