@c This is part of the Emacs manual.
-@c Copyright (C) 1985,86,87,93,94,95,97,99,2000 Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
+@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
@cindex C editing
@cindex program editing
- Emacs has many commands designed to understand the syntax of programming
-languages such as Lisp and C. These commands can
+ Emacs provides many features to facilitate editing programs. Some
+of these features can
@itemize @bullet
@item
-Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
+Find or move over top-level definitions (@pxref{Defuns}).
@item
-Move over or mark top-level expressions---@dfn{defuns}, in Lisp;
-functions, in C (@pxref{Defuns}).
+Apply the usual indentation conventions of the language
+(@pxref{Program Indent}).
@item
-Show how parentheses balance (@pxref{Matching}).
+Balance parentheses (@pxref{Parentheses}).
@item
Insert, kill or align comments (@pxref{Comments}).
@item
-Follow the usual indentation conventions of the language
-(@pxref{Program Indent}).
+Highlight program syntax (@pxref{Font Lock}).
@end itemize
- The commands for words, sentences and paragraphs are very useful in
-editing code even though their canonical application is for editing
-human language text. Most symbols contain words (@pxref{Words});
-sentences can be found in strings and comments (@pxref{Sentences}).
-Paragraphs per se don't exist in code, but the paragraph commands are
-useful anyway, because programming language major modes define
-paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
-Judicious use of blank lines to make the program clearer will also
-provide useful chunks of text for the paragraph commands to work
-on.
-
-@cindex selective display
-@cindex outline
-@cindex folding
-@findex outline-minor-mode
-@cindex outlines
- The selective display feature is useful for looking at the overall
-structure of a function (@pxref{Selective Display}). This feature
-causes only the lines that are indented less than a specified amount to
-appear on the screen. Programming modes often support Outline minor
-mode (@pxref{Outline Mode}). The Foldout package provides
-folding-editor features (@pxref{Foldout}).
-
- The `automatic typing' features may be useful when writing programs.
-@xref{,Autotyping,, autotype, Autotyping}.
+ This chapter describes these features and many more.
@menu
* Program Modes:: Major modes for editing programs.
-* Lists:: Expressions with balanced parentheses.
-* List Commands:: The commands for working with list and sexps.
-* Defuns:: Each program is made up of separate functions.
- There are editing commands to operate on them.
+* Defuns:: Commands to operate on major top-level parts
+ of a program.
* Program Indent:: Adjusting indentation to show the nesting.
-* Matching:: Insertion of a close-delimiter flashes matching open.
+* Parentheses:: Commands that operate on parentheses.
* Comments:: Inserting, killing, and aligning comments.
-* Balanced Editing:: Inserting two matching parentheses at once, etc.
-* Symbol Completion:: Completion on symbol names of your program or language.
-* Which Function:: Which Function mode shows which function you are in.
+* Documentation:: Getting documentation of functions you plan to call.
* Hideshow:: Displaying blocks selectively.
+* Symbol Completion:: Completion on symbol names of your program or language.
* Glasses:: Making identifiersLikeThis more readable.
-* Documentation:: Getting documentation of functions you plan to call.
-* Change Log:: Maintaining a change history for your program.
-* Authors:: Maintaining an @file{AUTHORS} file.
-* Tags:: Go direct to any function in your program in one
- command. Tags remembers which file it is in.
-* Imenu:: Making buffer indexes as menus.
-* Emerge:: A convenient way of merging two versions of a program.
+* Misc for Programs:: Other Emacs features useful for editing programs.
* C Modes:: Special commands of C, C++, Objective-C,
Java, and Pike modes.
-* Fortran:: Fortran mode and its special features.
* Asm Mode:: Asm mode and its special features.
+@ifnottex
+* Fortran:: Fortran mode and its special features.
+@end ifnottex
@end menu
@node Program Modes
@section Major Modes for Programming Languages
-
@cindex modes for programming languages
+
+ Emacs has specialized major modes for various programming languages.
+@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. 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 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 Metafont mode
@cindex Modula2 mode
@cindex Prolog mode
+@cindex Python mode
@cindex Simula mode
@cindex VHDL mode
@cindex M4 mode
@cindex Shell-script mode
@cindex Delphi mode
@cindex PostScript mode
- Emacs also has major modes for the programming languages Lisp, Scheme
-(a variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
-Awk, C, C++, Delphi (Object Pascal), Fortran (free and fixed format),
-Icon, IDLWAVE,
-Java, Metafont (@TeX{}'s companion for font creation), Modula2,
-Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Simula,
-VHDL, CORBA IDL, and Tcl.
-There is also a major mode for makefiles, called Makefile
-mode. An alternative mode for Perl is called CPerl mode. Modes
-are available for scripts for the common Unix shells, VMS DCL and
-MS-DOS/MS-Windows `BAT' files. In a similar fashion to programming
-languages, modes are provided for editing various sorts of configuration
+@cindex Conf mode
+@cindex DNS mode
+ The existing programming language major modes include Lisp, Scheme (a
+variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
+ASM, 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, Python, Simula, Tcl, and VHDL. An
+alternative mode for Perl is called CPerl mode. Modes are available for
+the 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 makefiles, DNS master files, and various sorts of configuration
files.
-Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
-Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL
+@kindex DEL @r{(programming modes)}
+@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 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/Pike/AWK
(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
-(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).
-
- Ideally, a major mode should be implemented for each programming
-language that you might want to edit with Emacs; but often the mode for
-one language can serve for other syntactically similar languages. The
-language modes that exist are those that someone decided to take the
-trouble to write.
-
- There are several forms of Lisp mode, which differ in the way they
-interface to Lisp execution. @xref{Executing Lisp}.
-
- Each of the programming language major modes defines the @key{TAB} key
-to run an indentation function that knows the indentation conventions of
-that language and updates the current line's indentation accordingly.
-For example, in C mode @key{TAB} is bound to @code{c-indent-line}.
-@kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB};
-thus, it too indents in a mode-specific fashion.
+(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran
+mode, see
+@iftex
+@ref{Fortran,,, emacs-xtra}.
+@end iftex
+@ifnottex
+@ref{Fortran}.
+@end ifnottex
-@kindex DEL @r{(programming modes)}
-@findex backward-delete-char-untabify
- In most programming languages, indentation is likely to vary from line to
-line. So the major modes for those languages rebind @key{DEL} to treat a
-tab as if it were the equivalent number of spaces (using the command
-@code{backward-delete-char-untabify}). This makes it possible to rub out
-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.
-
- Programming language modes define paragraphs to be separated only by
-blank lines, so that the paragraph commands remain useful. Auto Fill mode,
-if enabled in a programming language major mode, indents the new lines
-which it creates.
@cindex mode hook
@vindex c-mode-hook
@vindex emacs-lisp-mode-hook
@vindex lisp-interaction-mode-hook
@vindex scheme-mode-hook
- Turning on a major mode runs a normal hook called the @dfn{mode hook},
-which is the value of a Lisp variable. Each major mode has a mode hook,
-and the hook's name is always made from the mode command's name by
-adding @samp{-hook}. For example, turning on C mode runs the hook
-@code{c-mode-hook}, while turning on Lisp mode runs the hook
-@code{lisp-mode-hook}. @xref{Hooks}.
-
-@node Lists
-@section Lists and Sexps
-
-@cindex Control-Meta
- By convention, Emacs keys for dealing with balanced expressions are
-usually Control-Meta characters. They tend to be analogous in
-function to their Control and Meta equivalents. These commands are
-usually thought of as pertaining to expressions in programming
-languages, but can be useful with any language in which some sort of
-parentheses exist (including human languages).
-
-@cindex list
-@cindex sexp
-@cindex expression
-@cindex parentheses, moving across
-@cindex matching parenthesis, moving to
- These commands fall into two classes. Some deal only with @dfn{lists}
-(parenthetical groupings). They see nothing except parentheses, brackets,
-braces (whichever ones must balance in the language you are working with),
-and escape characters that might be used to quote those.
-
- The other commands deal with expressions or @dfn{sexps}. The word `sexp'
-is derived from @dfn{s-expression}, the ancient term for an expression in
-Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It
-refers to an expression in whatever language your program is written in.
-Each programming language has its own major mode, which customizes the
-syntax tables so that expressions in that language count as sexps.
-
- Sexps typically include symbols, numbers, and string constants, as well
-as anything contained in parentheses, brackets or braces.
-
- In languages that use prefix and infix operators, such as C, it is not
-possible for all expressions to be sexps. For example, C mode does not
-recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression;
-it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
-@samp{+} as punctuation between them. This is a fundamental ambiguity:
-both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
-move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a
-single sexp in C mode.
-
- Some languages have obscure forms of expression syntax that nobody
-has bothered to make Emacs understand properly.
-
-@node List Commands
-@section List And Sexp Commands
-
-@c doublewidecommands
-@table @kbd
-@item C-M-f
-Move forward over a sexp (@code{forward-sexp}).
-@item C-M-b
-Move backward over a sexp (@code{backward-sexp}).
-@item C-M-k
-Kill sexp forward (@code{kill-sexp}).
-@item C-M-@key{DEL}
-Kill sexp backward (@code{backward-kill-sexp}).
-@item C-M-u
-Move up and backward in list structure (@code{backward-up-list}).
-@item C-M-d
-Move down and forward in list structure (@code{down-list}).
-@item C-M-n
-Move forward over a list (@code{forward-list}).
-@item C-M-p
-Move backward over a list (@code{backward-list}).
-@item C-M-t
-Transpose expressions (@code{transpose-sexps}).
-@item C-M-@@
-Put mark after following expression (@code{mark-sexp}).
-@end table
-
-@kindex C-M-f
-@kindex C-M-b
-@findex forward-sexp
-@findex backward-sexp
- To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If
-the first significant character after point is an opening delimiter
-(@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
-moves past the matching closing delimiter. If the character begins a
-symbol, string, or number, @kbd{C-M-f} moves over that.
+ Turning on a major mode runs a normal hook called the @dfn{mode
+hook}, which is the value of a Lisp variable. Each major mode has a
+mode hook, and the hook's name is always made from the mode command's
+name by adding @samp{-hook}. For example, turning on C mode runs the
+hook @code{c-mode-hook}, while turning on Lisp mode runs the hook
+@code{lisp-mode-hook}. The purpose of the mode hook is to give you a
+place to set up customizations for that major mode. @xref{Hooks}.
- The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
-sexp. The detailed rules are like those above for @kbd{C-M-f}, but with
-directions reversed. If there are any prefix characters (single-quote,
-backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
-over them as well. The sexp commands move across comments as if they
-were whitespace in most modes.
+@node Defuns
+@section Top-Level Definitions, or Defuns
- @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
-specified number of times; with a negative argument, it moves in the
-opposite direction.
+ 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.
-@kindex C-M-k
-@findex kill-sexp
-@kindex C-M-DEL
-@findex backward-kill-sexp
- Killing a whole sexp 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.
+@menu
+* Left Margin Paren:: An open-paren or similar opening delimiter
+ starts a defun if it is at the left margin.
+* Moving by Defuns:: Commands to move over or mark a major definition.
+* Imenu:: Making buffer indexes as menus.
+* Which Function:: Which Function mode shows which function you are in.
+@end menu
-@kindex C-M-n
-@kindex C-M-p
-@findex forward-list
-@findex backward-list
- The @dfn{list commands} move over lists, as the sexp commands do, but skip
-blithely over any number of other kinds of sexps (symbols, strings, etc.).
-They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
-(@code{backward-list}). The main reason they are useful is that they
-usually ignore comments (since the comments usually do not contain any
-lists).@refill
+@node Left Margin Paren
+@subsection Left Margin Convention
-@kindex C-M-u
-@kindex C-M-d
-@findex backward-up-list
-@findex down-list
- @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
-that's possible. 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 past one unmatched opening delimiter. A
-positive argument serves as a repeat count; a negative argument reverses
-direction of motion and also requests repetition, so it moves forward and
-up one or more levels.@refill
-
- To move @emph{down} in list 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
-argument specifies the number of levels of parentheses to go down.
+@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. 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 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
+start of a top-level list.
-@cindex transposition
-@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 sexp
-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 sexps ending after point and the mark.
+ 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}).
-@kindex C-M-@@
-@findex mark-sexp
- To set the region around the next sexp 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 sexp.
+ 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:
- The list and sexp commands' understanding of syntax is completely
-controlled by the syntax table. Any character can, for example, be
-declared to be an opening delimiter and act like an open parenthesis.
-@xref{Syntax}.
+@example
+ (insert "Foo:
+\(bar)
+")
+@end example
-@node Defuns
-@section Defuns
+ 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, now that modern computers are so powerful, this
+scanning is rarely slow enough to annoy, so we've provided a way to
+disable the heuristic.
+
+@node Moving by Defuns
+@subsection Moving by Defuns
@cindex defuns
- In Emacs, a parenthetical grouping at the top level in the buffer is
-called a @dfn{defun}. The name derives from the fact that most top-level
-lists in a Lisp file are instances of the special form @code{defun}, but
-any top-level parenthetical grouping counts as a defun in Emacs parlance
-regardless of what its contents are, and regardless of the programming
-language in use. For example, in C, the body of a function definition is a
-defun.
+ These commands move point or set up the region based on top-level
+major definitions, also called @dfn{defuns}.
-@c doublewidecommands
@table @kbd
@item C-M-a
Move to beginning of current or preceding defun
Put region around whole current or following defun (@code{mark-defun}).
@end table
+@cindex move to beginning or end of function
+@cindex function, move to beginning or end
@kindex C-M-a
@kindex C-M-e
@kindex C-M-h
@findex beginning-of-defun
@findex end-of-defun
@findex mark-defun
- The commands to move to the beginning and end of the current defun are
-@kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
+ The commands to move to the beginning and end of the current defun
+are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
+(@code{end-of-defun}). If you repeat one of these commands, or use a
+positive numeric argument, each repetition moves to the next defun in
+the direction of motion.
+
+ @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
+@var{n} times to the next beginning of a defun. This is not exactly
+the same place that @kbd{C-M-e} with argument @var{n} would move to;
+the end of this defun is not usually exactly the same place as the
+beginning of the following defun. (Whitespace, comments, and perhaps
+declarations can separate them.) Likewise, @kbd{C-M-e} with a
+negative argument moves back to an end of a defun, which is not quite
+the same as @kbd{C-M-a} with a positive argument.
+@kindex C-M-h @r{(C mode)}
@findex c-mark-function
- If you wish to operate on the current defun, use @kbd{C-M-h}
-(@code{mark-defun}) which puts point at the beginning and mark at the end
-of the current or next defun. For example, this is the easiest way to get
-ready to move the defun to a different place in the text. 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}.
+ To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})
+which puts point at the beginning and mark at the end of the current
+defun. This is the easiest way to get ready to kill the defun in
+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, 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
+it backs up over the argument declarations, function name and returned
+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.
-@cindex open-parenthesis in leftmost column
-@cindex ( in leftmost column
- Emacs assumes that any open-parenthesis found in the leftmost column
-is the start of a defun. Therefore, @strong{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 starts the body
-of a function.} 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. It
-will not affect the contents of the string.
-
- In the remotest past, the original Emacs found defuns by moving upward a
-level of parentheses 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, Emacs was changed to assume
-that any @samp{(} (or other character assigned the syntactic class of
-opening-delimiter) at the left margin is the start of a defun. This
-heuristic is nearly always right and avoids the costly scan; however,
-it mandates the convention described above.
+@node Imenu
+@subsection Imenu
+@cindex index of buffer definitions
+@cindex buffer definitions index
+@cindex tags
+
+ 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.
+(@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 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 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 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
+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 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
+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.
+
+ Imenu provides the information to guide Which Function mode
+@ifnottex
+(@pxref{Which Function}).
+@end ifnottex
+@iftex
+(see below).
+@end iftex
+The Speedbar can also use it (@pxref{Speedbar}).
+
+@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
+buffer.
+
+@findex which-function-mode
+@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, it
+takes effect only 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
* Custom C Indent:: Controlling indentation style for C and related modes.
@end menu
+@cindex pretty-printer
Emacs also provides a Lisp pretty-printer in the library @code{pp}.
This program reformats a Lisp object with indentation chosen to look nice.
@node Basic Indent
@subsection Basic Program Indentation Commands
-@c WideCommands
+ The basic indentation commands indent a single line according to the
+usual conventions of the language you are editing.
+
@table @kbd
@item @key{TAB}
Adjust indentation of current line.
@item C-j
-Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
+Insert a newline, then adjust indentation of following line
+(@code{newline-and-indent}).
@end table
@kindex TAB @r{(programming modes)}
-@findex c-indent-line
-@findex lisp-indent-line
+@findex c-indent-command
+@findex indent-line-function
+@findex indent-for-tab-command
The basic indentation command is @key{TAB}, which gives the current line
the correct indentation as determined from the previous lines. The
-function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
-in Lisp mode, @code{c-indent-line} in C mode, etc. These functions
-understand different syntaxes for different languages, but they all do
-about the same thing. @key{TAB} in any programming-language major mode
+function that @key{TAB} runs depends on the major mode; it is
+@code{lisp-indent-line}
+in Lisp mode, @code{c-indent-command} in C mode, etc. These functions
+understand the syntax and conventions of different languages, but they all do
+conceptually the same job: @key{TAB} in any programming-language major mode
inserts or deletes whitespace at the beginning of the current line,
-independent of where point is in the line. If point is inside the
-whitespace at the beginning of the line, @key{TAB} leaves it at the end of
-that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
+independent of where point is in the line. If point was inside the
+whitespace at the beginning of the line, @key{TAB} puts it at the end of
+that whitespace; otherwise, @key{TAB} keeps point fixed with respect to
the characters around it.
- Use @kbd{C-q @key{TAB}} to insert a tab at point.
+ Use @kbd{C-q @key{TAB}} to insert a tab character at point.
@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} creates
-a blank line and then gives it the appropriate indentation.
-
- @key{TAB} indents the second and following lines of the body of a
-parenthetical grouping each under the preceding one; therefore, if you
-alter one line's indentation to be nonstandard, 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{Defuns}, for more
-information on this.
+ When entering lines of new code, use @kbd{C-j}
+(@code{newline-and-indent}), which inserts a newline and then adjusts
+indentation after it. (It also deletes any trailing whitespace which
+remains before the new newline.) Thus, @kbd{C-j} at the end of a line
+creates a blank line with appropriate indentation. In programming
+language modes, it is equivalent to @key{RET} @key{TAB}.
+
+ @key{TAB} indents a line that starts within a parenthetical grouping
+under the preceding line within the grouping, or the text after the
+parenthesis. Therefore, if you manually give one of these lines a
+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.
+
+ 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
+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, set @code{indent-tabs-mode} (@pxref{Just Spaces}).
@node Multi-line Indent
@subsection Indenting Several Lines
- When you wish to reindent several lines of code which have been altered
-or moved to a different level in the list structure, you have several
-commands available.
+ When you wish to reindent several lines of code which have been
+altered or moved to a different level in the parenthesis structure,
+you have several commands available.
@table @kbd
@item C-M-q
-Reindent all the lines within one list (@code{indent-sexp}).
-@item C-u @key{TAB}
-Shift an entire list rigidly sideways so that its first line
-is properly indented.
+Reindent all the lines within one parenthetical grouping (@code{indent-pp-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 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.
@end table
@kindex C-M-q
-@findex indent-sexp
- You can reindent the contents of a single list by positioning point
-before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
-Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable
-commands in other modes). The indentation of the line the sexp starts on
-is not changed; therefore, only the relative indentation within the list,
-and not its position, is changed. To correct the position as well, type a
-@key{TAB} before the @kbd{C-M-q}.
+@findex indent-pp-sexp
+ You can reindent the contents of a single parenthetical grouping by
+positioning point before the beginning of it and typing @kbd{C-M-q}
+(@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also
+bound to other suitable commands in other modes). The indentation of
+the line where the grouping starts is not changed; therefore this
+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 the relative indentation within a list is correct but the
-indentation of its first line is not, go to that line and type @kbd{C-u
-@key{TAB}}. @key{TAB} with a numeric argument reindents the current
-line as usual, then reindents by the same amount all the lines in the
-grouping starting on the current line. In other words, it reindents the
-whole grouping rigidly as a unit. It is clever, though, and does not
-alter lines that start inside strings, or C preprocessor lines when in C
-mode.
-
- 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.
+ 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
+reindent the whole grouping as a rigid unit. (This works in Lisp
+modes and C and related modes.) @key{TAB} with a numeric argument
+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. 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
+ 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.
+The prefix arg specifies the number of columns to indent.
@node Lisp Indent
@subsection Customizing Lisp Indentation
the containing list.
@vindex lisp-body-indent
- The standard pattern is overridden for certain functions. Functions
-whose names start with @code{def} always indent the second line by
-@code{lisp-body-indent} extra columns beyond the open-parenthesis
-starting the expression.
-
- The standard pattern can be overridden 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; the standard indentation pattern is used.
-@item @code{defun}
-The pattern used for function names that start with @code{def} is used for
-this function also.
-@item a number, @var{number}
-The first @var{number} arguments of the function are
-@dfn{distinguished} arguments; the rest are considered the @dfn{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 standard pattern is followed for that line.
-@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
+ Certain functions override the standard pattern. Functions whose
+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. 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
- Here are the commands for indentation in C mode and related modes:
+ Here are special features for indentation in C mode and related modes:
@table @code
@item C-c C-q
@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.
-
-@item C-u @key{TAB}
-Reindent the current line according to its syntax; also rigidly reindent
-any other lines of the expression that starts on the current line.
-@xref{Multi-line Indent}.
+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
@node Custom C Indent
@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 which you can customize.
-
-@menu
-* Syntactic Analysis::
-* Indentation Calculation::
-* Changing Indent Style::
-* Syntactic Symbols::
-* Variables for C Indent::
-* C Indent Styles::
-@end menu
-
-@node Syntactic Analysis
-@subsubsection Step 1---Syntactic Analysis
-@cindex syntactic analysis
-
- In the first step, the C indentation mechanism looks at the line
-before the one you are currently indenting and determines the syntactic
-components of the construct on that line. It builds a list of these
-syntactic components, each of which contains a @dfn{syntactic symbol}
-and sometimes also a buffer position. Some syntactic symbols describe
-grammatical elements, for example @code{statement} and
-@code{substatement}; others describe locations amidst grammatical
-elements, for example @code{class-open} and @code{knr-argdecl}.
-
- Conceptually, a line of C code is always indented relative to the
-indentation of some line higher up in the buffer. This is represented
-by the buffer positions in the syntactic component list.
-
- Here is an example. Suppose we have the following code in a C++ mode
-buffer (the line numbers don't actually appear in the buffer):
-
-@example
-1: void swap (int& a, int& b)
-2: @{
-3: int tmp = a;
-4: a = b;
-5: b = tmp;
-6: @}
-@end example
-
- If you type @kbd{C-c C-s} (which runs the command
-@code{c-show-syntactic-information}) on line 4, it shows the result of
-the indentation mechanism for that line:
-
-@example
-((statement . 32))
-@end example
-
- This indicates that the line is a statement and it is indented
-relative to buffer position 32, which happens to be the @samp{i} in
-@code{int} on line 3. If you move the cursor to line 3 and type
-@kbd{C-c C-s}, it displays this:
+ 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}.
-@example
-((defun-block-intro . 28))
-@end example
+@table @kbd
+@item C-c . @key{RET} @var{style} @key{RET}
+Select a predefined style @var{style} (@code{c-set-style}).
+@end table
- This indicates that the @code{int} line is the first statement in a
-block, and is indented relative to buffer position 28, which is the
-brace just after the function header.
+ 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 @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
+new style, you can type @kbd{C-x h C-M-\}.
-@noindent
-Here is another example:
+@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
-1: int add (int val, int incr, int doit)
-2: @{
-3: if (doit)
-4: @{
-5: return (val + incr);
-6: @}
-7: return (val);
-8: @}
+(setq c-default-style
+ '((java-mode . "java") (awk-mode . "awk") (other . "gnu")))
@end example
@noindent
-Typing @kbd{C-c C-s} on line 4 displays this:
-
-@example
-((substatement-open . 43))
-@end example
-
- This says that the brace @emph{opens} a substatement block. By the
-way, a @dfn{substatement} indicates the line after an @code{if},
-@code{else}, @code{while}, @code{do}, @code{switch}, @code{for},
-@code{try}, @code{catch}, @code{finally}, or @code{synchronized}
-statement.
-
-@cindex syntactic component
-@cindex syntactic symbol
-@vindex c-syntactic-context
- Within the C indentation commands, after a line has been analyzed
-syntactically for indentation, the variable @code{c-syntactic-context}
-contains a list that describes the results. Each element in this list
-is a @dfn{syntactic component}: a cons cell containing a syntactic
-symbol and (optionally) its corresponding buffer position. There may be
-several elements in a component list; typically only one element has a
-buffer position.
-
-@node Indentation Calculation
-@subsubsection Step 2---Indentation Calculation
-@cindex Indentation Calculation
-
- The C indentation mechanism calculates the indentation for the current
-line using the list of syntactic components, @code{c-syntactic-context},
-derived from syntactic analysis. Each component is a cons cell that
-contains a syntactic symbol and may also contain a buffer position.
-
- Each component contributes to the final total indentation of the line
-in two ways. First, the syntactic symbol identifies an element of
-@code{c-offsets-alist}, which is an association list mapping syntactic
-symbols into indentation offsets. Each syntactic symbol's offset adds
-to the total indentation. Second, if the component includes a buffer
-position, the column number of that position adds to the indentation.
-All these offsets and column numbers, added together, give the total
-indentation.
-
- The following examples demonstrate the workings of the C indentation
-mechanism:
-
-@example
-1: void swap (int& a, int& b)
-2: @{
-3: int tmp = a;
-4: a = b;
-5: b = tmp;
-6: @}
-@end example
-
- Suppose that point is on line 3 and you type @key{TAB} to reindent the
-line. As explained above (@pxref{Syntactic Analysis}), the syntactic
-component list for that line is:
-
-@example
-((defun-block-intro . 28))
-@end example
+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
- In this case, the indentation calculation first looks up
-@code{defun-block-intro} in the @code{c-offsets-alist} alist. Suppose
-that it finds the integer 2; it adds this to the running total
-(initialized to zero), yielding a updated total indentation of 2 spaces.
+@findex check-parens
+@cindex unbalanced parentheses and quotes
+ This section describes the commands and features that take advantage
+of the parenthesis structure in a program, or help you keep it
+balanced.
- The next step is to find the column number of buffer position 28.
-Since the brace at buffer position 28 is in column zero, this adds 0 to
-the running total. Since this line has only one syntactic component,
-the total indentation for the line is 2 spaces.
+ When talking about these facilities, the term ``parenthesis'' also
+includes braces, brackets, or whatever delimiters are defined to match
+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.
-@example
-1: int add (int val, int incr, int doit)
-2: @{
-3: if (doit)
-4: @{
-5: return(val + incr);
-6: @}
-7: return(val);
-8: @}
-@end example
+ You can use @kbd{M-x check-parens} to find any unbalanced
+parentheses and unbalanced string quotes in the buffer.
- If you type @key{TAB} on line 4, the same process is performed, but
-with different data. The syntactic component list for this line is:
+@menu
+* Expressions:: Expressions with balanced parentheses.
+* Moving by Parens:: Commands for moving up, down and across
+ in the structure of parentheses.
+* Matching:: Insertion of a close-delimiter flashes matching open.
+@end menu
-@example
-((substatement-open . 43))
-@end example
+@node Expressions
+@subsection Expressions with Balanced Parentheses
- Here, the indentation calculation's first job is to look up the
-symbol @code{substatement-open} in @code{c-offsets-alist}. Let's assume
-that the offset for this symbol is 2. At this point the running total
-is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43,
-which is the @samp{i} in @code{if} on line 3. This character is in
-column 2 on that line. Adding this yields a total indentation of 4
-spaces.
-
-@vindex c-strict-syntax-p
- If a syntactic symbol in the analysis of a line does not appear in
-@code{c-offsets-alist}, it is ignored; if in addition the variable
-@code{c-strict-syntax-p} is non-@code{nil}, it is an error.
-
-@node Changing Indent Style
-@subsubsection Changing Indentation Style
-
- There are two ways to customize the indentation style for the C-like
-modes. First, you can select one of several predefined styles, each of
-which specifies offsets for all the syntactic symbols. For more
-flexibility, you can customize the handling of individual syntactic
-symbols. @xref{Syntactic Symbols}, for a list of all defined syntactic
-symbols.
+@cindex sexp
+@cindex expression
+@cindex balanced expression
+ These commands deal with balanced expressions, also called
+@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an
+expression in Lisp.}.
@table @kbd
-@item M-x c-set-style @key{RET} @var{style} @key{RET}
-Select predefined indentation style @var{style}. Type @kbd{?} when
-entering @var{style} to see a list of supported styles; to find out what
-a style looks like, select it and reindent some C code.
-
-@item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET}
-Set the indentation offset for syntactic symbol @var{symbol}
-(@code{c-set-offset}). The second argument @var{offset} specifies the
-new indentation offset.
+@item C-M-f
+Move forward over a balanced expression (@code{forward-sexp}).
+@item C-M-b
+Move backward over a balanced expression (@code{backward-sexp}).
+@item C-M-k
+Kill balanced expression forward (@code{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
- The @code{c-offsets-alist} variable controls the amount of
-indentation to give to each syntactic symbol. Its value is an
-association list, and each element of the list has the form
-@code{(@var{syntactic-symbol} . @var{offset})}. By changing the offsets
-for various syntactic symbols, you can customize indentation in fine
-detail. To change this alist, use @code{c-set-offset} (see below).
-
- Each offset value in @code{c-offsets-alist} can be an integer, a
-function or variable name, a list, or one of the following symbols: @code{+},
-@code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative
-multiples of the variable @code{c-basic-offset}. Thus, if you want to
-change the levels of indentation to be 3 spaces instead of 2 spaces, set
-@code{c-basic-offset} to 3.
-
- Using a function as the offset value provides the ultimate flexibility
-in customizing indentation. The function is called with a single
-argument containing the @code{cons} of the syntactic symbol and
-the buffer position, if any. The function should return an integer
-offset.
-
- If the offset value is a list, its elements are processed according
-to the rules above until a non-@code{nil} value is found. That value is
-then added to the total indentation in the normal manner. The primary
-use for this is to combine the results of several functions.
-
-@kindex C-c C-o @r{(C mode)}
-@findex c-set-offset
- The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to
-set offsets, both interactively or in your @file{~/.emacs} file. First
-specify the syntactic symbol, then the offset you want. @xref{Syntactic
-Symbols}, for a list of valid syntactic symbols and their meanings.
-
-@node Syntactic Symbols
-@subsubsection Syntactic Symbols
-
- Here is a table of valid syntactic symbols for indentation in C and
-related modes, with their syntactic meanings. Normally, most of these
-symbols are assigned offsets in @code{c-offsets-alist}.
-
-@table @code
-@item string
-Inside a multi-line string.
-
-@item c
-Inside a multi-line C style block comment.
-
-@item defun-open
-On a brace that opens a function definition.
+ 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
+any pair of matching delimiters and their contents. Some languages
+have obscure forms of expression syntax that nobody has bothered to
+implement in Emacs.
-@item defun-close
-On a brace that closes a function definition.
+@cindex Control-Meta
+ 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.
-@item defun-block-intro
-In the first line in a top-level defun.
+@kindex C-M-f
+@kindex C-M-b
+@findex forward-sexp
+@findex backward-sexp
+ To move forward over a balanced expression, use @kbd{C-M-f}
+(@code{forward-sexp}). If the first significant character after point
+is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or
+@samp{@{} in C), @kbd{C-M-f} moves past the matching closing
+delimiter. If the character begins a symbol, string, or number,
+@kbd{C-M-f} moves over that.
-@item class-open
-On a brace that opens a class definition.
+ The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
+balanced expression. The detailed rules are like those above for
+@kbd{C-M-f}, but with directions reversed. If there are prefix
+characters (single-quote, backquote and comma, in Lisp) preceding the
+expression, @kbd{C-M-b} moves back over them as well. The balanced
+expression commands move across comments as if they were whitespace,
+in most modes.
-@item class-close
-On a brace that closes a class definition.
+ @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
+specified number of times; with a negative argument, it moves in the
+opposite direction.
-@item inline-open
-On a brace that opens an in-class inline method.
+@cindex killing expressions
+@kindex C-M-k
+@findex kill-sexp
+ Killing a whole balanced expression can be done with @kbd{C-M-k}
+(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f}
+would move over.
-@item inline-close
-On a brace that closes an in-class inline method.
+@cindex transposition of expressions
+@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.
-@item extern-lang-open
-On a brace that opens an external language block.
+@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 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
+multiple possibilities at a given position. For example, C mode does
+not treat @samp{foo + bar} as a single expression, even though it
+@emph{is} one C expression; instead, it recognizes @samp{foo} as one
+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}, 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
+
+@cindex parenthetical groupings
+@cindex parentheses, moving across
+@cindex matching parenthesis and braces, moving to
+@cindex braces, moving across
+@cindex list commands
+ The Emacs commands for handling parenthetical groupings see nothing
+except parentheses (or whatever characters must balance in the
+language you are working with), and the escape characters that might
+be used to quote those. They are mainly intended for editing
+programs, but can be useful for editing any text that has parentheses.
+They are sometimes called ``list'' commands because in Lisp these
+groupings are lists.
-@item extern-lang-close
-On a brace that closes an external language block.
+@table @kbd
+@item C-M-n
+Move forward over a parenthetical group (@code{forward-list}).
+@item C-M-p
+Move backward over a parenthetical group (@code{backward-list}).
+@item C-M-u
+Move up in parenthesis structure (@code{backward-up-list}).
+@item C-M-d
+Move down in parenthesis structure (@code{down-list}).
+@end table
-@item func-decl-cont
-The region between a function definition's argument list and the defun
-opening brace (excluding K&R function definitions). In C, you cannot
-put anything but whitespace and comments between them; in C++ and Java,
-@code{throws} declarations and other things can appear in this context.
+@kindex C-M-n
+@kindex C-M-p
+@findex forward-list
+@findex backward-list
+ The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and
+@kbd{C-M-p} (@code{backward-list}) move over one (or @var{n})
+parenthetical groupings, skipping blithely over any amount of text
+that doesn't include meaningful parentheses (symbols, strings, etc.).
-@item knr-argdecl-intro
-On the first line of a K&R C argument declaration.
+@kindex C-M-u
+@findex backward-up-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
+past one unmatched opening delimiter. A positive argument serves as a
+repeat count; a negative argument reverses the direction of motion, so
+that the command moves forward and up one or more levels.
-@item knr-argdecl
-In one of the subsequent lines in a K&R C argument declaration.
+@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
+argument specifies the number of levels to go down.
-@item topmost-intro
-On the first line in a topmost construct definition.
+@node Matching
+@subsection Automatic Display Of Matching Parentheses
+@cindex matching parentheses
+@cindex parentheses, displaying matches
-@item topmost-intro-cont
-On the topmost definition continuation lines.
+ The Emacs parenthesis-matching feature is designed to show
+automatically how parentheses (and other matching delimiters) match in
+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 of the text near it in the echo
+area. Either way, you can tell which grouping you are closing off.
-@item member-init-intro
-On the first line in a member initialization list.
+ If the opening delimiter and closing delimiter are mismatched---such
+as in @samp{[x)}---a warning message is displayed in the echo area.
-@item member-init-cont
-On one of the subsequent member initialization list lines.
+@vindex blink-matching-paren
+@vindex blink-matching-paren-distance
+@vindex blink-matching-delay
+ Three variables control parenthesis match display:
-@item inher-intro
-On the first line of a multiple inheritance list.
+ @code{blink-matching-paren} turns the feature on or off: @code{nil}
+disables it, but the default is @code{t} to enable match display.
-@item inher-cont
-On one of the subsequent multiple inheritance lines.
+ @code{blink-matching-delay} says how many seconds to leave the
+cursor on the matching opening delimiter, before bringing it back to
+the real location of point; the default is 1, but on some systems it
+is useful to specify a fraction of a second.
-@item block-open
-On a statement block open brace.
+ @code{blink-matching-paren-distance} specifies how many characters
+back to search to find the matching opening delimiter. If the match
+is not found in that distance, scanning stops, and nothing is displayed.
+This is to prevent the scan for the matching delimiter from wasting
+lots of time when there is no match. The default is 25600.
-@item block-close
-On a statement block close brace.
+@cindex Show Paren mode
+@cindex highlighting matching parentheses
+@findex show-paren-mode
+ Show Paren mode provides a more powerful kind of automatic matching.
+Whenever point is after a closing delimiter, that delimiter and its
+matching opening delimiter are both highlighted; otherwise, if point
+is before an opening delimiter, the matching closing delimiter is
+highlighted. (There is no need to highlight the opening delimiter in
+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.
+
+ 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}.
-@item brace-list-open
-On the opening brace of an @code{enum} or @code{static} array list.
+@node Comments
+@section Manipulating Comments
+@cindex comments
-@item brace-list-close
-On the closing brace of an @code{enum} or @code{static} array list.
+ Because comments are such an important part of programming, Emacs
+provides special commands for editing and inserting comments. It can
+also do spell checking on comments with Flyspell Prog mode
+(@pxref{Spelling}).
-@item brace-list-intro
-On the first line in an @code{enum} or @code{static} array list.
+@menu
+* Comment Commands:: Inserting, killing, and aligning comments.
+* Multi-Line Comments:: Commands for adding and editing multi-line comments.
+* Options for Comments::Customizing the comment features.
+@end menu
-@item brace-list-entry
-On one of the subsequent lines in an @code{enum} or @code{static} array
-list.
+@node Comment Commands
+@subsection Comment Commands
+@cindex indentation for comments
+@cindex alignment for comments
-@item brace-entry-open
-On one of the subsequent lines in an @code{enum} or @code{static} array
-list, when the line begins with an open brace.
+ The comment commands in this table insert, kill and align comments.
+They are described in this section and following sections.
-@item statement
-On an ordinary statement.
+@table @asis
+@item @kbd{M-;}
+Insert or realign comment on current line; alternatively, comment or
+uncomment the region (@code{comment-dwim}).
+@item @kbd{C-u M-;}
+Kill comment on current line (@code{comment-kill}).
+@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
-@item statement-cont
-On a continuation line of a statement.
+@kindex M-;
+@findex comment-dwim
+ The command to create or align a comment is @kbd{M-;}
+(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What
+I Mean''; it indicates that this command can be used for many
+different jobs relating to comments, depending on the situation where
+you use it.
+
+ If there is no comment already on the line, @kbd{M-;} inserts a new
+comment, aligned at a specific column called the @dfn{comment column}.
+The new comment begins with the string Emacs thinks comments should
+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 after point, to keep the syntax valid.
+
+ If the text of the line extends past the comment column, this
+command aligns 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-;} realigns it to
+the conventional alignment and moves point after it. (Exception:
+comments starting in column 0 are not moved.) Even when an existing
+comment is properly aligned, @kbd{M-;} is still useful for moving
+directly to the start of the text inside the comment.
+
+@findex comment-kill
+@kindex C-u M-;
+ @kbd{C-u M-;} kills any comment on the current line, along with the
+whitespace before it. To reinsert the comment on another line, move
+to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
+realign it.
+
+ Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}
+(@code{comment-dwim}) with a prefix argument. That command is
+programmed so that when it receives a prefix argument it calls
+@code{comment-kill}. However, @code{comment-kill} is a valid command
+in its own right, and you can bind it directly to a key if you wish.
+
+ @kbd{M-;} does two other jobs when used with an active region in
+Transient Mark mode (@pxref{Transient Mark}). Then it either adds or
+removes comment delimiters on each line of the region. (If every line
+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}),
+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.
+
+ Some major modes have special rules for aligning certain kinds of
+comments in certain contexts. For example, in Lisp code, comments which
+start with two semicolons are indented as if they were lines of code,
+instead of at the comment column. Comments which start with three
+semicolons are supposed to start at the left margin. Emacs understands
+these conventions by indenting a double-semicolon comment using @key{TAB},
+and by not changing the indentation of a triple-semicolon comment at all.
-@item statement-block-intro
-On the first line in a new statement block.
+@example
+;; This function is just an example
+;;; Here either two or three semicolons are appropriate.
+(defun foo (x)
+;;; And now, the first part of the function:
+ ;; The following line adds one.
+ (1+ x)) ; This line adds one.
+@end example
-@item statement-case-intro
-On the first line in a @code{case} ``block.''
+ 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
+the brace rather than at @code{comment-column}. For full details see
+@ref{Comment Commands,,, ccmode, The CC Mode Manual}.
-@item statement-case-open
-On the first line in a @code{case} block starting with brace.
+@node Multi-Line Comments
+@subsection Multiple Lines of Comments
-@item inexpr-statement
-On a statement block inside an expression. This is used for a GNU
-extension to the C language, and for Pike special functions that take a
-statement block as an argument.
+@kindex C-M-j
+@kindex M-j
+@cindex blank lines in programs
+@findex comment-indent-new-line
-@item inexpr-class
-On a class definition inside an expression. This is used for anonymous
-classes and anonymous array initializers in Java.
+ 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}). 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 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.
-@item substatement
-On the first line after an @code{if}, @code{while}, @code{for},
-@code{do}, or @code{else}.
+ 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 aligned or 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}.
-@item substatement-open
-On the brace that opens a substatement block.
+@node Options for Comments
+@subsection Options Controlling Comments
-@item case-label
-On a @code{case} or @code{default} label.
-
-@item access-label
-On a C++ @code{private}, @code{protected}, or @code{public} access label.
-
-@item label
-On any ordinary label.
-
-@item do-while-closure
-On the @code{while} that ends a @code{do}-@code{while} construct.
-
-@item else-clause
-On the @code{else} of an @code{if}-@code{else} construct.
-
-@item catch-clause
-On the @code{catch} and @code{finally} lines in
-@code{try}@dots{}@code{catch} constructs in C++ and Java.
-
-@item comment-intro
-On a line containing only a comment introduction.
-
-@item arglist-intro
-On the first line in an argument list.
-
-@item arglist-cont
-On one of the subsequent argument list lines when no arguments follow on
-the same line as the arglist opening parenthesis.
-
-@item arglist-cont-nonempty
-On one of the subsequent argument list lines when at least one argument
-follows on the same line as the arglist opening parenthesis.
-
-@item arglist-close
-On the closing parenthesis of an argument list.
-
-@item stream-op
-On one of the lines continuing a stream operator construct.
-
-@item inclass
-On a construct that is nested inside a class definition. The
-indentation is relative to the open brace of the class definition.
-
-@item inextern-lang
-On a construct that is nested inside an external language block.
-
-@item inexpr-statement
-On the first line of statement block inside an expression. This is used
-for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}.
-It is also used for the special functions that takes a statement block
-as an argument in Pike.
-
-@item inexpr-class
-On the first line of a class definition inside an expression. This is
-used for anonymous classes and anonymous array initializers in Java.
-
-@item cpp-macro
-On the start of a cpp macro.
-
-@item friend
-On a C++ @code{friend} declaration.
-
-@item objc-method-intro
-On the first line of an Objective-C method definition.
-
-@item objc-method-args-cont
-On one of the lines continuing an Objective-C method definition.
-
-@item objc-method-call-cont
-On one of the lines continuing an Objective-C method call.
-
-@item inlambda
-Like @code{inclass}, but used inside lambda (i.e. anonymous) functions. Only
-used in Pike.
-
-@item lambda-intro-cont
-On a line continuing the header of a lambda function, between the
-@code{lambda} keyword and the function body. Only used in Pike.
-@end table
-
-@node Variables for C Indent
-@subsubsection Variables for C Indentation
-
- This section describes additional variables which control the
-indentation behavior of C mode and related mode.
-
-@table @code
-@item c-offsets-alist
-@vindex c-offsets-alist
-Association list of syntactic symbols and their indentation offsets.
-You should not set this directly, only with @code{c-set-offset}.
-@xref{Changing Indent Style}, for details.
-
-@item c-style-alist
-@vindex c-style-alist
-Variable for defining indentation styles; see below.
-
-@item c-basic-offset
-@vindex c-basic-offset
-Amount of basic offset used by @code{+} and @code{-} symbols in
-@code{c-offsets-alist}.@refill
-
-@item c-special-indent-hook
-@vindex c-special-indent-hook
-Hook for user-defined special indentation adjustments. This hook is
-called after a line is indented by C mode and related modes.
-@end table
-
- The variable @code{c-style-alist} specifies the predefined indentation
-styles. Each element has form @code{(@var{name}
-@var{variable-setting}@dots{})}, where @var{name} is the name of the
-style. Each @var{variable-setting} has the form @code{(@var{variable}
-. @var{value})}; @var{variable} is one of the customization variables
-used by C mode, and @var{value} is the value for that variable when
-using the selected style.
-
- When @var{variable} is @code{c-offsets-alist}, that is a special case:
-@var{value} is appended to the front of the value of @code{c-offsets-alist}
-instead of replacing that value outright. Therefore, it is not necessary
-for @var{value} to specify each and every syntactic symbol---only those
-for which the style differs from the default.
-
- The indentation of lines containing only comments is also affected by
-the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}).
-
-@node C Indent Styles
-@subsubsection C Indentation Styles
-@cindex c indentation styles
-
- A @dfn{C style} is a collection of indentation style customizations.
-Emacs comes with several predefined indentation styles for C and related
-modes, 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}.
-
-@findex c-set-style
-@vindex c-default-style
- To choose the style you want, use the command @kbd{M-x c-set-style}.
-Specify a style name as an argument (case is not significant in C style
-names). The chosen style only affects newly visited buffers, not those
-you are already editing. You can also set the variable
-@code{c-default-style} to specify the 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,
-
-@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.
-
- The style @code{gnu} defines the formatting recommend by the GNU
-Project; it is the default, so as to encourage the indentation we
-recommend. If you make changes in variables such as
-@code{c-basic-offset} and @code{c-offsets-alist} in your @file{~/.emacs}
-file, they will however take precedence.
-
-@findex c-add-style
- To define a new C indentation style, call the function
-@code{c-add-style}:
-
-@example
-(c-add-style @var{name} @var{values} @var{use-now})
-@end example
-
-@noindent
-Here @var{name} is the name of the new style (a string), and
-@var{values} is an alist whose elements have the form
-@code{(@var{variable} . @var{value})}. The variables you specify should
-be among those documented in @ref{Variables for C Indent}.
-
- If @var{use-now} is non-@code{nil}, @code{c-add-style} selects the new
-style after defining it.
-
-@node Matching
-@section Automatic Display Of Matching Parentheses
-@cindex matching parentheses
-@cindex parentheses, displaying matches
-
- The Emacs parenthesis-matching feature is designed to show
-automatically how parentheses match in 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, some text near it is
-displayed in the echo area. Either way, you can tell what grouping is
-being closed off.
-
- In Lisp, automatic matching applies only to parentheses. In C, it
-applies to braces and brackets too. Emacs knows which characters to regard
-as matching delimiters based on the syntax table, which is set by the major
-mode. @xref{Syntax}.
-
- If the opening delimiter and closing delimiter are mismatched---such as
-in @samp{[x)}---a warning message is displayed in the echo area. The
-correct matches are specified in the syntax table.
-
-@vindex blink-matching-paren
-@vindex blink-matching-paren-distance
-@vindex blink-matching-delay
- Three variables control parenthesis match display.
-@code{blink-matching-paren} turns the feature on or off; @code{nil}
-turns it off, but the default is @code{t} to turn match display on.
-@code{blink-matching-delay} says how many seconds to wait; the default
-is 1, but on some systems it is useful to specify a fraction of a
-second. @code{blink-matching-paren-distance} specifies how many
-characters back to search to find the matching opening delimiter. If
-the match is not found in that far, scanning stops, and nothing is
-displayed. This is to prevent scanning for the matching delimiter from
-wasting lots of time when there is no match. The default is 12,000.
-
-@cindex Show Paren mode
-@findex show-paren-mode
- When using X Windows, you can request a more powerful alternative kind
-of automatic parenthesis matching by enabling Show Paren mode. This
-mode turns off the usual kind of matching parenthesis display and
-instead uses highlighting to show what matches. Whenever point is after
-a close parenthesis, the close parenthesis and its matching open
-parenthesis are both highlighted; otherwise, if point is before an open
-parenthesis, the matching close parenthesis is highlighted. (There is
-no need to highlight the open parenthesis after point because the cursor
-appears on top of that character.) Use the command @kbd{M-x
-show-paren-mode} to enable or disable this mode.
-
-@node Comments
-@section Manipulating Comments
-@cindex comments
-
- Because comments are such an important part of programming, Emacs
-provides special commands for editing and inserting comments.
-
-@menu
-* Comment Commands::
-* Multi-Line Comments::
-* Options for Comments::
-@end menu
-
-@node Comment Commands
-@subsection Comment Commands
-
-@kindex M-;
-@cindex indentation for comments
-@findex indent-for-comment
-
- The comment commands insert, kill and align comments.
-
-@c WideCommands
-@table @kbd
-@item M-;
-Insert or align comment (@code{indent-for-comment}).
-@item C-x ;
-Set comment column (@code{set-comment-column}).
-@item C-u - C-x ;
-Kill comment on current line (@code{kill-comment}).
-@item C-M-j
-Like @key{RET} followed by inserting and aligning a comment
-(@code{indent-new-comment-line}).
-@item M-x comment-region
-Add or remove comment delimiters on all the lines in the region.
-@end table
-
- The command that creates a comment is @kbd{M-;} (@code{indent-for-comment}).
-If there is no comment already on the line, a new comment is created,
-aligned at a specific column called the @dfn{comment column}. The comment
-is created by inserting the string Emacs thinks comments should start with
-(the value of @code{comment-start}; see below). Point is left after that
-string. If the text of the line extends past the comment column, then the
-indentation is done to a suitable boundary (usually, at least one space is
-inserted). If the major mode has specified a string to terminate comments,
-that is inserted after point, to keep the syntax valid.
-
- @kbd{M-;} can also be used to align an existing comment. If a line
-already contains the string that starts comments, then @kbd{M-;} just moves
-point after it and reindents it to the conventional place. Exception:
-comments starting in column 0 are not moved.
-
- Some major modes have special rules for indenting certain kinds of
-comments in certain contexts. For example, in Lisp code, comments which
-start with two semicolons are indented as if they were lines of code,
-instead of at the comment column. Comments which start with three
-semicolons are supposed to start at the left margin. Emacs understands
-these conventions by indenting a double-semicolon comment using @key{TAB},
-and by not changing the indentation of a triple-semicolon comment at all.
-
-@example
-;; This function is just an example
-;;; Here either two or three semicolons are appropriate.
-(defun foo (x)
-;;; 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.
-
- Even when an existing comment is properly aligned, @kbd{M-;} is still
-useful for moving directly to the start of the comment.
-
-@kindex C-u - C-x ;
-@findex kill-comment
- @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line,
-if there is one. The indentation before the start of the comment is killed
-as well. If there does not appear to be a comment in the line, nothing is
-done. To reinsert the comment on another line, move to the end of that
-line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that
-@kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
-with a negative argument. That command is programmed so that when it
-receives a negative argument it calls @code{kill-comment}. However,
-@code{kill-comment} is a valid command which you could bind directly to a
-key if you wanted to.
-
-@node Multi-Line Comments
-@subsection Multiple Lines of Comments
-
-@kindex C-M-j
-@cindex blank lines in programs
-@findex indent-new-comment-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{indent-new-comment-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.
-
-@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, if between defuns, and
-three, if within a defun.
-
-@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.
-
-@node Options for Comments
-@subsection Options Controlling Comments
-
-@vindex comment-column
-@kindex C-x ;
-@findex set-comment-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{set-comment-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. Note that @kbd{C-u - C-x ;}
-runs the function @code{kill-comment} as described above.
+@vindex comment-column
+@kindex C-x ;
+@findex comment-set-column
+ 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
@vindex comment-start-skip
The comment commands recognize comments based on the regular
-expression that is the value of the variable @code{comment-start-skip}.
-Make sure this regexp does not match the null string. It may match more
-than the comment starting delimiter in the strictest sense of the word;
-for example, in C mode the value of the variable is @code{@t{"/\\*+
-*"}}, which matches extra stars and spaces after the @samp{/*} itself.
-(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
-in regexp syntax. @xref{Regexps}.)
-
-@vindex comment-start
-@vindex comment-end
- When a comment command makes a new comment, it inserts the value of
-@code{comment-start} to begin it. The value of @code{comment-end} is
-inserted after point, so that it will follow the text that you will insert
-into the comment. In C mode, @code{comment-start} has the value
-@w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
-
-@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.
-
-@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
-various major modes. The function is called with no arguments, but with
-point at the beginning of the comment, or at the end of a line if a new
-comment is to be inserted. It should return the column in which the
-comment ought to start. For example, in Lisp mode, the indent hook
-function bases its decision on how many semicolons begin an existing
-comment, and on the code in the preceding lines.
-
-@node Balanced Editing
-@section Editing Without Unbalanced Parentheses
-
-@table @kbd
-@item M-(
-Put parentheses around next sexp(s) (@code{insert-parentheses}).
-@item M-)
-Move past next close parenthesis and reindent
-(@code{move-past-close-and-reindent}).
-@end table
-
-@kindex M-(
-@kindex M-)
-@findex insert-parentheses
-@findex move-past-close-and-reindent
- The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
-(@code{move-past-close-and-reindent}) are designed to facilitate a style
-of editing which keeps parentheses balanced at all times. @kbd{M-(}
-inserts a pair of parentheses, either together as in @samp{()}, or, if
-given an argument, around the next several sexps. It leaves point after
-the open parenthesis. The command @kbd{M-)} moves past the close
-parenthesis, deleting any indentation preceding it, and indenting with
-@kbd{C-j} after it.
-
- For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-(
-F O O}, which has the same effect except for leaving the cursor before
-the close parenthesis.
-
-@vindex parens-require-spaces
- @kbd{M-(} may insert a space before the open parenthesis, depending on
-the syntax class of the preceding character. Set
-@code{parens-require-spaces} to @code{nil} value if you wish to inhibit
-this.
-
-@findex check-parens
-You can use @kbd{M-x check-parens} to find any unbalanced parentheses in
-a buffer.
-
-@node Symbol Completion
-@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.
-
-@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.
-
- 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.
-
-@cindex completion using tags
-@cindex tags completion
-@cindex Info index completion
-@findex complete-symbol
- In most programming language major modes, @kbd{M-@key{TAB}} runs the
-command @code{complete-symbol}, which provides two kinds of completion.
-Normally it does completion based on a tags table (@pxref{Tags}); with a
-numeric argument (regardless of the value), it does completion based on
-the names listed in the Info file indexes for your language. Thus, to
-complete the name of a symbol defined in your own program, use
-@kbd{M-@key{TAB}} with no argument; to complete the name of a standard
-library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
-completion works only if there is an Info file for the standard library
-functions of your language, and only if it is installed at your site.
-
-@cindex Lisp symbol completion
-@cindex completion in Lisp
-@findex lisp-complete-symbol
- In Emacs-Lisp mode, the name space for completion normally consists of
-nontrivial symbols present in Emacs---those that have function
-definitions, values or properties. However, if there is an
-open-parenthesis immediately before the beginning of the partial symbol,
-only symbols with function definitions are considered as completions.
-The command which implements this is @code{lisp-complete-symbol}.
-
- In Text mode and related modes, @kbd{M-@key{TAB}} completes words
-based on the spell-checker's dictionary. @xref{Spelling}.
-
-@node Which Function
-@section Which Function Mode
-
- Which Function mode is a minor mode that displays the current function
-name in the mode line, as you move around in a buffer.
-
-@findex which-function-mode
-@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.)
-
-@node Hideshow
-@section Hideshow minor mode
-
-@findex hs-minor-mode
-Hideshow minor mode provides selective display of blocks. Use @kbd{M-x
-hs-minor-mode} to toggle the mode or add @code{hs-minor-mode} to the
-hook for major modes with which you want to use it and which support it.
-
-Blocks are defined dependent on the mode. In C mode or C++ mode, they
-are delimited by braces, while in Lisp-ish modes they are delimited by
-parens. Multi-line comments can also be hidden.
-
-@findex hs-hide-all
-@findex hs-hide-block
-@findex hs-show-all
-@findex hs-show-block
-@findex hs-show-region
-@findex hs-hide-level
-@findex hs-minor-mode
-@kindex C-c h
-@kindex C-c s
-@kindex C-c H
-@kindex C-c S
-@kindex C-c R
-@kindex C-c L
-@kindex S-mouse-2
-The mode provides the commands @kbd{C-c h} (@kbd{M-x hs-hide-all}),
-@kbd{C-c s} (@kbd{M-x hs-hide-block}), @kbd{C-c H} (@kbd{M-x
-hs-show-all}), @kbd{C-c S} (@kbd{M-x hs-show-block}), @kbd{C-c R}
-(@kbd{M-x hs-show-region}) and @kbd{C-c L} (@kbd{M-x hs-hide-level})
-with obvious functions and @kbd{S-mouse-2} toggles hiding of a block
-with the mouse.
-
-@vindex hs-hide-comments-when-hiding-all
-@vindex hs-show-hidden-short-form
-@vindex hs-isearch-open
-@vindex hs-special-modes-alist
-Hideshow is customized by the variables
-@table @code
-@item hs-hide-comments-when-hiding-all
-Specifies whether @kbd{hs-hide-all} should hide comments too.
-@item hs-show-hidden-short-form
-Specifies whether or not the last line in a form is omitted (saving
-screen space).
-@item hs-isearch-open
-Specifies what kind of hidden blocks to open in Isearch mode.
-@item hs-special-modes-alist
-Initializes Hideshow variables for different modes.
-@end table
-
-@node Glasses
-@section Glasses minor mode
-@cindex Glasses mode
-@cindex identifiers, unreadable
-@cindex StudlyCaps
-@findex glasses-mode
-
-Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} readable
-by displaying underscores between all the pairs of lower and upper
-English letters or by emboldening the capitals. The text is not
-altered, only the display, so that you can use this mode on code written
-with such a convention for separating words in identifiers without
-modifying the code. It can be customized under the group
-@samp{glasses}. You can use it by adding @code{glasses-mode} to the
-mode hook of appropriate programming modes.
-
-
-@node Documentation
-@section Documentation Commands
-
- As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
-(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
-be used to print documentation of functions and variables that you want to
-call. These commands use the minibuffer to read the name of a function or
-variable to document, and display the documentation in a window.
-
- For extra convenience, these commands provide default arguments based on
-the code in the neighborhood of point. @kbd{C-h f} sets the default to the
-function called in the innermost list containing point. @kbd{C-h v} uses
-the symbol name around or adjacent to point as its default.
-
-@cindex Eldoc mode
-@findex eldoc-mode
- For Emacs Lisp code, you can also use Eldoc mode. This minor mode
-constantly displays in the echo area the argument list for the function
-being called at point. (In other words, it finds the function call that
-point is contained in, and displays the argument list of that function.)
-Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use
-the command @kbd{M-x eldoc-mode} to enable or disable this feature.
-
-@findex info-lookup-symbol
-@findex info-lookup-file
-@kindex C-h C-i
- For C, Lisp, and other languages, you can use @kbd{C-h C-i}
-(@code{info-lookup-symbol}) to view the Info documentation for a symbol.
-You specify the symbol with the minibuffer; by default, it uses the
-symbol that appears in the buffer at point. The major mode determines
-where to look for documentation for the symbol---which Info files and
-which indices. You can also use @kbd{M-x info-lookup-file} to look for
-documentation for a file name. Currently the modes supported by
-Info-lookup are: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4,
-Makefile, Octave, Perl, Scheme and Texinfo. The relevant Info files
-mostly must be obtained separately, typically from the appropriate GNU
-package.
-
-@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 exit.) The result goes in a buffer
-named @samp{*Man @var{topic}*}. These buffers use a special major mode,
-Man mode, that facilitates scrolling and examining other manual pages.
-For details, type @kbd{C-h m} while in a man page buffer.
-
-@cindex sections of manual pages
- Man pages are subdivided into @dfn{sections}, and some man pages have
-identical names, but belong to different sections. To read a man page
-from a certain section, type @kbd{@var{topic}(@var{section})} or
-@kbd{@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 @code{2v}).
-
- 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 the
-first man page they find, others display all the man pages, and you can
-page between them with the @kbd{M-n} and @kbd{M-p} keys. The mode line
-shows how many manual pages are available in the Man buffer.
-
-@vindex Man-fontify-manpage-flag
- For a long man page, setting the faces properly can take substantial
-time. By default, Emacs uses faces in man pages if Emacs can display
-different fonts or colors. You can turn off use of faces in 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
-other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
-perform the same conversions that @kbd{M-x manual-entry} does.
-
-@findex woman
-@cindex manual pages, on MS-DOS/MS-Windows
- An alternative way of reading manual pages is the @kbd{M-x woman}
-command@footnote{The name of the command, @code{woman}, is an acronym
-for ``w/o (without) man'', since it doesn't use the @code{man}
-program.}. Unlike @kbd{M-x man}, it does not run any external programs
-to format and display the man pages, instead it does that entirely in
-Emacs Lisp. Thus, it is useful on systems such as MS-Windows, where the
-@code{man} program and the programs it runs are not readily available.
-When invoked, @kbd{M-x woman} prompts for a name of a manual page and
-provides completion based on the list of manual pages that are installed
-on your machine; the list of available manual pages is computed
-automatically the first time you invoke @code{woman}. The word at point
-in the current buffer is used to suggest the default name of the manual
-page.
-
- With a numeric argument, @kbd{M-x woman} recomputes the list of the
-manual pages used for completion. This is useful if you add or delete
-manual pages.
-
- If you type a name of a manual page and @kbd{M-x woman} finds that
-several manual pages by the same name exist in different sections, it
-pops up a window with possible candidates asking you to choose one of
-them.
-
-@vindex woman-manpath
- By default, @kbd{M-x woman} looks up the manual pages in directories
-listed by 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 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. By changing the value of this variable, you can customize the
-list of directories where @code{woman} looks for manual pages.
-
-@vindex woman-path
- In addition, you can 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
- 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 bound to @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}.
-
- Eventually the GNU project hopes to replace most man pages with
-better-organized manuals that you can browse with Info. @xref{Misc
-Help}. Since this process is only partially completed, it is still
-useful to read manual pages.
-
-@node Change Log
-@section Change Logs
-
-@cindex change log
-@kindex C-x 4 a
-@findex add-change-log-entry-other-window
- The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
-file for the file you are editing
-(@code{add-change-log-entry-other-window}). If that file is actually a
-backup file, it makes an entry appropriate for the file's parent. This
-is useful for making log entries by comparing a version with deleted
-functions.
-
- A change log file contains a chronological record of when and why you
-have changed a program, consisting of a sequence of entries describing
-individual changes. Normally it is kept in a file called
-@file{ChangeLog} in the same directory as the file you are editing, or
-one of its parent directories. A single @file{ChangeLog} file can
-record changes for all the files in its directory and all its
-subdirectories.
-
- A change log entry starts with a header line that contains your name,
-your email address (taken from the variable @code{user-mail-address}),
-and the current date and time. Aside from these header lines, every
-line in the change log starts with a space or a tab. The bulk of the
-entry consists of @dfn{items}, each of which starts with a line starting
-with whitespace and a star. Here are two entries, both dated in May
-1993, each with two items:
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-1993-05-25 Richard Stallman <rms@@gnu.org>
-
- * man.el: Rename symbols `man-*' to `Man-*'.
- (manual-entry): Make prompt string clearer.
-
- * simple.el (blink-matching-paren-distance):
- Change default to 12,000.
-
-1993-05-24 Richard Stallman <rms@@gnu.org>
-
- * vc.el (minor-mode-map-alist): Don't use it if it's void.
- (vc-cancel-version): Doc fix.
-@end smallexample
-
-@noindent
-(Previous Emacs versions used a different format for the date. You can
-convert old-style entries to the current format with
-@findex change-log-redate
-@kbd{M-x change-log-redate}.)
-
- One entry can describe several changes; each change should have its
-own item. Normally there should be a blank line between items. When
-items are related (parts of the same change, in different places), group
-them by leaving no blank line between them. The second entry above
-contains two items grouped in this way.
-
-@vindex add-log-keep-changes-together
- @kbd{C-x 4 a} visits the change log file and creates a new entry
-unless the most recent entry is for today's date and your name. It also
-creates a new item for the current file. For many languages, it can
-even guess the name of the function or other object that was changed.
-When the option @code{add-log-keep-changes-together} is set, @kbd{C-x 4
-a} adds to any existing entry for the file rather than starting a new
-entry.
-
-@cindex Change Log mode
-@findex change-log-mode
- The change log file is visited in Change Log mode. In this major
-mode, each bunch of grouped items counts as one paragraph, and each
-entry is considered a page. This facilitates editing the entries.
-@kbd{C-j} and auto-fill indent each new line like the previous line;
-this is convenient for entering the contents of an entry.
-
-@findex change-log-merge
-The command @kbd{M-x change-log-merge} can be used to merge other log
-files into a buffer in Change Log Mode, preserving the date ordering
-of entries with either the current or old-style date formats.
-
- Version control systems are another way to keep track of changes in your
-program and keep a change log. @xref{Log Buffer}.
-
-@node Authors
-@section @file{AUTHORS} files
-@cindex @file{AUTHORS} file
-
- Programs which have many contributors usually include a file named
-@file{AUTHORS} in their distribution, which lists the individual
-contributions. Emacs has a special command for maintaining the
-@file{AUTHORS} file that is part of the Emacs distribution.
-
-@findex authors
- The @kbd{M-x authors} command prompts for the name of the root of the
-Emacs source directory. It then scans @file{ChageLog} files and Lisp
-source files under that directory for information about authors of
-individual packages and people who made changes in source files, and
-puts the information it gleans into a buffer named @samp{*Authors*}.
-You can then edit the contents of that buffer and merge it with the
-exisiting @file{AUTHORS} file.
-
-@node Tags
-@section Tags Tables
-@cindex tags table
-
- A @dfn{tags table} is a description of how a multi-file program is
-broken up into files. It lists the names of the component files and the
-names and positions of the functions (or other named subunits) in each
-file. Grouping the related files makes it possible to search or replace
-through all the files with one command. Recording the function names
-and positions makes possible the @kbd{M-.} command which finds the
-definition of a function by looking up which of the files it is in.
-
- Tags tables are stored in files called @dfn{tags table files}. The
-conventional name for a tags table file is @file{TAGS}.
-
- Each entry in the tags table records the name of one tag, the name of the
-file that the tag is defined in (implicitly), and the position in that file
-of the tag's definition.
-
- Just what names from the described files are recorded in the tags table
-depends on the programming language of the described file. They
-normally include all functions and subroutines, and may also include
-global variables, data types, and anything else convenient. Each name
-recorded is called a @dfn{tag}.
-
-@cindex C++ class browser, tags
-@cindex tags, C++
-@cindex class browser, C++
-@cindex Ebrowse
-The Ebrowse is a separate facility tailored for C++, with tags and a
-class browser. @xref{,,, ebrowse, Ebrowse User's Manual}.
-
-@menu
-* Tag Syntax:: Tag syntax for various types of code and text files.
-* Create Tags Table:: Creating a tags table with @code{etags}.
-* Etags Regexps:: Create arbitrary tags using regular expressions.
-* Select Tags Table:: How to visit a tags table.
-* Find Tag:: Commands to find the definition of a specific tag.
-* Tags Search:: Using a tags table for searching and replacing.
-* List Tags:: Listing and finding tags defined in a file.
-@end menu
-
-@node Tag Syntax
-@subsection Source File Tag Syntax
-
- Here is how tag syntax is defined for the most popular languages:
-
-@itemize @bullet
-@item
-In C code, any C function or typedef is a tag, and so are definitions of
-@code{struct}, @code{union} and @code{enum}. You can tag function
-declarations and external variables in addition to function definitions
-by giving the @samp{--declarations} option to @code{etags}.
-@code{#define} macro definitions and @code{enum} constants are also
-tags, unless you specify @samp{--no-defines} when making the tags table.
-Similarly, global variables are tags, unless you specify
-@samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
-can make the tags table file much smaller.
-
-@item
-In C++ code, in addition to all the tag constructs of C code, member
-functions are also recognized, and optionally member variables if you
-use the @samp{--members} option. Tags for variables and functions in
-classes are named @samp{@var{class}::@var{variable}} and
-@samp{@var{class}::@var{function}}. @code{operator} functions tags are
-named, for example @samp{operator+}.
-
-@item
-In Java code, tags include all the constructs recognized in C++, plus
-the @code{interface}, @code{extends} and @code{implements} constructs.
-Tags for variables and functions in classes are named
-@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
-
-@item
-In La@TeX{} text, the argument of any of the commands @code{\chapter},
-@code{\section}, @code{\subsection}, @code{\subsubsection},
-@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
-@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
-tag.@refill
-
-Other commands can make tags as well, if you specify them in the
-environment variable @env{TEXTAGS} before invoking @code{etags}. The
-value of this environment variable should be a colon-separated list of
-command names. For example,
-
-@example
-TEXTAGS="def:newcommand:newenvironment"
-export TEXTAGS
-@end example
-
-@noindent
-specifies (using Bourne shell syntax) that the commands @samp{\def},
-@samp{\newcommand} and @samp{\newenvironment} also define tags.
-
-@item
-In Lisp code, any function defined with @code{defun}, any variable
-defined with @code{defvar} or @code{defconst}, and in general the first
-argument of any expression that starts with @samp{(def} in column zero, is
-a tag.
-
-@item
-In Scheme code, tags include anything defined with @code{def} or with a
-construct whose name starts with @samp{def}. They also include variables
-set with @code{set!} at top level in the file.
-@end itemize
-
- Several other languages are also supported:
-
-@itemize @bullet
-
-@item
-In Ada code, functions, procedures, packages, tasks, and types are
-tags. Use the @samp{--packages-only} option to create tags for packages
-only.
-
-@item
-In assembler code, labels appearing at the beginning of a line,
-followed by a colon, are tags.
-
-@item
-In Bison or Yacc input files, each rule defines as a tag the nonterminal
-it constructs. The portions of the file that contain C code are parsed
-as C code.
-
-@item
-In Cobol code, tags are paragraph names; that is, any word starting in
-column 8 and followed by a period.
-
-@item
-In Erlang code, the tags are the functions, records, and macros defined
-in the file.
-
-@item
-In Fortran code, functions, subroutines and blockdata are tags.
-
-@item
-In Objective C code, tags include Objective C definitions for classes,
-class categories, methods, and protocols.
-
-@item
-In Pascal code, the tags are the functions and procedures defined in
-the file.
-
-@item
-In Perl code, the tags are the procedures defined by the @code{sub},
-@code{my} and @code{local} keywords. Use @samp{--globals} if you want
-to tag global variables.
-
-@item
-In PostScript code, the tags are the functions.
-
-@item
-In Prolog code, a tag name appears at the left margin.
-
-@item
-In Python code, @code{def} or @code{class} at the beginning of a line
-generate a tag.
-@end itemize
-
- You can also generate tags based on regexp matching (@pxref{Etags
-Regexps}) to handle other formats and languages.
-
-@node Create Tags Table
-@subsection Creating Tags Tables
-@cindex @code{etags} program
-
- The @code{etags} program is used to create a tags table file. It knows
-the syntax of several languages, as described in
-@iftex
-the previous section.
-@end iftex
-@ifinfo
-@ref{Tag Syntax}.
-@end ifinfo
-Here is how to run @code{etags}:
-
-@example
-etags @var{inputfiles}@dots{}
-@end example
-
-@noindent
-The @code{etags} program reads the specified files, and writes a tags
-table named @file{TAGS} in the current working directory. You can
-intermix compressed and plain text source file names. @code{etags}
-knows about the most common compression formats, and does the right
-thing. So you can compress all your source files and have @code{etags}
-look for compressed versions of its file name arguments, if it does not
-find uncompressed versions. Under MS-DOS, @code{etags} also looks for
-file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the
-command line and @samp{mycode.c} does not exist.
-
- @code{etags} recognizes the language used in an input file based on
-its file name and contents. You can specify the language with the
-@samp{--language=@var{name}} option, described below.
-
- If the tags table data become outdated due to changes in the files
-described in the table, the way to update the tags table is the same way it
-was made in the first place. It is not necessary to do this often.
-
- If the tags table fails to record a tag, or records it for the wrong
-file, then Emacs cannot possibly find its definition. However, if the
-position recorded in the tags table becomes a little bit wrong (due to
-some editing in the file that the tag definition is in), the only
-consequence is a slight delay in finding the tag. Even if the stored
-position is very wrong, Emacs will still find the tag, but it must
-search the entire file for it.
-
- So you should update a tags table when you define new tags that you want
-to have listed, or when you move tag definitions from one file to another,
-or when changes become substantial. Normally there is no need to update
-the tags table after each edit, or even every day.
-
- One tags table can effectively include another. Specify the included
-tags file name with the @samp{--include=@var{file}} option when creating
-the file that is to include it. The latter file then acts as if it
-contained all the files specified in the included file, as well as the
-files it directly contains.
-
- If you specify the source files with relative file names when you run
-@code{etags}, the tags file will contain file names relative to the
-directory where the tags file was initially written. This way, you can
-move an entire directory tree containing both the tags file and the
-source files, and the tags file will still refer correctly to the source
-files.
-
- If you specify absolute file names as arguments to @code{etags}, then
-the tags file will contain absolute file names. This way, the tags file
-will still refer to the same files even if you move it, as long as the
-source files remain in the same place. Absolute file names start with
-@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
-
- When you want to make a tags table from a great number of files, you
-may have problems listing them on the command line, because some systems
-have a limit on its length. The simplest way to circumvent this limit
-is to tell @code{etags} to read the file names from its standard input,
-by typing a dash in place of the file names, like this:
-
-@smallexample
-find . -name "*.[chCH]" -print | etags -
-@end smallexample
-
- Use the option @samp{--language=@var{name}} to specify the language
-explicitly. You can intermix these options with file names; each one
-applies to the file names that follow it. Specify
-@samp{--language=auto} to tell @code{etags} to resume guessing the
-language from the file names and file contents. Specify
-@samp{--language=none} to turn off language-specific processing
-entirely; then @code{etags} recognizes tags by regexp matching alone
-(@pxref{Etags Regexps}).
-
- @samp{etags --help} prints the list of the languages @code{etags}
-knows, and the file name rules for guessing the language. It also prints
-a list of all the available @code{etags} options, together with a short
-explanation.
-
-@node Etags Regexps
-@subsection Etags Regexps
-
- The @samp{--regex} option provides a general way of recognizing tags
-based on regexp matching. You can freely intermix it with file names.
-Each @samp{--regex} option adds to the preceding ones, and applies only
-to the following files. The syntax is:
-
-@smallexample
---regex=/@var{tagregexp}[/@var{nameregexp}]/
-@end smallexample
-
-@noindent
-where @var{tagregexp} is used to match the lines to tag. It is always
-anchored, that is, it behaves as if preceded by @samp{^}. If you want
-to account for indentation, just match any initial number of blanks by
-beginning your regular expression with @samp{[ \t]*}. In the regular
-expressions, @samp{\} quotes the next character, and @samp{\t} stands
-for the tab character. Note that @code{etags} does not handle the other
-C escape sequences for special characters.
-
-@cindex interval operator (in regexps)
- The syntax of regular expressions in @code{etags} is the same as in
-Emacs, augmented with the @dfn{interval operator}, which works as in
-@code{grep} and @code{ed}. The syntax of an interval operator is
-@samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
-expression at least @var{m} times and up to @var{n} times.
-
- You should not match more characters with @var{tagregexp} than that
-needed to recognize what you want to tag. If the match is such that
-more characters than needed are unavoidably matched by @var{tagregexp}
-(as will usually be the case), you should add a @var{nameregexp}, to
-pick out just the tag. This will enable Emacs to find tags more
-accurately and to do completion on tag names more reliably. You can
-find some examples below.
-
- The option @samp{--ignore-case-regex} (or @samp{-c}) is like
-@samp{--regex}, except that the regular expression provided will be
-matched without regard to case, which is appropriate for various
-programming languages.
-
- The @samp{-R} option deletes all the regexps defined with
-@samp{--regex} options. It applies to the file names following it, as
-you can see from the following example:
-
-@smallexample
-etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
- bar.ber -R --lang=lisp los.er
-@end smallexample
-
-@noindent
-Here @code{etags} chooses the parsing language for @file{voo.doo} and
-@file{bar.ber} according to their contents. @code{etags} also uses
-@var{reg1} to recognize additional tags in @file{voo.doo}, and both
-@var{reg1} and @var{reg2} to recognize additional tags in
-@file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
-matching, to recognize tags in @file{los.er}.
-
- A regular expression can be bound to a given language, by prepending
-it with @samp{@{lang@}}. When you do this, @code{etags} will use the
-regular expression only for files of that language. @samp{etags --help}
-prints the list of languages recognised by @code{etags}. The following
-example tags the @code{DEFVAR} macros in the Emacs source files.
-@code{etags} applies this regular expression to C files only:
-
-@smallexample
---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
-@end smallexample
-
-@noindent
-This feature is particularly useful when storing a list of regular
-expressions in a file. The following option syntax instructs
-@code{etags} to read two files of regular expressions. The regular
-expressions contained in the second file are matched without regard to
-case.
-
-@smallexample
---regex=@@first-file --ignore-case-regex=@@second-file
-@end smallexample
-
-@noindent
-A regex file contains one regular expressions per line. Empty lines,
-and lines beginning with space or tab are ignored. When the first
-character in a line is @samp{@@}, @code{etags} assumes that the rest of
-the line is the name of a file of regular expressions. This means that
-such files can be nested. All the other lines are taken to be regular
-expressions. For example, one can create a file called
-@samp{emacs.tags} with the following contents (the first line in the
-file is a comment):
-
-@smallexample
- -- This is for GNU Emacs source files
-@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
-@end smallexample
-
-@noindent
-and then use it like this:
-
-@smallexample
-etags --regex=@@emacs.tags *.[ch] */*.[ch]
-@end smallexample
-
- Here are some more examples. The regexps are quoted to protect them
-from shell interpretation.
-
-@itemize @bullet
-
-@item
-Tag Octave files:
-
-@smallexample
-etags --language=none \
- --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
- --regex='/###key \(.*\)/\1/' \
- --regex='/[ \t]*global[ \t].*/' \
- *.m
-@end smallexample
-
-@noindent
-Note that tags are not generated for scripts so that you have to add a
-line by yourself of the form `###key <script-name>' if you want to jump
-to it.
-
-@item
-Tag Tcl files:
-
-@smallexample
-etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
-@end smallexample
-
-@item
-Tag VHDL files:
-
-@smallexample
---language=none \
---regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
---regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
-\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
-@end smallexample
-@end itemize
-
-@node Select Tags Table
-@subsection Selecting a Tags Table
-
-@vindex tags-file-name
-@findex visit-tags-table
- Emacs has at any time one @dfn{selected} tags table, and all the commands
-for working with tags tables use the selected one. To select a tags table,
-type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
-argument. The name @file{TAGS} in the default directory is used as the
-default file name.
-
- All this command does is store the file name in the variable
-@code{tags-file-name}. Emacs does not actually read in the tags table
-contents until you try to use them. Setting this variable yourself is just
-as good as using @code{visit-tags-table}. The variable's initial value is
-@code{nil}; that value tells all the commands for working with tags tables
-that they must ask for a tags table file name to use.
-
- Using @code{visit-tags-table} when a tags table is already loaded
-gives you a choice: you can add the new tags table to the current list
-of tags tables, or start a new list. The tags commands use all the tags
-tables in the current list. If you start a new list, the new tags table
-is used @emph{instead} of others. If you add the new table to the
-current list, it is used @emph{as well as} the others. When the tags
-commands scan the list of tags tables, they don't always start at the
-beginning of the list; they start with the first tags table (if any)
-that describes the current file, proceed from there to the end of the
-list, and then scan from the beginning of the list until they have
-covered all the tables in the list.
-
-@vindex tags-table-list
- You can specify a precise list of tags tables by setting the variable
-@code{tags-table-list} to a list of strings, like this:
-
-@c keep this on two lines for formatting in smallbook
-@example
-@group
-(setq tags-table-list
- '("~/emacs" "/usr/local/lib/emacs/src"))
-@end group
-@end example
-
-@noindent
-This tells the tags commands to look at the @file{TAGS} files in your
-@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
-directory. The order depends on which file you are in and which tags
-table mentions that file, as explained above.
-
- Do not set both @code{tags-file-name} and @code{tags-table-list}.
-
-@node Find Tag
-@subsection Finding a Tag
-
- The most important thing that a tags table enables you to do is to find
-the definition of a specific tag.
-
-@table @kbd
-@item M-.@: @var{tag} @key{RET}
-Find first definition of @var{tag} (@code{find-tag}).
-@item C-u M-.
-Find next alternate definition of last tag specified.
-@item C-u - M-.
-Go back to previous tag found.
-@item C-M-. @var{pattern} @key{RET}
-Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
-@item C-u C-M-.
-Find the next tag whose name matches the last pattern used.
-@item C-x 4 .@: @var{tag} @key{RET}
-Find first definition of @var{tag}, but display it in another window
-(@code{find-tag-other-window}).
-@item C-x 5 .@: @var{tag} @key{RET}
-Find first definition of @var{tag}, and create a new frame to select the
-buffer (@code{find-tag-other-frame}).
-@item M-*
-Pop back to where you previously invoked @kbd{M-.} and friends.
-@end table
-
-@kindex M-.
-@findex find-tag
- @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
-a specified tag. It searches through the tags table for that tag, as a
-string, and then uses the tags table info to determine the file that the
-definition is in and the approximate character position in the file of
-the definition. Then @code{find-tag} visits that file, moves point to
-the approximate character position, and searches ever-increasing
-distances away to find the tag definition.
-
- If an empty argument is given (just type @key{RET}), the sexp in the
-buffer before or around point is used as the @var{tag} argument.
-@xref{Lists}, for info on sexps.
-
- You don't need to give @kbd{M-.} the full name of the tag; a part
-will do. This is because @kbd{M-.} finds tags in the table which
-contain @var{tag} as a substring. However, it prefers an exact match
-to a substring match. To find other tags that match the same
-substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
-M-.}; this does not read a tag name, but continues searching the tags
-table's text for another tag containing the same substring last used.
-If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
-alternative to @kbd{C-u M-.}.
-
-@kindex C-x 4 .
-@findex find-tag-other-window
-@kindex C-x 5 .
-@findex find-tag-other-frame
- Like most commands that can switch buffers, @code{find-tag} has a
-variant that displays the new buffer in another window, and one that
-makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
-the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
-which invokes @code{find-tag-other-frame}.
-
- To move back to places you've found tags recently, use @kbd{C-u -
-M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
-command can take you to another buffer. @kbd{C-x 4 .} with a negative
-argument finds the previous tag location in another window.
-
-@kindex M-*
-@findex pop-tag-mark
-@vindex find-tag-marker-ring-length
- As well as going back to places you've found tags recently, you can go
-back to places @emph{from where} you found them. Use @kbd{M-*}, which
-invokes the command @code{pop-tag-mark}, for this. Typically you would
-find and study the definition of something with @kbd{M-.} and then
-return to where you were with @kbd{M-*}.
-
- Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
-a depth determined by the variable @code{find-tag-marker-ring-length}.
-
-@findex find-tag-regexp
-@kindex C-M-.
- The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
-match a specified regular expression. It is just like @kbd{M-.} except
-that it does regexp matching instead of substring matching.
-
-@node Tags Search
-@subsection Searching and Replacing with Tags Tables
-
- The commands in this section visit and search all the files listed in the
-selected tags table, one by one. For these commands, the tags table serves
-only to specify a sequence of files to search.
-
-@table @kbd
-@item M-x tags-search @key{RET} @var{regexp} @key{RET}
-Search for @var{regexp} through the files in the selected tags
-table.
-@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
-Perform a @code{query-replace-regexp} on each file in the selected tags table.
-@item M-,
-Restart one of the commands above, from the current location of point
-(@code{tags-loop-continue}).
-@end table
-
-@findex tags-search
- @kbd{M-x tags-search} reads a regexp using the minibuffer, then
-searches for matches in all the files in the selected tags table, one
-file at a time. It displays the name of the file being searched so you
-can follow its progress. As soon as it finds an occurrence,
-@code{tags-search} returns.
-
-@kindex M-,
-@findex tags-loop-continue
- Having found one match, you probably want to find all the rest. To find
-one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
-@code{tags-search}. This searches the rest of the current buffer, followed
-by the remaining files of the tags table.@refill
-
-@findex tags-query-replace
- @kbd{M-x tags-query-replace} performs a single
-@code{query-replace-regexp} through all the files in the tags table. It
-reads a regexp to search for and a string to replace with, just like
-ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
-tags-search}, but repeatedly, processing matches according to your
-input. @xref{Replace}, for more information on query replace.
-
- It is possible to get through all the files in the tags table with a
-single invocation of @kbd{M-x tags-query-replace}. But often it is
-useful to exit temporarily, which you can do with any input event that
-has no special query replace meaning. You can resume the query replace
-subsequently by typing @kbd{M-,}; this command resumes the last tags
-search or replace command that you did.
-
- The commands in this section carry out much broader searches than the
-@code{find-tag} family. The @code{find-tag} commands search only for
-definitions of tags that match your substring or regexp. The commands
-@code{tags-search} and @code{tags-query-replace} find every occurrence
-of the regexp, as ordinary search commands and replace commands do in
-the current buffer.
-
- These commands create buffers only temporarily for the files that they
-have to search (those which are not already visited in Emacs buffers).
-Buffers in which no match is found are quickly killed; the others
-continue to exist.
-
- It may have struck you that @code{tags-search} is a lot like
-@code{grep}. You can also run @code{grep} itself as an inferior of
-Emacs and have Emacs show you the matching lines one by one. This works
-much like running a compilation; finding the source locations of the
-@code{grep} matches works like finding the compilation errors.
-@xref{Compilation}.
-
-@node List Tags
-@subsection Tags Table Inquiries
-
-@table @kbd
-@item M-x list-tags @key{RET} @var{file} @key{RET}
-Display a list of the tags defined in the program file @var{file}.
-@item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
-Display a list of all tags matching @var{regexp}.
-@end table
-
-@findex list-tags
- @kbd{M-x list-tags} reads the name of one of the files described by
-the selected tags table, and displays a list of all the tags defined in
-that file. The ``file name'' argument is really just a string to
-compare against the file names recorded in the tags table; it is read as
-a string rather than as a file name. Therefore, completion and
-defaulting are not available, and you must enter the file name the same
-way it appears in the tags table. Do not include a directory as part of
-the file name unless the file name recorded in the tags table includes a
-directory.
-
-@findex tags-apropos
- @kbd{M-x tags-apropos} is like @code{apropos} for tags
-(@pxref{Apropos}). It reads a regexp, then finds all the tags in the
-selected tags table whose entries match that regexp, and displays the
-tag names found.
-@vindex tags-apropos-additional-actions
-You can display additional output with @kbd{M-x tags-apropos} by customizing
-the variable @code{tags-apropos-additional-actions}. See its
-documentation for details.
-
- You can also perform completion in the buffer on the name space of tag
-names in the current tags tables. @xref{Symbol Completion}.
-
-@node Imenu
-@section Imenu
-@cindex indexes of buffer contents
-@cindex buffer content indexes
-@cindex tags
-
-The Imenu facility provides mode-specific indexes of the contents of
-single buffers and provides selection from a menu. Selecting a menu
-item takes you to the indexed point in the buffer, in a similar way to
-the Tags facility. Indexing is typically by names of program routines
-and variables but in Texinfo mode, for instance, node names are indexed.
-Most major modes for which it is appropriate have Imenu support.
+expression that is the value of the variable @code{comment-start-skip}.
+Make sure this regexp does not match the null string. It may match more
+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
+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
+in regexp syntax. @xref{Regexp Backslash}.)
-@findex imenu
-@findex imenu-add-menu-bar-index
-@kbd{M-x imenu} builds the index if necessary and presents you with an
-electric buffer menu from which to select an entry (with completion).
-If you bind @code{imenu} to a mouse event (@pxref{Mouse Buttons}) and
-invoke it that way, the index will appear as a popup menu; there is no
-such binding by default. You can add an index menubar on the menubar
-with @kbd{imenu-add-menu-bar-index}.
-
-Some major modes provide facilities for invoking Imenu; otherwise you
-could add @code{imenu-add-menu-bar-index} to a major mode's hook to
-generate an index for each buffer created in that mode. (If you do
-that, it takes sime time to generate the index when finding a file,
-depending on the file's size and the complexity of the indexing function
-for that mode.)
+@vindex comment-start
+@vindex comment-end
+ When a comment command makes a new comment, it inserts the value of
+@code{comment-start} to begin it. The value of @code{comment-end} is
+inserted after point, so that it will follow the text that you will
+insert into the comment. When @code{comment-end} is non-empty, it
+should start with a space. For example, in C mode,
+@code{comment-start} has the value @w{@code{"/* "}} and
+@code{comment-end} has the value @w{@code{" */"}}.
-@vindex imenu-auto-rescan
-The index should be regenerated (via the @samp{*Rescan*} menu item) when
-indexable items are added to or deleted from the buffer. Rescanning is
-done when a menu selction is requested if the option
-@code{imenu-auto-rescan} is set. By default buffer positions are in
-terms of markers, so that changing non-indexable text doesn't require
-rescanning.
+@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{nil} means 0. Alternatively, @code{comment-padding}
+can hold the actual string to insert.
-@vindex imenu-sort-function
-The way the menus are sorted can be customized via the option
-@code{imenu-sort-function}. By default names are ordered as they occur
-in the buffer; alphabetic sorting is provided as an alternative.
+@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.
-Imenu provides the information used by Which Function mode (@pxref{Which
-Function}). It may also be used by Speedbar (@pxref{Speedbar}).
+@vindex comment-indent-function
+ The variable @code{comment-indent-function} should contain a function
+that will be called to compute the alignment for a newly inserted
+comment or for aligning an existing comment. It is set differently by
+various major modes. The function is called with no arguments, but with
+point at the beginning of the comment, or at the end of a line if a new
+comment is to be inserted. It should return the column in which the
+comment ought to start. For example, in Lisp mode, the indent hook
+function bases its decision on how many semicolons begin an existing
+comment, and on the code in the preceding lines.
-@node Emerge, C Modes, Imenu, Programs
-@section Merging Files with Emerge
-@cindex Emerge
-@cindex merging files
+@node Documentation
+@section Documentation Lookup
-It's not unusual for programmers to get their signals crossed and modify
-the same program in two different directions. To recover from this
-confusion, you need to merge the two versions. Emerge makes this
-easier. See also @ref{Comparing Files}, for commands to compare
-in a more manual fashion, and @ref{,Ediff,, ediff, The Ediff Manual}.
+ Emacs provides several features you can use to look up the
+documentation of functions, variables and commands that you plan to
+use in your program.
@menu
-* Overview of Emerge:: How to start Emerge. Basic concepts.
-* Submodes of Emerge:: Fast mode vs. Edit mode.
- Skip Prefers mode and Auto Advance mode.
-* State of Difference:: You do the merge by specifying state A or B
- for each difference.
-* Merge Commands:: Commands for selecting a difference,
- changing states of differences, etc.
-* Exiting Emerge:: What to do when you've finished the merge.
-* Combining in Emerge:: How to keep both alternatives for a difference.
-* Fine Points of Emerge:: Misc.
+* Info Lookup:: Looking up library functions and commands
+ in Info files.
+* Man Page:: Looking up man pages of library functions and commands.
+* Lisp Doc:: Looking up Emacs Lisp functions, etc.
@end menu
-@node Overview of Emerge
-@subsection Overview of Emerge
-
-To start Emerge, run one of these four commands:
-
-@table @kbd
-@item M-x emerge-files
-@findex emerge-files
-Merge two specified files.
-
-@item M-x emerge-files-with-ancestor
-@findex emerge-files-with-ancestor
-Merge two specified files, with reference to a common ancestor.
-
-@item M-x emerge-buffers
-@findex emerge-buffers
-Merge two buffers.
-
-@item M-x emerge-buffers-with-ancestor
-@findex emerge-buffers-with-ancestor
-Merge two buffers with reference to a common ancestor in a third
-buffer.
-@end table
-
-@cindex merge buffer (Emerge)
-@cindex A and B buffers (Emerge)
- The Emerge commands compare two files or buffers, and display the
-comparison in three buffers: one for each input text (the @dfn{A buffer}
-and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
-takes place. The merge buffer shows the full merged text, not just the
-differences. Wherever the two input texts differ, you can choose which
-one of them to include in the merge buffer.
-
- The Emerge commands that take input from existing buffers use only the
-accessible portions of those buffers, if they are narrowed
-(@pxref{Narrowing}).
-
- If a common ancestor version is available, from which the two texts to
-be merged were both derived, Emerge can use it to guess which
-alternative is right. Wherever one current version agrees with the
-ancestor, Emerge presumes that the other current version is a deliberate
-change which should be kept in the merged version. Use the
-@samp{with-ancestor} commands if you want to specify a common ancestor
-text. These commands read three file or buffer names---variant A,
-variant B, and the common ancestor.
-
- After the comparison is done and the buffers are prepared, the
-interactive merging starts. You control the merging by typing special
-@dfn{merge commands} in the merge buffer. The merge buffer shows you a
-full merged text, not just differences. For each run of differences
-between the input texts, you can choose which one of them to keep, or
-edit them both together.
-
- The merge buffer uses a special major mode, Emerge mode, with commands
-for making these choices. But you can also edit the buffer with
-ordinary Emacs commands.
-
- At any given time, the attention of Emerge is focused on one
-particular difference, called the @dfn{selected} difference. This
-difference is marked off in the three buffers like this:
-
-@example
-vvvvvvvvvvvvvvvvvvvv
-@var{text that differs}
-^^^^^^^^^^^^^^^^^^^^
-@end example
-
-@noindent
-Emerge numbers all the differences sequentially and the mode
-line always shows the number of the selected difference.
-
- Normally, the merge buffer starts out with the A version of the text.
-But when the A version of a difference agrees with the common ancestor,
-then the B version is initially preferred for that difference.
-
- Emerge leaves the merged text in the merge buffer when you exit. At
-that point, you can save it in a file with @kbd{C-x C-w}. If you give a
-numeric argument to @code{emerge-files} or
-@code{emerge-files-with-ancestor}, it reads the name of the output file
-using the minibuffer. (This is the last file name those commands read.)
-Then exiting from Emerge saves the merged text in the output file.
-
- Normally, Emerge commands save the output buffer in its file when you
-exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
-save the output buffer, but you can save it yourself if you wish.
-
-@node Submodes of Emerge
-@subsection Submodes of Emerge
-
- You can choose between two modes for giving merge commands: Fast mode
-and Edit mode. In Fast mode, basic merge commands are single
-characters, but ordinary Emacs commands are disabled. This is
-convenient if you use only merge commands. In Edit mode, all merge
-commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
-commands are also available. This allows editing the merge buffer, but
-slows down Emerge operations.
-
- Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
-Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
-and @samp{F}.
-
- Emerge has two additional submodes that affect how particular merge
-commands work: Auto Advance mode and Skip Prefers mode.
-
- If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
-advance to the next difference. This lets you go through the merge
-faster as long as you simply choose one of the alternatives from the
-input. The mode line indicates Auto Advance mode with @samp{A}.
-
- If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
-skip over differences in states prefer-A and prefer-B (@pxref{State of
-Difference}). Thus you see only differences for which neither version
-is presumed ``correct.'' The mode line indicates Skip Prefers mode with
-@samp{S}.
-
-@findex emerge-auto-advance-mode
-@findex emerge-skip-prefers-mode
- Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
-clear Auto Advance mode. Use @kbd{s s}
-(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
-These commands turn on the mode with a positive argument, turns it off
-with a negative or zero argument, and toggle the mode with no argument.
-
-@node State of Difference
-@subsection State of a Difference
-
- In the merge buffer, a difference is marked with lines of @samp{v} and
-@samp{^} characters. Each difference has one of these seven states:
-
-@table @asis
-@item A
-The difference is showing the A version. The @kbd{a} command always
-produces this state; the mode line indicates it with @samp{A}.
-
-@item B
-The difference is showing the B version. The @kbd{b} command always
-produces this state; the mode line indicates it with @samp{B}.
-
-@item default-A
-@itemx default-B
-The difference is showing the A or the B state by default, because you
-haven't made a choice. All differences start in the default-A state
-(and thus the merge buffer is a copy of the A buffer), except those for
-which one alternative is ``preferred'' (see below).
-
-When you select a difference, its state changes from default-A or
-default-B to plain A or B. Thus, the selected difference never has
-state default-A or default-B, and these states are never displayed in
-the mode line.
-
-The command @kbd{d a} chooses default-A as the default state, and @kbd{d
-b} chooses default-B. This chosen default applies to all differences
-which you haven't ever selected and for which no alternative is preferred.
-If you are moving through the merge sequentially, the differences you
-haven't selected are those following the selected one. Thus, while
-moving sequentially, you can effectively make the A version the default
-for some sections of the merge buffer and the B version the default for
-others by using @kbd{d a} and @kbd{d b} between sections.
-
-@item prefer-A
-@itemx prefer-B
-The difference is showing the A or B state because it is
-@dfn{preferred}. This means that you haven't made an explicit choice,
-but one alternative seems likely to be right because the other
-alternative agrees with the common ancestor. Thus, where the A buffer
-agrees with the common ancestor, the B version is preferred, because
-chances are it is the one that was actually changed.
-
-These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
-
-@item combined
-The difference is showing a combination of the A and B states, as a
-result of the @kbd{x c} or @kbd{x C} commands.
-
-Once a difference is in this state, the @kbd{a} and @kbd{b} commands
-don't do anything to it unless you give them a numeric argument.
-
-The mode line displays this state as @samp{comb}.
-@end table
-
-@node Merge Commands
-@subsection Merge Commands
-
- Here are the Merge commands for Fast mode; in Edit mode, precede them
-with @kbd{C-c C-c}:
-
-@table @kbd
-@item p
-Select the previous difference.
-
-@item n
-Select the next difference.
+@node Info Lookup
+@subsection Info Documentation Lookup
-@item a
-Choose the A version of this difference.
-
-@item b
-Choose the B version of this difference.
-
-@item C-u @var{n} j
-Select difference number @var{n}.
-
-@item .
-Select the difference containing point. You can use this command in the
-merge buffer or in the A or B buffer.
-
-@item q
-Quit---finish the merge.
-
-@item C-]
-Abort---exit merging and do not save the output.
-
-@item f
-Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
-
-@item e
-Go into Edit mode.
-
-@item l
-Recenter (like @kbd{C-l}) all three windows.
-
-@item -
-Specify part of a prefix numeric argument.
-
-@item @var{digit}
-Also specify part of a prefix numeric argument.
-
-@item d a
-Choose the A version as the default from here down in
-the merge buffer.
-
-@item d b
-Choose the B version as the default from here down in
-the merge buffer.
-
-@item c a
-Copy the A version of this difference into the kill ring.
+@findex info-lookup-symbol
+@findex info-lookup-file
+@kindex C-h S
+ 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.
+
+ 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 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.
-@item c b
-Copy the B version of this difference into the kill ring.
+@findex manual-entry
+ 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.
-@item i a
-Insert the A version of this difference at point.
+@cindex sections of manual pages
+ 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 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} 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@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.
-@item i b
-Insert the B version of this difference at point.
+@vindex Man-fontify-manpage-flag
+ 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}.
-@item m
-Put point and mark around the difference.
+@findex Man-fontify-manpage
+ If you insert the text of a man page into an Emacs buffer in some
+other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
+perform the same conversions that @kbd{M-x manual-entry} does.
-@item ^
-Scroll all three windows down (like @kbd{M-v}).
+@findex woman
+@cindex manual pages, on MS-DOS/MS-Windows
+ An alternative way of reading manual pages is the @kbd{M-x woman}
+command@footnote{The name of the command, @code{woman}, is an acronym
+for ``w/o (without) man,'' since it doesn't use the @code{man}
+program.}. Unlike @kbd{M-x man}, it does not run any external
+programs to format and display the man pages; instead it does the job
+in Emacs Lisp, so it works on systems such as MS-Windows, where the
+@code{man} program (and other programs it uses) are not generally
+available.
+
+ @kbd{M-x woman} prompts for a name of a manual page, and provides
+completion based on the list of manual pages that are installed on
+your machine; the list of available manual pages is computed
+automatically the first time you invoke @code{woman}. The word at
+point in the current buffer is used to suggest the default for the
+name the manual page.
-@item v
-Scroll all three windows up (like @kbd{C-v}).
+ With a numeric argument, @kbd{M-x woman} recomputes the list of the
+manual pages used for completion. This is useful if you add or delete
+manual pages.
-@item <
-Scroll all three windows left (like @kbd{C-x <}).
+ If you type a name of a manual page and @kbd{M-x woman} finds that
+several manual pages by the same name exist in different sections, it
+pops up a window with possible candidates asking you to choose one of
+them.
-@item >
-Scroll all three windows right (like @kbd{C-x >}).
+ 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}.
-@item |
-Reset horizontal scroll on all three windows.
+@node Lisp Doc
+@subsection Emacs Lisp Documentation Lookup
-@item x 1
-Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
-to full size.)
+ As you edit Lisp code to be run in Emacs, you can use the commands
+@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v}
+(@code{describe-variable}) to view documentation of functions and
+variables that you want to use. These commands use the minibuffer to
+read the name of a function or variable to document, and display the
+documentation in a window. Their default arguments are based on the
+code in the neighborhood of point. For @kbd{C-h f}, the default is
+the function called in the innermost list containing point. @kbd{C-h
+v} uses the symbol name around or adjacent to point as its default.
-@item x c
-Combine the two versions of this difference (@pxref{Combining in
-Emerge}).
+@cindex Eldoc mode
+@findex eldoc-mode
+ A more automatic but less powerful method is Eldoc mode. This minor
+mode constantly displays in the echo area the argument list for the
+function being called at point. (In other words, it finds the
+function call that point is contained in, and displays the argument
+list of that function.) If point is over a documented variable, it
+shows the first line of the variable's docstring. Eldoc mode applies
+in Emacs Lisp and Lisp Interaction modes, and perhaps a few others
+that provide special support for looking up doc strings. Use the
+command @kbd{M-x eldoc-mode} to enable or disable this feature.
-@item x f
-Show the names of the files/buffers Emerge is operating on, in a Help
-window. (Use @kbd{C-u l} to restore windows.)
+@node Hideshow
+@section Hideshow minor mode
-@item x j
-Join this difference with the following one.
-(@kbd{C-u x j} joins this difference with the previous one.)
+@findex hs-minor-mode
+ Hideshow minor mode provides selective display of portions of a
+program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode}
+to enable or disable this mode, or add @code{hs-minor-mode} to the
+mode hook for certain major modes in order to enable it automatically
+for those modes.
-@item x s
-Split this difference into two differences. Before you use this
-command, position point in each of the three buffers at the place where
-you want to split the difference.
+ Just what constitutes a block depends on the major mode. In C mode
+or C++ mode, they are delimited by braces, while in Lisp mode and
+similar modes they are delimited by parentheses. Multi-line comments
+also count as blocks.
-@item x t
-Trim identical lines off the top and bottom of the difference.
-Such lines occur when the A and B versions are
-identical but differ from the ancestor version.
+@findex hs-hide-all
+@findex hs-hide-block
+@findex hs-show-all
+@findex hs-show-block
+@findex hs-show-region
+@findex hs-hide-level
+@findex hs-minor-mode
+@kindex C-c @@ C-h
+@kindex C-c @@ C-s
+@kindex C-c @@ C-M-h
+@kindex C-c @@ C-M-s
+@kindex C-c @@ C-r
+@kindex C-c @@ C-l
+@kindex S-Mouse-2
+@table @kbd
+@item C-c @@ C-h
+Hide the current block (@code{hs-hide-block}).
+@item C-c @@ C-s
+Show the current block (@code{hs-show-block}).
+@item C-c @@ C-c
+Either hide or show the current block (@code{hs-toggle-hiding}).
+@item S-Mouse-2
+Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}).
+@item C-c @@ C-M-h
+Hide all top-level blocks (@code{hs-hide-all}).
+@item C-c @@ C-M-s
+Show everything in the buffer (@code{hs-show-all}).
+@item C-c @@ C-l
+Hide all blocks @var{n} levels below this block
+(@code{hs-hide-level}).
@end table
-@node Exiting Emerge
-@subsection Exiting Emerge
+@vindex hs-hide-comments-when-hiding-all
+@vindex hs-isearch-open
+@vindex hs-special-modes-alist
+ These variables exist for customizing Hideshow mode.
- The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
-the results into the output file if you specified one. It restores the
-A and B buffers to their proper contents, or kills them if they were
-created by Emerge and you haven't changed them. It also disables the
-Emerge commands in the merge buffer, since executing them later could
-damage the contents of the various buffers.
+@table @code
+@item hs-hide-comments-when-hiding-all
+Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
- @kbd{C-]} aborts the merge. This means exiting without writing the
-output file. If you didn't specify an output file, then there is no
-real difference between aborting and finishing the merge.
+@item hs-isearch-open
+Specifies what kind of hidden blocks incremental search should make
+visible. The value should be one of these four symbols:
- If the Emerge command was called from another Lisp program, then its
-return value is @code{t} for successful completion, or @code{nil} if you
-abort.
+@table @code
+@item code
+Open only code blocks.
+@item comment
+Open only comments.
+@item t
+Open both code blocks and comments.
+@item nil
+Open neither code blocks nor comments.
+@end table
-@node Combining in Emerge
-@subsection Combining the Two Versions
+@item hs-special-modes-alist
+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
- Sometimes you want to keep @emph{both} alternatives for a particular
-difference. To do this, use @kbd{x c}, which edits the merge buffer
-like this:
+@node Symbol Completion
+@section Completion for Symbol Names
+@cindex completion (symbol names)
-@example
-@group
-#ifdef NEW
-@var{version from A buffer}
-#else /* not NEW */
-@var{version from B buffer}
-#endif /* not NEW */
-@end group
-@end example
+ 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.
-@noindent
-@vindex emerge-combine-versions-template
-While this example shows C preprocessor conditionals delimiting the two
-alternative versions, you can specify the strings to use by setting
-the variable @code{emerge-combine-versions-template} to a string of your
-choice. In the string, @samp{%a} says where to put version A, and
-@samp{%b} says where to put version B. The default setting, which
-produces the results shown above, looks like this:
+@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. This command inserts at point any additional characters that
+it can determine from the partial name. (If your window manager
+defines @kbd{M-@key{TAB}} to switch windows, you can type
+@kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.)
+
+ 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 complete-symbol
+ In most programming language major modes, @kbd{M-@key{TAB}} runs the
+command @code{complete-symbol}, which provides two kinds of completion.
+Normally it does completion based on a tags table (@pxref{Tags}); with a
+numeric argument (regardless of the value), it does completion based on
+the names listed in the Info file indexes for your language. Thus, to
+complete the name of a symbol defined in your own program, use
+@kbd{M-@key{TAB}} with no argument; to complete the name of a standard
+library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
+completion works only if there is an Info file for the standard library
+functions of your language, and only if it is installed at your site.
-@example
-@group
-"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
-@end group
-@end example
+@cindex Lisp symbol completion
+@cindex completion (Lisp symbols)
+@findex lisp-complete-symbol
+ In Emacs-Lisp mode, the name space for completion normally consists of
+nontrivial symbols present in Emacs---those that have function
+definitions, values or properties. However, if there is an
+open-parenthesis immediately before the beginning of the partial symbol,
+only symbols with function definitions are considered as completions.
+The command which implements this is @code{lisp-complete-symbol}.
-@node Fine Points of Emerge
-@subsection Fine Points of Emerge
+ In Text mode and related modes, @kbd{M-@key{TAB}} completes words
+based on the spell-checker's dictionary. @xref{Spelling}.
- During the merge, you mustn't try to edit the A and B buffers yourself.
-Emerge modifies them temporarily, but ultimately puts them back the way
-they were.
+@node Glasses
+@section Glasses minor mode
+@cindex Glasses mode
+@cindex identifiers, making long ones readable
+@cindex StudlyCaps, making them readable
+@findex glasses-mode
- You can have any number of merges going at once---just don't use any one
-buffer as input to more than one merge at once, since the temporary
-changes made in these buffers would get in each other's way.
+ Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
+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 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 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}).
+Judicious use of blank lines to make the program clearer will also
+provide useful chunks of text for the paragraph commands to work on.
+Auto Fill mode, if enabled in a programming language major mode,
+indents the new lines which it creates.
- Starting Emerge can take a long time because it needs to compare the
-files fully. Emacs can't do anything else until @code{diff} finishes.
-Perhaps in the future someone will change Emerge to do the comparison in
-the background when the input files are large---then you could keep on
-doing other things with Emacs until Emerge is ready to accept
-commands.
+ The selective display feature is useful for looking at the overall
+structure of a function (@pxref{Selective Display}). This feature
+hides the lines that are indented more than a specified amount.
+Programming modes often support Outline minor mode (@pxref{Outline
+Mode}). The Foldout package provides folding-editor features
+(@pxref{Foldout}).
-@vindex emerge-startup-hook
- After setting up the merge, Emerge runs the hook
-@code{emerge-startup-hook} (@pxref{Hooks}).
+ The ``automatic typing'' features may be useful for writing programs.
+@xref{Top,,Autotyping, autotype, Autotyping}.
@node C Modes
@section C and Related Modes
@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 describes special features available in C, C++,
-Objective-C, Java, CORBA IDL, and Pike modes. When we say ``C mode and
-related modes,'' those are the modes we mean.
-
-Additional information is available in the separate manual for these
-modes. @xref{Top, CC Mode, ccmode, , CC Mode}.
+ This section gives a brief description of the special features
+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::
-* Electric C::
-* Hungry Delete::
-* Other C Commands::
-* Comments in C::
+* 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}).
-
-@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
-@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.
+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}).
@end table
@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 may insert newlines. This feature is controlled by
-the variable @code{c-auto-newline}. 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}:
+@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{)}.
+
+ 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-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.
+@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
- 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 :}:
+ 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 :
-@kindex C-c : @r{(C mode)}
-@findex c-scope-operator
-Insert a double colon scope operator at point, without reindenting the
-line or adding any newlines (@code{c-scope-operator}).
+@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
- 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}.
-
- 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.
-
- 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.
-
- 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
-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 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
+@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}:
+ 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{DEL}
+@itemx C-c @key{DEL}
+@findex c-hungry-backspace
+@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
-@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.
+@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{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
-@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}).
+ 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{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
+@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
@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}. 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
+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
-@findex c-mark-function
-@kindex C-M-h @r{(C mode)}
Put mark at the end of a function definition, and put point at the
beginning (@code{c-mark-function}).
@findex c-show-syntactic-information
@kindex C-c C-s @r{(C mode)}
Display the syntactic information about the current source line
-(@code{c-show-syntactic-information}). This is the information that
-directs how the line is indented.
+(@code{c-show-syntactic-information}). This information directs how
+the line is indented.
@item M-x cwarn-mode
@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 suspicious C and C++ constructions:
+CWarn minor mode highlights certain suspicious C and C++ constructions:
@itemize @bullet{}
@item
-Assignments inside expressions, including variations like @samp{+=};
+Assignments inside expressions.
@item
Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
(except after a @samp{do @dots{} while} statement);
@end itemize
@noindent
-You can activate the mode either by customizing @code{global-cwarn-mode}
-or by adding @code{cwarn-mode} to @code{c-mode-common-hook}. It
-requires Font Lock mode to be active.
+You can enable the mode for one buffer with the command @kbd{M-x
+cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
+global-cwarn-mode} or by customizing the variable
+@code{global-cwarn-mode}. You must also enable Font Lock mode to make
+it work.
@item M-x hide-ifdef-mode
@findex hide-ifdef-mode
@cindex Hide-ifdef mode
Hide-ifdef minor mode hides selected code within @samp{#if} and
-@samp{#ifdef} preprocessor blocks. You can activate it by adding
-@code{hide-ifdef-mode} to @code{c-mode-common-hook}. See the mode's
-help for more information.
-@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.
+@samp{#ifdef} preprocessor blocks. See the documentation string of
+@code{hide-ifdef-mode} for more information.
+
+@item M-x ff-find-related-file
+@cindex related files
+@findex ff-find-related-file
+@vindex ff-related-file-alist
+Find a file ``related'' in a special way to the file visited by the
+current buffer. Typically this will be the header file corresponding
+to a C/C++ source file, or vice versa. The variable
+@code{ff-related-file-alist} specifies how to compute related file
+names.
@end table
-
-@node Fortran
-@section Fortran Mode
-@cindex Fortran mode
-@cindex mode, Fortran
-
- Fortran mode provides special motion commands for Fortran statements and
-subprograms, and indentation commands that understand Fortran conventions
-of nesting, line numbers and continuation statements. Fortran mode has
-its own Auto Fill mode that breaks long lines into proper Fortran
-continuation lines.
-
- Special commands for comments are provided because Fortran comments
-are unlike those of other languages. Built-in abbrevs optionally save
-typing when you insert Fortran keywords.
-
-@findex fortran-mode
- Use @kbd{M-x fortran-mode} to switch to this major mode. This command
-runs the hook @code{fortran-mode-hook} (@pxref{Hooks}).
-
-@cindex Fortran77
-@cindex Fortran90
-@findex f90-mode
-@findex fortran-mode
-Note that Fortan mode described here (obtained with the
-@code{fortran-mode} command) is for editing the old Fortran77
-idiosyncratic `fixed format' source form. For editing the modern
-Fortran90 `free format' source form (which is supported by the GNU
-Fortran compiler) use @code{f90-mode}.
-
-By default @code{fortran-mode} is invoked on files with extension
-@samp{.f}, @samp{.F} or @samp{.for} and @code{f90-mode} is invoked for
-the extension @samp{.f90}.
-
-@menu
-* Motion: Fortran Motion. Moving point by statements or subprograms.
-* Indent: Fortran Indent. Indentation commands for Fortran.
-* Comments: Fortran Comments. Inserting and aligning comments.
-* Autofill: Fortran Autofill. Auto fill minor mode for Fortran.
-* Columns: Fortran Columns. Measuring columns for valid Fortran.
-* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
-* Misc: Fortran Misc. Other Fortran mode features.
-@end menu
-
-@node Fortran Motion
-@subsection Motion Commands
-
-In addition to the normal commands for moving by and operating on
-`defuns' (Fortran subprograms---functions
-and subroutines) Fortran mode provides special commands to move by statements.
-
-@kindex C-c C-p @r{(Fortran mode)}
-@kindex C-c C-n @r{(Fortran mode)}
-@findex fortran-previous-statement
-@findex fortran-next-statement
-
-@table @kbd
-@item C-c C-n
-Move to beginning of current or next statement
-(@code{fortran-next-statement}).
-@item C-c C-p
-Move to beginning of current or previous statement
-(@code{fortran-previous-statement}).
-@end table
-
-@node Fortran Indent
-@subsection Fortran Indentation
-
- Special commands and features are needed for indenting Fortran code in
-order to make sure various syntactic entities (line numbers, comment line
-indicators and continuation line flags) appear in the columns that are
-required for standard Fortran.
-
-@menu
-* Commands: ForIndent Commands. Commands for indenting and filling Fortran.
-* Contline: ForIndent Cont. How continuation lines indent.
-* Numbers: ForIndent Num. How line numbers auto-indent.
-* Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
-* Vars: ForIndent Vars. Variables controlling Fortran indent style.
-@end menu
-
-@node ForIndent Commands
-@subsubsection Fortran-Specific Indentation and Filling Commands
-
-@table @kbd
-@item C-M-j
-Break the current line and set up a continuation line
-(@code{fortran-split-line}).
-@item M-^
-Join this line to the previous line (@code{fortran-join-line}).
-@item C-M-q
-Indent all the lines of the subprogram point is in
-(@code{fortran-indent-subprogram}).
-@item M-q
-Fill a comment block or statement.
-@end table
-
-@kindex C-M-q @r{(Fortran mode)}
-@findex fortran-indent-subprogram
- The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
-to reindent all the lines of the Fortran subprogram (function or
-subroutine) containing point.
-
-@kindex C-M-j @r{(Fortran mode)}
-@findex fortran-split-line
- The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
-a line in the appropriate fashion for Fortran. In a non-comment line,
-the second half becomes a continuation line and is indented
-accordingly. In a comment line, both halves become separate comment
-lines.
-
-@kindex M-^ @r{(Fortran mode)}
-@kindex C-c C-d @r{(Fortran mode)}
-@findex fortran-join-line
- @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
-which joins a continuation line back to the previous line, roughly as
-the inverse of @code{fortran-split-line}. The point must be on a
-continuation line when this command is invoked.
-
-@kindex M-q @r{(Fortran mode)}
-Fortran mode defines the function for filling paragraphs such that
-@kbd{M-q} fills the comment block or statement around point. Filling a
-statement removes excess statement continuations.
-
-@node ForIndent Cont
-@subsubsection Continuation Lines
-@cindex Fortran continuation lines
-
-@vindex fortran-continuation-string
- Most modern Fortran compilers allow two ways of writing continuation
-lines. If the first non-space character on a line is in column 5, then
-that line is a continuation of the previous line. We call this
-@dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The
-variable @code{fortran-continuation-string} specifies what character to
-put on column 5. A line that starts with a tab character followed by
-any digit except @samp{0} is also a continuation line. We call this
-style of continuation @dfn{tab format}.
-
-@vindex indent-tabs-mode @r{(Fortran mode)}
- Fortran mode can make either style of continuation line, but you
-must specify which one you prefer. The value of the variable
-@code{indent-tabs-mode} controls the choice: @code{nil} for fixed
-format, and non-@code{nil} for tab format. You can tell which style
-is presently in effect by the presence or absence of the string
-@samp{Tab} in the mode line.
-
- If the text on a line starts with the conventional Fortran
-continuation marker @samp{$}, or if it begins with any non-whitespace
-character in column 5, Fortran mode treats it as a continuation line.
-When you indent a continuation line with @key{TAB}, it converts the line
-to the current continuation style. When you split a Fortran statement
-with @kbd{C-M-j}, the continuation marker on the newline is created
-according to the continuation style.
-
- The setting of continuation style affects several other aspects of
-editing in Fortran mode. In fixed format mode, the minimum column
-number for the body of a statement is 6. Lines inside of Fortran
-blocks that are indented to larger column numbers always use only the
-space character for whitespace. In tab format mode, the minimum
-column number for the statement body is 8, and the whitespace before
-column 8 must always consist of one tab character.
-
-@vindex fortran-tab-mode-default
-@vindex fortran-analyze-depth
- When you enter Fortran mode for an existing file, it tries to deduce the
-proper continuation style automatically from the file contents. The first
-line that begins with either a tab character or six spaces determines the
-choice. The variable @code{fortran-analyze-depth} specifies how many lines
-to consider (at the beginning of the file); if none of those lines
-indicates a style, then the variable @code{fortran-tab-mode-default}
-specifies the style. If it is @code{nil}, that specifies fixed format, and
-non-@code{nil} specifies tab format.
-
-@node ForIndent Num
-@subsubsection Line Numbers
-
- If a number is the first non-whitespace in the line, Fortran
-indentation assumes it is a line number and moves it to columns 0
-through 4. (Columns always count from 0 in GNU Emacs.)
-
-@vindex fortran-line-number-indent
- Line numbers of four digits or less are normally indented one space.
-The variable @code{fortran-line-number-indent} controls this; it
-specifies the maximum indentation a line number can have. Line numbers
-are indented to right-justify them to end in column 4 unless that would
-require more than this maximum indentation. The default value of the
-variable is 1.
-
-@vindex fortran-electric-line-number
- Simply inserting a line number is enough to indent it according to
-these rules. As each digit is inserted, the indentation is recomputed.
-To turn off this feature, set the variable
-@code{fortran-electric-line-number} to @code{nil}. Then inserting line
-numbers is like inserting anything else.
-
-@node ForIndent Conv
-@subsubsection Syntactic Conventions
-
- Fortran mode assumes that you follow certain conventions that simplify
-the task of understanding a Fortran program well enough to indent it
-properly:
-
-@itemize @bullet
-@item
-Two nested @samp{do} loops never share a @samp{continue} statement.
-
-@item
-Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
-and others are written without embedded whitespace or line breaks.
-
-Fortran compilers generally ignore whitespace outside of string
-constants, but Fortran mode does not recognize these keywords if they
-are not contiguous. Constructs such as @samp{else if} or @samp{end do}
-are acceptable, but the second word should be on the same line as the
-first and not on a continuation line.
-@end itemize
-
-@noindent
-If you fail to follow these conventions, the indentation commands may
-indent some lines unaesthetically. However, a correct Fortran program
-retains its meaning when reindented even if the conventions are not
-followed.
-
-@node ForIndent Vars
-@subsubsection Variables for Fortran Indentation
-
-@vindex fortran-do-indent
-@vindex fortran-if-indent
-@vindex fortran-structure-indent
-@vindex fortran-continuation-indent
-@vindex fortran-check-all-num@dots{}
-@vindex fortran-minimum-statement-indent@dots{}
- Several additional variables control how Fortran indentation works:
-
-@table @code
-@item fortran-do-indent
-Extra indentation within each level of @samp{do} statement (default 3).
-
-@item fortran-if-indent
-Extra indentation within each level of @samp{if} statement (default 3).
-This value is also used for extra indentation within each level of the
-Fortran 90 @samp{where} statement.
-
-@item fortran-structure-indent
-Extra indentation within each level of @samp{structure}, @samp{union}, or
-@samp{map} statements (default 3).
-
-@item fortran-continuation-indent
-Extra indentation for bodies of continuation lines (default 5).
-
-@item fortran-check-all-num-for-matching-do
-If this is @code{nil}, indentation assumes that each @samp{do} statement
-ends on a @samp{continue} statement. Therefore, when computing
-indentation for a statement other than @samp{continue}, it can save time
-by not checking for a @samp{do} statement ending there. If this is
-non-@code{nil}, indenting any numbered statement must check for a
-@samp{do} that ends there. The default is @code{nil}.
-
-@item fortran-blink-matching-if
-If this is @code{t}, indenting an @samp{endif} statement moves the
-cursor momentarily to the matching @samp{if} statement to show where it
-is. The default is @code{nil}.
-
-@item fortran-minimum-statement-indent-fixed
-Minimum indentation for fortran statements when using fixed format
-continuation line style. Statement bodies are never indented less than
-this much. The default is 6.
-
-@item fortran-minimum-statement-indent-tab
-Minimum indentation for fortran statements for tab format continuation line
-style. Statement bodies are never indented less than this much. The
-default is 8.
-@end table
-
-@node Fortran Comments
-@subsection Fortran Comments
-
- The usual Emacs comment commands assume that a comment can follow a line
-of code. In Fortran, the standard comment syntax requires an entire line
-to be just a comment. Therefore, Fortran mode replaces the standard Emacs
-comment commands and defines some new variables.
-
- Fortran mode can also handle the Fortran90 comment syntax where comments
-start with @samp{!} and can follow other text. Because only some Fortran77
-compilers accept this syntax, Fortran mode will not insert such comments
-unless you have said in advance to do so. To do this, set the variable
-@code{comment-start} to @samp{"!"} (@pxref{Variables}).
-
-@table @kbd
-@item M-;
-Align comment or insert new comment (@code{fortran-comment-indent}).
-
-@item C-x ;
-Applies to nonstandard @samp{!} comments only.
-
-@item C-c ;
-Turn all lines of the region into comments, or (with argument) turn them back
-into real code (@code{fortran-comment-region}).
-@end table
-
- @kbd{M-;} in Fortran mode is redefined as the command
-@code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this
-recognizes any kind of existing comment and aligns its text appropriately;
-if there is no existing comment, a comment is inserted and aligned. But
-inserting and aligning comments are not the same in Fortran mode as in
-other modes.
-
- When a new comment must be inserted, if the current line is blank, a
-full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
-comment is inserted if you have said you want to use them. Otherwise a
-full-line comment is inserted on a new line before the current line.
-
- Nonstandard @samp{!} comments are aligned like comments in other
-languages, but full-line comments are different. In a standard full-line
-comment, the comment delimiter itself must always appear in column zero.
-What can be aligned is the text within the comment. You can choose from
-three styles of alignment by setting the variable
-@code{fortran-comment-indent-style} to one of these values:
-
-@vindex fortran-comment-indent-style
-@vindex fortran-comment-line-extra-indent
-@table @code
-@item fixed
-Align the text at a fixed column, which is the sum of
-@code{fortran-comment-line-extra-indent} and the minimum statement
-indentation. This is the default.
-
-The minimum statement indentation is
-@code{fortran-minimum-statement-indent-fixed} for fixed format
-continuation line style and @code{fortran-minimum-statement-indent-tab}
-for tab format style.
-
-@item relative
-Align the text as if it were a line of code, but with an additional
-@code{fortran-comment-line-extra-indent} columns of indentation.
-
-@item nil
-Don't move text in full-line comments automatically at all.
-@end table
-
-@vindex fortran-comment-indent-char
- In addition, you can specify the character to be used to indent within
-full-line comments by setting the variable
-@code{fortran-comment-indent-char} to the single-character string you want
-to use.
-
-@vindex comment-line-start
-@vindex comment-line-start-skip
- Fortran mode introduces two variables @code{comment-line-start} and
-@code{comment-line-start-skip}, which play for full-line comments the same
-roles played by @code{comment-start} and @code{comment-start-skip} for
-ordinary text-following comments. Normally these are set properly by
-Fortran mode, so you do not need to change them.
-
- The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
-you use @samp{!} comments, this command can be used with them. Otherwise
-it is useless in Fortran mode.
-
-@kindex C-c ; @r{(Fortran mode)}
-@findex fortran-comment-region
-@vindex fortran-comment-region
- The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
-lines of the region into comments by inserting the string @samp{C$$$} at
-the front of each one. With a numeric argument, it turns the region
-back into live code by deleting @samp{C$$$} from the front of each line
-in it. The string used for these comments can be controlled by setting
-the variable @code{fortran-comment-region}. Note that here we have an
-example of a command and a variable with the same name; these two uses
-of the name never conflict because in Lisp and in Emacs it is always
-clear from the context which one is meant.
-
-@node Fortran Autofill
-@subsection Fortran Auto Fill Mode
-
- Fortran Auto Fill mode is a minor mode which automatically splits
-Fortran statements as you insert them when they become too wide.
-Splitting a statement involves making continuation lines using
-@code{fortran-continuation-string} (@pxref{ForIndent Cont}). This
-splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and
-also in the Fortran indentation commands.
-
-@findex fortran-auto-fill-mode
- @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it
-was off, or off if it was on. This command works the same as @kbd{M-x
-auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A
-positive numeric argument turns Fortran Auto Fill mode on, and a
-negative argument turns it off. You can see when Fortran Auto Fill mode
-is in effect by the presence of the word @samp{Fill} in the mode line,
-inside the parentheses. Fortran Auto Fill mode is a minor mode, turned
-on or off for each buffer individually. @xref{Minor Modes}.
-
-@vindex fortran-break-before-delimiters
- Fortran Auto Fill mode breaks lines at spaces or delimiters when the
-lines get longer than the desired width (the value of @code{fill-column}).
-The delimiters that Fortran Auto Fill mode may break at are @samp{,},
-@samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}.
-The line break comes after the delimiter if the variable
-@code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by
-default), the break comes before the delimiter.
-
- By default, Fortran Auto Fill mode is not enabled. If you want this
-feature turned on permanently, add a hook function to
-@code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}.
-@xref{Hooks}.
-
-@node Fortran Columns
-@subsection Checking Columns in Fortran
-
-@table @kbd
-@item C-c C-r
-Display a ``column ruler'' momentarily above the current line
-(@code{fortran-column-ruler}).
-@item C-c C-w
-Split the current window horizontally temporarily so that it is 72
-columns wide. This may help you avoid making lines longer than the
-72-character limit that some Fortran compilers impose
-(@code{fortran-window-create-momentarily}).
-@end table
-
-@kindex C-c C-r @r{(Fortran mode)}
-@findex fortran-column-ruler
-@vindex fortran-column-ruler
- The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
-ruler momentarily above the current line. The comment ruler is two lines
-of text that show you the locations of columns with special significance in
-Fortran programs. Square brackets show the limits of the columns for line
-numbers, and curly brackets show the limits of the columns for the
-statement body. Column numbers appear above them.
-
- Note that the column numbers count from zero, as always in GNU Emacs.
-As a result, the numbers may be one less than those you are familiar
-with; but the positions they indicate in the line are standard for
-Fortran.
-
- The text used to display the column ruler depends on the value of
-the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is
-@code{nil}, then the value of the variable
-@code{fortran-column-ruler-fixed} is used as the column ruler.
-Otherwise, the variable @code{fortran-column-ruler-tab} is displayed.
-By changing these variables, you can change the column ruler display.
-
-@kindex C-u C-c C-w @r{(Fortran mode)}
-@findex fortran-window-create
- For even more help, use @kbd{M-x fortran-window-create}), a
-command which splits the current window horizontally, making a window 72
-columns wide. By editing in this window you can immediately see when you
-make a line too wide to be correct Fortran.
-
-@kindex C-c C-w @r{(Fortran mode)}
-@findex fortran-window-create-momentarily
-Also, @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) can be
-used temporarily to split the current window horizontally, making a
-window 72 columns wide to check column widths rather than to edit in
-this mode. The normal width is restored when you type a space.
-
-@node Fortran Abbrev
-@subsection Fortran Keyword Abbrevs
-
- Fortran mode provides many built-in abbrevs for common keywords and
-declarations. These are the same sort of abbrev that you can define
-yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}.
-
- The built-in abbrevs are unusual in one way: they all start with a
-semicolon. You cannot normally use semicolon in an abbrev, but Fortran
-mode makes this possible by changing the syntax of semicolon to ``word
-constituent.''
-
- For example, one built-in Fortran abbrev is @samp{;c} for
-@samp{continue}. If you insert @samp{;c} and then insert a punctuation
-character such as a space or a newline, the @samp{;c} expands automatically
-to @samp{continue}, provided Abbrev mode is enabled.@refill
-
- Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
-Fortran abbrevs and what they stand for.
-
-@node Fortran Misc
-@subsection Other Fortran Mode Commands
-
-The command @kbd{fortran-strip-sqeuence-nos} can be used to remove text
-past Fortran column 72, which is typically old `sequence numbers'.
-
@node Asm Mode
@section Asm Mode
@cindex Asm mode
-@cindex Assembler mode
+@cindex assembler mode
Asm mode is a major mode for editing files of assembler code. It
defines these commands:
The variable @code{asm-comment-char} specifies which character
starts comments in assembler syntax.
+
+@ifnottex
+@include fortran-xtra.texi
+@end ifnottex
+
+@ignore
+ arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0
+@end ignore