@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Programs, Building, Text, Top
@chapter Editing Programs
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
* Left Margin Paren:: An open-paren or similar opening delimiter
starts a defun if it is at the left margin.
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.
+outermost level. Some major modes, including C and related modes, set
+@code{open-paren-in-column-0-is-defun-start} buffer-locally to
+@code{nil}
@end defvar
-In buffers where @code{open-paren-in-column-0-is-defun-start} is
+ In modes 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
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
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
+scanning is rarely slow enough to annoy, so we've provided a way to
disable the heuristic.
@node Moving by Defuns
order to move it to a different place in the file. If you use the
command while point is between defuns, it uses the following defun.
Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode
-when the mark is active, includes an additional defun in the region
-each time.
+when the mark is active, extends the end of the region to include one
+more defun each time.
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
@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.
+if you have done that, you will have to wait a little while 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
Adjust indentation of current line.
@item C-j
Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
-@item @key{LINEFEED}
-This key, if the keyboard has it, is another way to enter @kbd{C-j}.
@end table
@kindex TAB @r{(programming modes)}
@kindex C-j
@findex newline-and-indent
When entering lines of new code, use @kbd{C-j}
-(@code{newline-and-indent}), which is equivalent to a @key{RET}
-followed by a @key{TAB}. @kbd{C-j} at the end of a line creates a
+(@code{newline-and-indent}), which is equivalent to @key{RET}
+followed by @key{TAB}. @kbd{C-j} at the end of a line creates a
blank line and then gives it the appropriate indentation.
@key{TAB} indents a line that starts within a parenthetical grouping
result of @key{TAB} because you find it unaesthetic for a particular
line.
- By default, an open-parenthesis, open-brace or other opening
+ In some modes, 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
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}.
+to use spaces only, set @code{indent-tabs-mode} (@pxref{Just Spaces}).
@node Multi-line Indent
@subsection Indenting Several Lines
@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).
+ To choose a style for the current buffer, use the command @w{@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
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.
+active, it extends the end of 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
that doesn't include meaningful parentheses (symbols, strings, etc.).
@kindex C-M-u
-@kindex C-M-d
@findex backward-up-list
-@findex down-list
@kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
parenthesis structure. To move @emph{up} one (or @var{n}) levels, use
@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up
repeat count; a negative argument reverses the direction of motion, so
that the command moves forward and up one or more levels.
+@kindex C-M-d
+@findex down-list
To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
(@code{down-list}). In Lisp mode, where @samp{(} is the only opening
delimiter, this is nearly the same as searching for a @samp{(}. An
that case, because the cursor appears on top of that character.) Use
the command @kbd{M-x show-paren-mode} to enable or disable this mode.
- By default, @code{show-paren-mode} uses colors to highlight the
-parentheses. However, if your display doesn't support colors, you can
-customize the faces @code{show-paren-match-face} and
-@code{show-paren-mismatch-face} to use other attributes, such as bold or
-underline. @xref{Face Customization}.
+ Show Paren mode uses the faces @code{show-paren-match} and
+@code{show-paren-mismatch} to highlight parentheses; you can customize
+them to control how highlighting looks. @xref{Face Customization}.
@node Comments
@section Manipulating Comments
start with (the value of @code{comment-start}; see below). Point is
after that string, so you can insert the text of the comment right
away. If the major mode has specified a string to terminate comments,
-@kbd{M-;} inserts that too, to keep the syntax valid.
+@kbd{M-;} inserts that after point, to keep the syntax valid.
- If the text of the line extends past the comment column, then the
-comment start string is indented to a suitable boundary (usually, at
-least one space is inserted).
+ If the text of the line extends past the comment column, this
+command indents the comment start string to a suitable boundary
+(usually, at least one space is inserted).
You can also use @kbd{M-;} to align an existing comment. If a line
already contains the comment-start string, @kbd{M-;} reindents it to
is a comment, it removes comment delimiters from each; otherwise, it
adds comment delimiters to each.) If you are not using Transient Mark
mode, then you should use the commands @code{comment-region} and
-@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}).
+@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}),
+or else enable Transient Mark mode momentarily (@pxref{Momentary Mark}).
A prefix argument used in these circumstances specifies how many
comment delimiters to add or how many to delete.
(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
+ For C-like modes, you can configure the exact effect of @kbd{M-;}
+more flexibly than for most buffers by setting the variables
@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
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.
+(@code{comment-indent-new-line}). If @code{comment-multi-line}
+(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new
+line within the comment. Otherwise it closes the comment and starts a
+new comment on a new 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
+comment-region} command (or type @kbd{C-c C-c} in C-like modes). 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.
@findex info-lookup-symbol
@findex info-lookup-file
@kindex C-h S
- For C, Lisp, and other languages that have documentation in Info,
-you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the Info
-documentation for a symbol used in the program. You specify the
-symbol with the minibuffer; the default is the symbol appearing in the
-buffer at point. For example, in C mode this looks for the symbol in
-the C Library Manual.
+ For many major modes, that apply to languages that have
+documentation in Info, you can use @kbd{C-h S}
+(@code{info-lookup-symbol}) to view the Info documentation for a
+symbol used in the program. You specify the symbol with the
+minibuffer; the default is the symbol appearing in the buffer at
+point. For example, in C mode this looks for the symbol in the C
+Library Manual. The command only works if the appropriate manual's
+Info files are installed.
The major mode determines where to look for documentation for the
symbol---which Info files to look in, and which indices to search.
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,
-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.
+ If you use @kbd{C-h S} in a major mode that does not support it,
+it asks you to specify the ``symbol help mode''. You should enter
+a command such as @code{c-mode} that would select a major
+mode which @kbd{C-h S} does support.
@node Man Page
@subsection Man Page Lookup
@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
+page} or @dfn{man page}. In the GNU operating system, we aim 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.
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 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}).
+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
pops up a window with possible candidates asking you to choose one of
them.
-@vindex woman-manpath
- By default, @kbd{M-x woman} looks for manual pages in the
-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 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
-list in the @code{woman-manpath} variable. Changing the value of this
-variable is another way to control the list of directories used.
-
-@vindex woman-path
- You can also augment the list of directories searched by
-@code{woman} by setting the value of the @code{woman-path} variable.
-This variable should hold a list of specific directories which
-@code{woman} should search, in addition to those in
-@code{woman-manpath}. Unlike @code{woman-manpath}, the directories in
-@code{woman-path} are searched for the manual pages, not for
-@file{man*} subdirectories.
-
-@findex woman-find-file
- Occasionally, you might need to display manual pages that are not in
-any of the directories listed by @code{woman-manpath} and
-@code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a
-name of a manual page file, with completion, and then formats and
-displays that file like @kbd{M-x woman} does.
-
-@vindex woman-dired-keys
- The first time you invoke @kbd{M-x woman}, it defines the Dired
-@kbd{W} key to run the @code{woman-find-file} command on the current
-line's file. You can disable this by setting the variable
-@code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition,
-the Tar-mode @kbd{w} key is define to invoke @code{woman-find-file} on
-the current line's archive member.
-
For more information about setting up and using @kbd{M-x woman}, see
@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
Manual}.
Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
@item hs-isearch-open
-Specifies what kind of hidden blocks to open in Isearch mode.
-The value should be one of these four symbols:
+Specifies what kind of hidden blocks incremental search should make
+visible. The value should be one of these four symbols:
@table @code
@item code
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
-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
-@findex c-forward-into-nomenclature
-Move point forward to end of a C++ nomenclature section or word.
-With prefix argument @var{n}, move @var{n} times.
@end table
@node Electric C
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}.
+@kbd{)}.
You might find electric indentation inconvenient if you are editing
chaotically indented code. If you are new to CC Mode, you might find
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 :}:
-
-@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}
-. @var{nl-list})}. Most of the syntactic symbols that appear in
-@code{c-offsets-alist} are meaningful here as well.
-
- The list @var{nl-list} may contain either of the symbols
-@code{before} or @code{after}, or both; or it may be @code{nil}. When a
-brace is inserted, the syntactic context it defines is looked up in
-@code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used
-to determine where newlines are inserted: either before the brace,
-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}
-. @var{nl-list})}. The list @var{nl-list} may contain either of the
-symbols @code{before} or @code{after}, or both; or it may be @code{nil}.
-
- When a colon is inserted, the syntactic symbol it defines is looked
-up in this list, and if found, the @var{nl-list} is used to determine
-where newlines are inserted: either before the brace, after, or both.
-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 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
-the @samp{@{}, if there is nothing between the braces aside from
-@code{catch} and @var{condition}.
-
-@item brace-else-brace
-Clean up @samp{@} else @{} constructs by placing the entire construct on
-a single line. The clean-up occurs when you type the @samp{@{} after
-the @code{else}, but only if there is nothing but white space between
-the braces and the @code{else}.
-
-@item brace-elseif-brace
-Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire
-construct on a single line. The clean-up occurs when you type the
-@samp{@{}, if there is nothing but white space between the @samp{@}} and
-@samp{@{} aside from the keywords and the @code{if}-condition.
-
-@item empty-defun-braces
-Clean up empty defun braces by placing the braces on the same
-line. Clean-up occurs when you type the closing brace.
-
-@item defun-close-semi
-Clean up the semicolon after a @code{struct} or similar type
-declaration, by placing the semicolon on the same line as the closing
-brace. Clean-up occurs when you type the semicolon.
-
-@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.
-@end table
+ Usually the CC Mode style configures the exact circumstances in
+which Emacs inserts auto-newlines. You can also configure this
+directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
@node Hungry Delete
@subsection Hungry Delete Feature in C
preprocessor commands.
@table @kbd
-@item C-c C-@key{BS}
-@itemx C-c @key{BS}
+@item C-c C-@key{DEL}
+@itemx C-c @key{DEL}
@findex c-hungry-backspace
-@kindex C-c C-@key{BS} (C Mode)
-@kindex C-c @key{BS} (C Mode)
+@kindex C-c C-@key{DEL} (C Mode)
+@kindex C-c @key{DEL} (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}
+@itemx C-c C-@key{DELETE}
+@itemx C-c @key{DELETE}
@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)
+@kindex C-c C-@key{DELETE} (C Mode)
+@kindex C-c @key{DELETE} (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.
+the mode line after the mode name), a single @key{DEL} deletes all
+preceding whitespace, not just one space, and a single @kbd{C-c C-d}
+(but @emph{not} plain @key{DELETE}) deletes all following whitespace.
@table @kbd
@item M-x c-toggle-hungry-state
@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.
+Enable (or disable) @dfn{subword mode}. In 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.
+
+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-context-line-break
@findex c-context-line-break