@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,86,87,93,94,95,97,99,00,2001 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}).
-@item
-Show how parentheses balance (@pxref{Matching}).
+Apply the usual indentation conventions of the language
+(@pxref{Program Indent}).
@item
Insert, kill or align comments (@pxref{Comments}).
@item
-Follow the usual indentation conventions of the language
-(@pxref{Program Indent}).
+Balance parentheses (@pxref{Parentheses}).
+@item
+Highlight program syntax (@pxref{Font Lock}).
@end itemize
- Emacs commands that operate on 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.
-
- 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}).
-
- The ``automatic typing'' features may be useful for writing programs.
-@xref{Top,,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.
* 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.
+* Parentheses:: Commands that operate on parentheses.
+* 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.
@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 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 @samp{BAT} files. In a similar fashion to programming
-languages, modes are provided for editing 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
-(@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-command}.
-@kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB};
-thus, it too indents in a mode-specific fashion.
+ The existing programming language major modes include Lisp, Scheme (a
+variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
+Awk, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
+format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
+companion for font creation), Modula2, Objective-C, Octave, Pascal,
+Perl, Pike, PostScript, Prolog, Simula, Tcl, and VHDL. There is
+also a major mode for makefiles, called Makefile mode. An alternative
+mode for Perl is called CPerl mode. Modes are available for the
+scripting languages of the common GNU and Unix shells, VMS DCL, and
+MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for
+editing various sorts of configuration files.
@kindex DEL @r{(programming modes)}
@findex c-electric-backspace
- 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{c-electric-backspace}). 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.
+ 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
+(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
+(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).
@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
- 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
-
-@cindex parentheses, moving across
-@cindex matching parenthesis and braces, moving to
-@cindex braces, moving across
-@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 is
+called a @dfn{defun}. The name comes from Lisp, but in Emacs we use
+it for all languages.
-@cindex deleting parenthesized expressions
-@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.
+ In most programming language modes, Emacs assumes that a defun is
+any pair of parentheses (or braces, if the language uses braces this
+way) that starts at the left margin. For example, in C, the body of a
+function definition is normally a defun, because the open-brace that
+begins it is normally at the left margin. A variable's initializer
+can also count as a defun, if the open-brace that begins the
+initializer is at the left margin.
-@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
+ However, some language modes provide their own code for recognizing
+defuns in a way that suits the language syntax and conventions better.
-@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.
+@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
-@cindex transposition of parenthesized 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 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.
+@node Left Margin Paren
+@subsection Left Margin Convention
-@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.
+@cindex open-parenthesis in leftmost column
+@cindex ( in leftmost column
+ In most major modes, Emacs assumes that any opening delimiter found
+at the left margin is the start of a top-level definition, or defun.
+Therefore, @strong{never put an opening delimiter at the left margin
+unless it should have that significance.} For instance, never put an
+open-parenthesis at the left margin in a Lisp file unless it is the
+start of a top-level list. Never put an open-brace or other opening
+delimiter at the beginning of a line of C code unless it is at top
+level.
+
+ If you don't follow this convention, not only will you have trouble
+when you explicitly use the commands for motion by defuns; other
+features that use them will also give you trouble. This includes
+the indentation commands (@pxref{Program Indent}) and Font Lock
+mode (@pxref{Font Lock}).
+
+ The most likely problem case is when you want an opening delimiter
+at the start of a line inside a string. To avoid trouble, put an
+escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some
+other Lisp dialects) before the opening delimiter. This will not
+affect the contents of the string, but will prevent that opening
+delimiter from starting a defun. Here's an example:
- 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
+ In the earliest days, the original Emacs found defuns by moving
+upward a level of parentheses or braces until there were no more
+levels to go up. This always required scanning all the way back to
+the beginning of the buffer, even for a small function. To speed up
+the operation, we changed Emacs to assume that any opening delimiter
+at the left margin is the start of a defun. This heuristic is nearly
+always right, and avoids the need to scan back to the beginning of the
+buffer. However, it mandates following the convention described
+above.
+
+@node Moving by Defuns
+@subsection Moving by Defuns
@cindex defuns
- 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
@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.
+
+ 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 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 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 only takes effect in certain major modes, those listed in the value of
+@code{which-func-modes}. If the value is @code{t}, then Which
+Function mode applies to all major modes that know how to support
+it---in other words, all the major modes that support Imenu.
@node Program Indent
@section Indentation for Programs
* 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}).
+@item @key{LINEFEED}
+This key, if the keyboard has it, is another way to enter @kbd{C-j}.
@end table
@kindex TAB @r{(programming modes)}
@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{indent-for-tab-command}
+function that @key{TAB} runs depends on the major mode; it is
+@code{indent-for-tab-command}
in Lisp mode, @code{c-indent-command} 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
+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.
@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.
+ When entering lines of new code, use @kbd{C-j}
+(@code{newline-and-indent}), which is equivalent to a @key{RET}
+followed by a @key{TAB}. @kbd{C-j} at the end of a line creates a
+blank line and then gives it the appropriate indentation.
+
+ @key{TAB} indents lines that start within a parenthetical grouping
+each under the preceding line (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.
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.
+commands fast; you must simply accept it. @xref{Left Margin Paren},
+for more information on this.
Normally, lines are indented with tabs and spaces. If you want Emacs
to use spaces only, see @ref{Just Spaces}.
@node Multi-line Indent
@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-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}.
+ 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-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, or C preprocessor lines when in C mode.
+
+@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 comment or a string, unless the region starts inside that
+comment or string.
@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
+ Certain functions override the standard pattern. Functions whose
+names start with @code{def} treat the the second lines as the start of
+a @dfn{body}, by indenting the second line @code{lisp-body-indent}
+additional columns beyond the open-parenthesis that starts the
+expression.
+
+@cindex @code{lisp-indent-function} property
+ You can override the standard pattern in various ways for individual
functions, according to the @code{lisp-indent-function} property of the
function name. There are four possibilities for this property:
@table @asis
@item @code{nil}
-This is the same as no property; the standard indentation pattern is used.
+This is the same as no property---use the standard indentation pattern.
@item @code{defun}
-The pattern used for function names that start with @code{def} is used for
-this function also.
+Handle this function like a @samp{def} construct: treat the second
+line as the start of a @dfn{body}.
@item a number, @var{number}
The first @var{number} arguments of the function are
-@dfn{distinguished} arguments; the rest are considered the @dfn{body}
+@dfn{distinguished} arguments; the rest are considered the body
of the expression. A line in the expression is indented according to
whether the first argument on it is distinguished or not. If the
argument is part of the body, the line is indented @code{lisp-body-indent}
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.
+the line uses the standard pattern.
@item a symbol, @var{symbol}
@var{symbol} should be a function name; that function is called to
calculate the indentation of a line within this expression. The
@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
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}.
@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
-syntactic analysis: ((statement . 32))
-@end example
+indentation offset based on your selected @dfn{style}.
- 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:
+@table @kbd
+@item M-x c-set-style @key{RET} @var{style} @key{RET}
+Select predefined indentation style @var{style}.
+@end table
-@example
-syntactic analysis: ((defun-block-intro . 28))
-@end example
+ A style is a named collection of indentation customizations that can
+be used in C mode and the related modes. Emacs comes with several
+predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
+@code{stroustrup}, @code{linux}, @code{python}, @code{java},
+@code{whitesmith}, @code{ellemtel}, @code{cc-mode}, and @code{user}.
+Some of these styles are primarily intended for one language, but any
+of them can be used with any of the languages supported by these
+modes. To find out what a style looks like, select it and reindent
+some code, e.g., by typing @key{C-M-q} at the start of a function
+definition.
- 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.
+@findex c-set-style
+ To choose a style for the current buffer, use the command @kbd{M-x
+c-set-style}. Specify a style name as an argument (case is not
+significant). This command affects the current buffer only, and it
+affects only future invocations of the indentation commands; it does
+not reindent the code 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 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") (other . "gnu")))
@end example
@noindent
-Typing @kbd{C-c C-s} on line 4 displays this:
-
-@example
-syntactic analysis: ((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 an explicit choice for Java mode, and the default @samp{gnu}
+style for the other C-like modes. 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.
- 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.
+ 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.
- 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.
+ @xref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for
+more information on customizing indentation for C and related modes,
+including how to override parts of an existing style and how to define
+your own styles.
-@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
+@node Parentheses
+@section Commands for Editing with Parentheses
- 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:
+@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.
-@example
-((substatement-open . 43))
-@end example
+ 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.
- 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.
+ You can use @kbd{M-x check-parens} to find any unbalanced
+parentheses and unbalanced string quotes in the buffer.
-@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.
+@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
-@node Changing Indent Style
-@subsubsection Changing Indentation Style
+@node Expressions
+@subsection Expressions with Balanced Parentheses
- 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-@key{DEL}
+Kill balanced expression backward (@code{backward-kill-sexp}).
+@item C-M-t
+Transpose expressions (@code{transpose-sexps}).
+@item C-M-@@
+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}.
+ 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.
-@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.
+@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-close
-On a brace that closes a function definition.
+@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 defun-block-intro
-In the first line in a top-level defun.
+ 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-open
-On a brace that opens 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 class-close
-On a brace that closes a class definition.
+@cindex killing expressions
+@kindex C-M-k
+@findex kill-sexp
+@kindex C-M-DEL
+@findex backward-kill-sexp
+ Killing a whole balanced expression can be done with @kbd{C-M-k}
+(@code{kill-sexp}) or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}).
+@kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over, and
+@kbd{C-M-@key{DEL}} kills the characters that @kbd{C-M-b} would move
+over. On some machines, @kbd{C-M-@key{DEL}} typed on the console is a
+command to reboot; when that is so, you cannot use it as an Emacs
+command. This conflict is rare, though: usually the @key{DEL} key for
+Emacs is really @key{BACKSPACE}, and the reboot command is
+@kbd{C-M-@key{DELETE}}, so there is no conflict.
+
+@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, and a negative argument drags the previous balanced
+expression backwards across those before it (thus canceling out the
+effect of @kbd{C-M-t} with a positive argument). An argument of zero,
+rather than doing nothing, transposes the balanced expressions ending
+at or after point and the mark.
-@item inline-open
-On a brace that opens an in-class inline method.
+@kindex C-M-@@
+@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.
+
+ 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 inline-close
-On a brace that closes an in-class inline method.
+@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 extern-lang-open
-On a brace that opens an external language block.
+@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 extern-lang-close
-On a brace that closes an external language block.
+@kindex C-M-u
+@kindex C-M-d
+@findex backward-up-list
+@findex down-list
+ @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
+parenthesis structure. To move @emph{up} one (or @var{n}) levels, use
+@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up
+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.
+
+ 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 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.
+@node Matching
+@subsection Automatic Display Of Matching Parentheses
+@cindex matching parentheses
+@cindex parentheses, displaying matches
-@item knr-argdecl-intro
-On the first line of a K&R C argument declaration.
+ 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 knr-argdecl
-In one of the subsequent lines in a K&R C argument declaration.
+ If the opening delimiter and closing delimiter are mismatched---such
+as in @samp{[x)}---a warning message is displayed in the echo area.
-@item topmost-intro
-On the first line in a topmost construct definition.
+@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}
+disables it, but the default is @code{t} to enable match display.
-@item topmost-intro-cont
-On the topmost definition continuation 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 member-init-intro
-On the first line in a member initialization list.
+ @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 member-init-cont
-On one of the subsequent member initialization list lines.
+@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.
-@item inher-intro
-On the first line of a multiple inheritance list.
+ By default, @code{show-paren-mode} uses colors to highlight the
+parentheses. However, if your display doesn't support colors, you can
+customize the faces @code{show-paren-match-face} and
+@code{show-paren-mismatch-face} to use other attributes, such as bold or
+underline. @xref{Face Customization}.
-@item inher-cont
-On one of the subsequent multiple inheritance lines.
+@node Comments
+@section Manipulating Comments
+@cindex comments
-@item block-open
-On a statement block open brace.
+ Because comments are such an important part of programming, Emacs
+provides special commands for editing and inserting comments.
-@item block-close
-On a statement block close brace.
+@menu
+* Comment Commands:: Inserting, killing, and indenting comments.
+* Multi-Line Comments:: Commands for adding and editing multi-line comments.
+* Options for Comments::Customizing the comment features.
+@end menu
-@item brace-list-open
-On the opening brace of an @code{enum} or @code{static} array list.
+@node Comment Commands
+@subsection Comment Commands
+@cindex indentation for comments
-@item brace-list-close
-On the closing brace of an @code{enum} or @code{static} array list.
-
-@item brace-list-intro
-On the first line in an @code{enum} or @code{static} array list.
-
-@item brace-list-entry
-On one of the subsequent lines in an @code{enum} or @code{static} array
-list.
-
-@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.
-
-@item statement
-On an ordinary statement.
-
-@item statement-cont
-On a continuation line of a statement.
-
-@item statement-block-intro
-On the first line in a new statement block.
-
-@item statement-case-intro
-On the first line in a @code{case} ``block.''
-
-@item statement-case-open
-On the first line in a @code{case} block starting with brace.
-
-@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.
-
-@item inexpr-class
-On a class definition inside an expression. This is used for anonymous
-classes and anonymous array initializers in Java.
-
-@item substatement
-On the first line after an @code{if}, @code{while}, @code{for},
-@code{do}, or @code{else}.
-
-@item substatement-open
-On the brace that opens a substatement block.
-
-@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. However, if you make changes in variables such as
-@code{c-basic-offset} and @code{c-offsets-alist} in your
-@file{~/.emacs} file, your changes override the what @code{gnu} style
-says.
-
-@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 25600.
-
-@cindex Show Paren mode
-@cindex highlighting matching parentheses
-@findex show-paren-mode
- Show Paren mode provides a more powerful kind of automatic
-parenthesis matching. 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.
-
- By default, @code{show-paren-mode} uses colors to highlight the
-parentheses. However, if your display doesn't support colors, you can
-customize the faces @code{show-paren-match-face} and
-@code{show-paren-mismatch-face} to use other attributes, such as bold or
-underline. @xref{Face Customization}.
-
-@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
-@cindex indentation for comments
-
- The comment commands in this table insert, kill and align comments.
-They are described in this section and following sections.
+ The comment commands in this table insert, kill and align comments.
+They are described in this section and following sections.
@table @kbd
@item M-;
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.
+@node Documentation
+@section Documentation Lookup
-@findex check-parens
-@cindex unbalanced parentheses and quotes
- You can use @kbd{M-x check-parens} to find any unbalanced
-parentheses and unbalanced string quotes in a buffer.
+ 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.
-@node Symbol Completion
-@section Completion for Symbol Names
-@cindex completion (symbol names)
+@menu
+* 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
- Usually completion happens in the minibuffer. But one kind of completion
-is available in all buffers: completion for symbol names.
+@node Info Lookup
+@subsection Info Documentation Lookup
-@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
+@findex info-lookup-symbol
+@findex info-lookup-file
+@kindex C-h C-i
+ For C, Lisp, and other languages that have documentation in Info,
+you can use @kbd{C-h C-i} (@code{info-lookup-symbol}) to view the Info
+documentation for a symbol. You specify the symbol with the
+minibuffer; the default is the symbol appearing in the buffer 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 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.
-
-@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}.
-
- 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 portions of a
-file, 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.
-
- 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.
-
-@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
-
-@vindex hs-hide-comments-when-hiding-all
-@vindex hs-isearch-open
-@vindex hs-special-modes-alist
- These user options exist for customizing Hideshow mode.
-
-@table @code
-@item hs-hide-comments-when-hiding-all
-Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
-@item hs-isearch-open
-Specifies what kind of hidden blocks to open in Isearch mode.
-@item hs-special-modes-alist
-Specifies
-Initializes Hideshow variables for different modes.
-@end table
-
-@node Glasses
-@section Glasses minor mode
-@cindex Glasses mode
-@cindex identifiers, making long ones readable
-@cindex StudlyCaps, making them readable
-@findex glasses-mode
-
- Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
-readable by altering the display. It can do this in two different
-ways: by displaying underscores between an lower-case letter and the
-following capital letter, or by emboldening the capital letters. It
-does not alter the buffer text, only the way they display, so you can
-use it even on read-only buffers. You can use the command @kbd{M-x
-glasses-mode} to enable or disable the mode; you can also add
-@code{glasses-mode} to the mode hook of appropriate programming
-language major modes.
-
-@node Documentation
-@section Documentation Commands
+ 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.
- 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.
+ This feature currently supports the modes Awk, Autoconf, Bison, C,
+Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme, and Texinfo,
+provided you have installed the relevant Info files, which are
+typically available with the appropriate GNU package.
- 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.
+@node Man Page
+@subsection Man Page Lookup
-@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 this supports the following
-modes: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4,
-Makefile, Octave, Perl, Scheme and Texinfo, provided you have installed
-the relevant Info files, which are typically available with the appropriate GNU
-package.
+@cindex manual page
+ On Unix, the main form of on-line documentation was the @dfn{manual
+page} or @dfn{man page}. In the GNU operating system, we hope to
+replace man pages with better-organized manuals that you can browse
+with Info (@pxref{Misc Help}). This process is not finished, so it is
+still useful to read manual pages.
@findex manual-entry
-@cindex manual pages
- You can read the ``man page'' for an operating system command, library
+ 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.
+runs the @code{man} program to format the man page; if the system
+permits, it runs @code{man} asynchronously, so that you can keep on
+editing while the page is being formatted. (On MS-DOS and MS-Windows
+3, you cannot edit while Emacs waits for @code{man} to finish.) The
+result goes in a buffer named @samp{*Man @var{topic}*}. These buffers
+use a special major mode, Man mode, that facilitates scrolling and
+jumping to other manual pages. For details, type @kbd{C-h m} while in
+a man page buffer.
@cindex sections of manual pages
- Man pages are classified into @dfn{sections}; sometimes there are
-man pages with the same name in different sections. To read a man
-page from a specific section, type @samp{@var{topic}(@var{section})} or
-@samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts
-for the topic. For example, to read the man page for the C library
-function @code{chmod} (as opposed to a command by the same name), type
-@kbd{M-x manual-entry @key{RET} chmod(2v) @key{RET}} (assuming
-@code{chmod} is in section @samp{2v}).
-
+ 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} command works on your system. Some of them display only
+@code{man} program works on your system. Some of them display only
the first man page they find. Others display all man pages that have
-the specified name, so you can 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.
+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.
@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}.
+ By default, Emacs highlights the text in man pages. For a long man
+page, highlighting can take substantial time. You can turn off
+highlighting of man pages by setting the variable
+@code{Man-fontify-manpage-flag} to @code{nil}.
@findex Man-fontify-manpage
If you insert the text of a man page into an Emacs buffer in some
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 the programs it needs are not readily
-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
-name of the manual page.
+@code{man} program (and the 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.
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
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.
+ By default, @kbd{M-x woman} looks for manual pages in the
+directories specified in the @code{MANPATH} environment variable. (If
+@code{MANPATH} is not set, @code{woman} uses a suitable default value,
+which can be customized.) More precisely, @code{woman} looks for
+subdirectories that match the shell wildcard pattern @file{man*} in each one
+of these directories, and tries to find the manual pages in those
+subdirectories. When first invoked, @kbd{M-x woman} converts the
+value of @code{MANPATH} to a list of directory names and stores that
+list in the @code{woman-manpath} variable. Changing the value of this
+variable is another way to control the list of directories used.
@vindex woman-path
- In addition, you can augment the list of directories searched by
+ You can also augment the list of directories searched by
@code{woman} by setting the value of the @code{woman-path} variable.
This variable should hold a list of specific directories which
@code{woman} should search, in addition to those in
@code{woman-manpath}. Unlike @code{woman-manpath}, the directories in
-@code{woman-path} are searched for the manual pages, not for @file{man*}
-subdirectories.
+@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
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.
+ The first time you invoke @kbd{M-x woman}, it defines the Dired
+@kbd{W} key to run the @code{woman-find-file} command on the current
+line's file. You can disable this by setting the variable
+@code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition,
+the Tar-mode @kbd{w} key is define to invoke @code{woman-find-file} on
+the current line's archive member.
For more information about setting up and using @kbd{M-x woman}, see
@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
Manual}.
- 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---that is useful for making log entries for functions that
-have been deleted in the current version.
-
- 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
-
- 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.
-
- @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.
-
-@vindex add-log-keep-changes-together
- When the option @code{add-log-keep-changes-together} is
-non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file
-rather than starting a new entry.
-
-@vindex change-log-version-info-enabled
-@vindex change-log-version-number-regexp-list
-@cindex file version in change log entries
- If the value of the variable @code{change-log-version-info-enabled}
-is non-@code{nil}, @kbd{C-x 4 a} ads the file's version number to the
-change log entry. It finds the version number by searching the first
-ten percent of the file, using regular expressions from the variable
-@code{change-log-version-number-regexp-list}.
-
-@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
- You can use the command @kbd{M-x change-log-merge} to merge other
-log files into a buffer in Change Log Mode, preserving the date
-ordering of entries.
-
-@findex change-log-redate
-@cindex converting change log date style
- Versions of Emacs before 20.1 used a different format for the time of
-the change log entry:
-
-@smallexample
-Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
-@end smallexample
-
-@noindent
-The @kbd{M-x change-log-redate} command converts all the old-style
-date entries in the change log file visited in the current buffer to
-the new format, to make the file uniform in style. This is handy when
-entries are contributed by many different people, some of whom use old
-versions of Emacs.
-
- 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.
-
- Do not assume that this command finds all the contributors; don't
-assume that a person not listed in the output was not a contributor.
-If you merged in someone's contribution and did not put his name
-in the change log, he won't show up in @kbd{M-x authors} either.
-
-@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 file names, 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
- See also the Ebrowse facility, which is tailored for C++.
-@xref{Top,, Ebrowse, 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
+@node Lisp Doc
+@subsection Emacs Lisp Documentation Lookup
- 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}.
-@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.
-
-You can tag function declarations and external variables in addition
-to function definitions by giving the @samp{--declarations} option to
-@code{etags}.
-
-@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} definitions have
-tag names like @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.
+ 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
-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.
-
-In Ada, the same name can be used for different kinds of entity
-(e.g.@:, for a procedure and for a function). Also, for things like
-packages, procedures and functions, there is the spec (i.e.@: the
-interface) and the body (i.e.@: the implementation). To make it
-easier to pick the definition you want, Ada tag name have suffixes
-indicating the type of entity:
-
-@table @samp
-@item /b
-package body.
-@item /f
-function.
-@item /k
-task.
-@item /p
-procedure.
-@item /s
-package spec.
-@item /t
-type.
-@end table
-
- Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
-directly to the body of the package @code{bidule}, while @kbd{M-x
-find-tag @key{RET} bidule @key{RET}} will just search for any tag
-@code{bidule}.
-
-@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 makefiles, targets 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.
-
- If the specified files don't exist, @code{etags} looks for
-compressed versions of them and uncompresses them to read them. Under
-MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
-if it is given @samp{mycode.c} on the command line and @file{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. But it is not necessary to do
-this very 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 virtually 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 covered all the source 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}) works like
-@samp{--regex}, except that matching ignores case. This is
-appropriate for certain 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}.
-
- You can specify a regular expression for a particular language, by
-writing @samp{@{lang@}} in front of it. Then @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, for the C language only:
-
-@smallexample
---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
-@end smallexample
-
-@noindent
-This feature is particularly useful when you store 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; thus, one
-such file can include another file. All the other lines are taken to
-be regular expressions. If the first non-whitespace text on the line
-is @samp{--}, that line is a comment.
-
- For example, one can create a file called @samp{emacs.tags} with the
-following contents:
-
-@smallexample
- -- This is for GNU Emacs C 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 @samp{###key @var{scriptname}} 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
-etags --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
-@cindex search and replace in multiple files
-@cindex multiple-file search and replace
-
- 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.
-
-@vindex tags-case-fold-search
-@cindex case-sensitivity and tags search
- You can control the case-sensitivity of tags search commands by
-customizing the value of the variable @code{tags-case-fold-search}. The
-default is to use the same setting as the value of
-@code{case-fold-search} (@pxref{Search Case}).
-
- 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
-@vindex tags-apropos-verbose
- @kbd{M-x tags-apropos} is like @code{apropos} for tags
-(@pxref{Apropos}). It finds all the tags in the selected tags table
-whose entries match @var{regexp}, and displays them. If the variable
-@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
-of the tags files together with the tag names.
-
-@vindex tags-tag-face
-@vindex tags-apropos-additional-actions
-You can customize the appearance of the output with the face
-@code{tags-tag-face}. 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 use the collection of tag names to complete a symbol
-name in the buffer. @xref{Symbol Completion}.
-
-@node Imenu
-@section Imenu
-@cindex indexes of buffer contents
-@cindex buffer content indexes
-@cindex tags
-
- The Imenu facility is another way to find definitions or sections
-in a file. It is similar in spirit to Tags, but operates on a single
-buffer only, and works entirely within Emacs with no need for a separate
-tags table.
-
-@findex imenu
-@findex imenu-add-menu-bar-index
- If you type @kbd{M-x imenu}, it reads the name of a section or
-definition in the current buffer, then goes to that section or
-definition. You can use completion to specify the name, and a
-complete list of possible names is always displayed.
-
- Alternatively you can bind the command @code{imenu} to a mouse
-click. Then it displays mouse menus for you to select the section or
-definition you want. You can also add the buffer's index to the menu
-bar by calling @code{imenu-add-menu-bar-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-menu-bar-index} to its mode
-hook. But then you will have to wait for the buffer to be searched
-for sections and definitions, each time you visit a file which uses
-that mode.
-
-@vindex imenu-auto-rescan
- When you change the contents of a buffer, if you add or delete
-definitions or sections, you can update the buffer's index to
-correspond to the new contents by invoking the @samp{*Rescan*} item in
-the menu. Rescanning happens automatically if
-@code{imenu-auto-rescan} is non-@code{nil}. There is no need to
-rescan because of small changes in the text.
-
-@vindex imenu-sort-function
- You can customize the way the menus are sorted via the variable
-@code{imenu-sort-function}. By default names are ordered as they
-occur in the buffer; alphabetic sorting is provided as an alternative.
-
- Imenu provides the information to guide Which Function mode
-(@pxref{Which Function}). The Speedbar can also use it
-(@pxref{Speedbar}).
-
-@node Emerge, C Modes, Imenu, Programs
-@section Merging Files with Emerge
-@cindex Emerge
-@cindex merging files
-
-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}.
+@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.) 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.
-@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.
-@end menu
+@node Hideshow
+@section Hideshow minor mode
-@node Overview of Emerge
-@subsection Overview of Emerge
+@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.
-To start Emerge, run one of these four commands:
+ 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.
+@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 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.
+@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
-@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:
+@vindex hs-hide-comments-when-hiding-all
+@vindex hs-isearch-open
+@vindex hs-special-modes-alist
+ These user options exist for customizing Hideshow mode.
-@example
-vvvvvvvvvvvvvvvvvvvv
-@var{text that differs}
-^^^^^^^^^^^^^^^^^^^^
-@end example
+@table @code
+@item hs-hide-comments-when-hiding-all
+Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
-@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:
+@item hs-isearch-open
+Specifies what kind of hidden blocks to open in Isearch mode.
+The value should be one of these four symbols.
-@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}.
+@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 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.
-
-@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.
-
-@item c b
-Copy the B version of this difference into the kill ring.
-
-@item i a
-Insert the A version of this difference at point.
-
-@item i b
-Insert the B version of this difference at point.
-
-@item m
-Put point and mark around the difference.
-
-@item ^
-Scroll all three windows down (like @kbd{M-v}).
-
-@item v
-Scroll all three windows up (like @kbd{C-v}).
-
-@item <
-Scroll all three windows left (like @kbd{C-x <}).
-
-@item >
-Scroll all three windows right (like @kbd{C-x >}).
-
-@item |
-Reset horizontal scroll on all three windows.
-
-@item x 1
-Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
-to full size.)
-
-@item x c
-Combine the two versions of this difference (@pxref{Combining in
-Emerge}).
-
-@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.)
-
-@item x j
-Join this difference with the following one.
-(@kbd{C-u x j} joins this difference with the previous one.)
-
-@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.
-
-@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.
+@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
-@node Exiting Emerge
-@subsection Exiting Emerge
-
- 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.
-
- @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.
-
- 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.
+@node Symbol Completion
+@section Completion for Symbol Names
+@cindex completion (symbol names)
-@node Combining in Emerge
-@subsection Combining the Two Versions
+ 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.
- 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:
+@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.
-@example
-@group
-#ifdef NEW
-@var{version from A buffer}
-#else /* not NEW */
-@var{version from B buffer}
-#endif /* not NEW */
-@end group
-@end example
+ 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.
-@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:
+@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
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.
+* Comments in C:: Options for customizing comment style.
@end menu
@node Motion in C
HCoop / bpt / emacs.git / blobdiff