@cindex C editing
@cindex program editing
- Emacs provides many features to facilitate editing programs. Some
-of these features can
+ This chapter describes Emacs features for facilitating editing
+programs. Some of these features can:
@itemize @bullet
@item
Highlight program syntax (@pxref{Font Lock}).
@end itemize
- This chapter describes these features and many more.
-
@menu
* Program Modes:: Major modes for editing programs.
* Defuns:: Commands to operate on major top-level parts
* Glasses:: Making identifiersLikeThis more readable.
* Semantic:: Suite of editing tools based on source code parsing.
* Misc for Programs:: Other Emacs features useful for editing programs.
-* C Modes:: Special commands of C, C++, Objective-C,
- Java, and Pike modes.
+* C Modes:: Special commands of C, C++, Objective-C, Java,
+ IDL, Pike and AWK modes.
* Asm Mode:: Asm mode and its special features.
@ifnottex
* Fortran:: Fortran mode and its special features.
@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
+ Emacs has specialized major modes (@pxref{Major Modes}) for many
+programming languages. A programming language 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 or end 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}.
+to find the beginning or end of a function definition. It often has
+features for compiling and debugging programs as well. The major mode
+for each language is named after the language; for instance, the major
+mode for the C programming language is @code{c-mode}.
@cindex Perl mode
@cindex Icon mode
@cindex Conf mode
@cindex DNS mode
@cindex Javascript mode
- The existing programming language major modes include Lisp, Scheme
-(a variant of Lisp) and the Scheme-based DSSSL expression language,
-Ada, ASM, AWK, C, C++, Delphi (Object Pascal), Fortran, Icon, IDL
-(CORBA), IDLWAVE, Java, Javascript, Metafont (@TeX{}'s companion for
-font creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike,
-PostScript, Prolog, Python, Ruby, Simula, Tcl, and VHDL. An
-alternative mode for Perl is called CPerl mode. Modes are available
-for the scripting languages of the common GNU and Unix shells, VMS
-DCL, and MS-DOS/MS-Windows @samp{BAT} files. There are also major
-modes for editing makefiles, DNS master files, and various sorts of
-configuration files.
+ Emacs has programming language modes for Lisp, Scheme, the
+Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi,
+Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont
+(@TeX{}'s companion for font creation), Modula2, Objective-C, Octave,
+Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and
+VHDL. An alternative mode for Perl is called CPerl mode. Modes are
+also available for the scripting languages of the common GNU and Unix
+shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for
+makefiles, DNS master files, and various sorts of configuration files.
+
+ Ideally, Emacs should have a major mode for each programming
+language that you might want to edit. If it doesn't have a mode for
+your favorite language, the mode might be implemented in a package not
+distributed with Emacs (@pxref{Packages}); or you can contribute one.
@kindex DEL @r{(programming modes)}
@findex c-electric-backspace
+@findex backward-delete-char-untabify
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 (@pxref{Program Indent}). They also
-rebind @key{DEL} to treat a tab as if it were the equivalent number of
-spaces; this lets you delete one column of indentation without
-worrying whether the whitespace consists of spaces or tabs. Use
-@kbd{C-b C-d} to delete a tab character before point, in these modes.
-
- Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
-Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK
-(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
-(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran
-mode, see
-@iftex
-@ref{Fortran,,, emacs-xtra, Specialized Emacs Features}.
-@end iftex
-@ifnottex
-@ref{Fortran}.
-@end ifnottex
+line to illustrate the structure of the program. Therefore, in most
+programming language modes, typing @key{TAB} updates the indentation
+of the current line (@pxref{Program Indent}). Furthermore, @key{DEL}
+is usually bound to @code{backward-delete-char-untabify}, which
+deletes backward treating each tab as if it were the equivalent number
+of spaces, so that you can delete one column of indentation without
+worrying whether the whitespace consists of spaces or tabs.
@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}. The purpose of the mode hook is to give you a
-place to set up customizations for that major mode. @xref{Hooks}.
+ Entering a programming language mode runs the custom Lisp functions
+specified in the hook variable @code{prog-mode-hook}, followed by
+those specified in the mode's own mode hook (@pxref{Major Modes}).
+For instance, entering C mode runs the hooks @code{prog-mode-hook} and
+@code{c-mode-hook}. @xref{Hooks}, for information about hooks.
+
+@ifinfo
+ Separate manuals are available for the modes for Ada (@pxref{Top,,
+Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
+IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE
+(@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
+@end ifinfo
+@ifnotinfo
+ The Emacs distribution contains Info manuals for the major modes for
+Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE. For
+Fortran mode, see the ``Fortran'' section in the Info version of the
+Emacs manual, which is not included in this printed version.
+@end ifnotinfo
@node Defuns
@section Top-Level Definitions, or Defuns
@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.
+ Which Function mode is a global minor mode (@pxref{Minor Modes})
+which 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 either enable or disable Which Function mode, use the command
-@kbd{M-x which-function-mode}. This command applies to all buffers,
-both existing ones and those yet to be created. However, it takes
-effect only in certain major modes, those listed in the value of
-@code{which-func-modes}. If the value of @code{which-func-modes} is
-@code{t} rather than a list of modes, 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.
+@kbd{M-x which-function-mode}. Although Which Function mode is a
+global minor mode, it takes effect only in certain major modes: those
+listed in the variable @code{which-func-modes}. If the value of
+@code{which-func-modes} is @code{t} rather than a list of modes, 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
single line, a specified number of lines, or all of the lines inside a
single parenthetical grouping.
+ @xref{Indentation}, for general information about indentation. This
+section describes indentation features specific to programming
+language modes.
+
@menu
* Basic Indent:: Indenting a single line.
* Multi-line Indent:: Commands to reindent many lines at once.
@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.
+ Emacs also provides a Lisp pretty-printer in the @code{pp} package,
+which reformats Lisp objects with nice-looking indentation.
@node Basic Indent
@subsection Basic Program Indentation Commands
- 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.
+Adjust indentation of current line (@code{indent-for-tab-command}).
@item C-j
Insert a newline, then adjust indentation of following line
(@code{newline-and-indent}).
@findex c-indent-command
@findex indent-line-function
@findex indent-for-tab-command
- The basic indentation command is @key{TAB}. In any
-programming-language major mode, @key{TAB} gives the current line the
-correct indentation as determined from the previous lines. It does
-this by inserting or deleting whitespace at the beginning of the
-current 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.
-If the region is active (@pxref{Mark}), @key{TAB} indents every line
-within the region instead of just the current line. The function that
-@key{TAB} runs depends on the major mode; for instance, it is
-@code{c-indent-line-or-region} in C mode. Each function is aware of
-the syntax and conventions for its particular language.
-
- Use @kbd{C-q @key{TAB}} to insert a tab character at point.
-
-@kindex C-j
+ The basic indentation command is @key{TAB}
+(@code{indent-for-tab-command}), which was documented in
+@ref{Indentation}. In programming language modes, @key{TAB} indents
+the current line, based on the indentation and syntactic content of
+the preceding lines; if the region is active, @key{TAB} indents each
+line within the region, not just the current line.
+
+@kindex C-j @r{(indenting source code)}
@findex newline-and-indent
- When entering lines of new code, use @kbd{C-j}
-(@code{newline-and-indent}), which inserts a newline and then adjusts
-indentation after it. (It also deletes any trailing whitespace which
-remains before the new newline.) For instance, @kbd{C-j} at the end
-of a line creates a blank line with appropriate indentation. In
-programming language modes, it is equivalent to @key{RET} @key{TAB}.
-
- When Emacs indents a line that starts within a parenthetical
-grouping, it usually places the start of the line under the preceding
-line within the group, or under the text after the parenthesis. 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}
-indentation (e.g., for aesthetic purposes).
-
- Many programming-language modes assume that an open-parenthesis,
-open-brace or other opening delimiter at the left margin is the start
-of a function. This assumption speeds up indentation commands. If
-the text you are editing contains opening delimiters in column zero
-that aren't the beginning of a functions---even if these delimiters
-occur inside strings or comments---then you must set
-@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin
+ The command @kbd{C-j} (@code{newline-and-indent}), which was
+documented in @ref{Indentation Commands}, does the same as @key{RET}
+followed by @key{TAB}: it inserts a new line, then adjusts the line's
+indentation.
+
+ When indenting a line that starts within a parenthetical grouping,
+Emacs usually places the start of the line under the preceding line
+within the group, or under the text after the parenthesis. If you
+manually give one of these lines a nonstandard indentation (e.g.@: for
+aesthetic purposes), the lines below will follow it.
+
+ The indentation commands for most programming language modes assume
+that a open-parenthesis, open-brace or other opening delimiter at the
+left margin is the start of a function. If the code you are editing
+violates this assumption---even if the delimiters occur in strings or
+comments---you must set @code{open-paren-in-column-0-is-defun-start}
+to @code{nil} for indentation to work properly. @xref{Left Margin
Paren}.
- Normally, Emacs indents lines using an ``optimal'' mix of tab and
-space characters. If you want Emacs to use spaces only, set
-@code{indent-tabs-mode} (@pxref{Just Spaces}).
-
@node Multi-line Indent
@subsection Indenting Several Lines
Sometimes, you may want to reindent several lines of code at a time.
One way to do this is to use the mark; when the mark is active and the
-region is non-empty, @key{TAB} indents every line within the region.
-In addition, Emacs provides several other commands for indenting large
-chunks of code:
+region is non-empty, @key{TAB} indents every line in the region.
+Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
+every line in the region, whether or not the mark is active
+(@pxref{Indentation Commands}).
+
+ In addition, Emacs provides the following commands for indenting
+large chunks of code:
@table @kbd
@item C-M-q
Reindent all the lines within one parenthetical grouping.
-@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.
To reindent the contents of a single parenthetical grouping,
position point before the beginning of the grouping and type
@kbd{C-M-q}. This changes the relative indentation within the
-grouping, without affecting its overall indentation (i.e., the
+grouping, without affecting its overall indentation (i.e.@: the
indentation of the line where the grouping starts). The function that
@kbd{C-M-q} runs depends on the major mode; it is
@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
etc. To correct the overall indentation as well, type @key{TAB}
first.
- @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to the region.
-This is useful when Transient Mark mode is disabled (@pxref{Persistent
-Mark}), because in that case @key{TAB} does not act on the region.
-
@kindex C-u TAB
If you like the relative indentation within a grouping but not the
indentation of its first line, move point to that first line and type
@cindex @code{lisp-indent-function} property
You can override the standard pattern in various ways for individual
functions, according to the @code{lisp-indent-function} property of
-the function name. Normally you would use this for macro definitions
-and specify it using the @code{declare} construct (@pxref{Defining
-Macros,,, elisp, the Emacs Lisp Reference Manual}).
+the function name. This is normally done for macro definitions, using
+the @code{declare} construct. @xref{Defining Macros,,, elisp, the
+Emacs Lisp Reference Manual}.
@node C Indent
@subsection Commands for C Indentation
including how to override parts of an existing style and how to define
your own styles.
+ As an alternative to specifying a style, you can get Emacs to
+@dfn{guess} the style by scanning a code buffer which is already
+formatted. To do this, call @kbd{M-x c-guess} in your sample buffer.
+You can then apply this guessed style to other buffers with @kbd{M-x
+c-guess-install}. @xref{Guessing the Style,,, ccmode, the CC Mode
+Manual}, for more details about this mechanism.
+
@node Parentheses
@section Commands for Editing with Parentheses
@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.}.
+ Each programming language mode has its own definition of a
+@dfn{balanced expression}. Balanced expressions typically include
+individual symbols, numbers, and string constants, as well as pieces
+of code enclosed in a matching pair of delimiters. The following
+commands deal with balanced expressions (in Emacs, such expressions
+are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
+is used to refer to an expression in Lisp.}).
@table @kbd
@item C-M-f
Put mark after following expression (@code{mark-sexp}).
@end table
- Each programming language major mode customizes the definition of
-balanced expressions to suit that language. Balanced expressions
-typically include symbols, numbers, and string constants, as well as
-any pair of matching delimiters and their contents. Some languages
-have obscure forms of expression syntax that nobody has bothered to
-implement in Emacs.
-
-@cindex Control-Meta
- By convention, the keys for these commands are all Control-Meta
-characters. They usually act on expressions just as the corresponding
-Meta characters act on words. For instance, the command @kbd{C-M-b}
-moves backward over a balanced expression, just as @kbd{M-b} moves
-back over a word.
-
@kindex C-M-f
@kindex C-M-b
@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.
+is an opening delimiter (e.g.@: @samp{(}, @samp{[} or @samp{@{} in C),
+this command moves past the matching closing delimiter. If the
+character begins a symbol, string, or number, the command moves over
+that.
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.
-
- @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.
+balanced expression---like @kbd{C-M-f}, but in the reverse direction.
+If the expression is preceded by any prefix characters (single-quote,
+backquote and comma, in Lisp), the command moves back over them as
+well.
+
+ @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation
+the specified number of times; with a negative argument means to move
+in the opposite direction. In most modes, these two commands move
+across comments as if they were whitespace. Note that their keys,
+@kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
+which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
+@kbd{M-b}, which move by words (@pxref{Words}).
@cindex killing expressions
@kindex C-M-k
@findex kill-sexp
- Killing a whole balanced expression can be done with @kbd{C-M-k}
-(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f}
-would move over.
+ To kill a whole balanced expression, type @kbd{C-M-k}
+(@code{kill-sexp}). This kills the text that @kbd{C-M-f} would move
+over.
@cindex transposition of expressions
@kindex C-M-t
@findex transpose-sexps
- A somewhat random-sounding command which is nevertheless handy is
-@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous
-balanced expression across the next one. An argument serves as a
-repeat count, moving the previous expression over that many following
-ones. A negative argument drags the previous balanced expression
-backwards across those before it (thus canceling out the effect of
-@kbd{C-M-t} with a positive argument). An argument of zero, rather
-than doing nothing, transposes the balanced expressions ending at or
-after point and the mark.
+ @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
+previous balanced expression and the next one. It is analogous to the
+@kbd{C-t} command, which transposes characters (@pxref{Transpose}).
+An argument to @kbd{C-M-t} serves as a repeat count, moving the
+previous expression over that many following ones. A negative
+argument moves the previous balanced expression backwards across those
+before it. An argument of zero, rather than doing nothing, transposes
+the balanced expressions ending at or after point and the mark.
@kindex C-M-@@
@kindex C-M-@key{SPC}
@findex mark-sexp
- To set the region around the next balanced expression in the buffer,
-use @kbd{C-M-@key{SPC}} (@code{mark-sexp}), which sets mark at the
-same place that @kbd{C-M-f} would move to. @kbd{C-M-@key{SPC}} treats
-numeric arguments in the same way as @kbd{C-M-f}; in particular, a
-negative argument puts the mark at the beginning of the previous
-balanced expression. The alias @kbd{C-M-@@} is equivalent to
-@kbd{C-M-@key{SPC}}. While the mark is active, each successive use of
-@kbd{C-M-@key{SPC}} extends the region by shifting the mark by one
-sexp.
+ To operate on balanced expressions with a command which acts on the
+region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}). This sets the
+mark where @kbd{C-M-f} would move to. While the mark is active, each
+successive call to this command extends the region by shifting the
+mark by one expression. Positive or negative numeric arguments move
+the mark forward or backward by the specified number of expressions.
+The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
+@xref{Marking Objects}, for more information about this and related
+commands.
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.
+to recognize all balanced expressions 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.
+However, C mode recognizes @samp{(foo + bar)} as a single expression,
+because of the parentheses.
@node Moving by Parens
@subsection Moving in the Parenthesis Structure
@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). They ignore strings and comments
-(including any parentheses within them) and ignore parentheses quoted
-by an escape character. 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.
+ The following commands move over groupings delimited by parentheses
+(or whatever else serves as delimiters in the language you are working
+with). They ignore strings and comments, including any parentheses
+within them, and also ignore parentheses that are ``quoted'' with an
+escape character. These commands are mainly intended for editing
+programs, but can be useful for editing any text containing
+parentheses. They are referred to internally as ``list'' commands
+because in Lisp these groupings are lists.
-These commands assume that the starting point is not inside a string
-or a comment. Sometimes you can invoke them usefully from one of
-these places (for example, when you have a parenthesised clause in a
-comment) but this is unreliable.
+ These commands assume that the starting point is not inside a string
+or a comment. If you invoke them from inside a string or comment, the
+results are unreliable.
@table @kbd
@item C-M-n
argument specifies the number of levels to go down.
@node Matching
-@subsection Automatic Display Of Matching Parentheses
+@subsection Matching Parentheses
@cindex matching parentheses
@cindex parentheses, displaying matches
- 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
+ Emacs has a number of @dfn{parenthesis matching} features, which
+make it easy to see how and whether parentheses (or other delimiters)
+match up.
+
+ 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.
-
- If the opening delimiter and closing delimiter are mismatched---such
+If the opening delimiter and closing delimiter are mismatched---such
as in @samp{[x)}---a warning message is displayed in the echo area.
@vindex blink-matching-paren
@vindex blink-matching-paren-distance
@vindex blink-matching-delay
- Three variables control parenthesis match display:
+ Three variables control the display of matching parentheses:
- @code{blink-matching-paren} turns the feature on or off: @code{nil}
-disables it, but the default is @code{t} to enable match display.
+@itemize @bullet
+@item
+@code{blink-matching-paren} turns the feature on or off: @code{nil}
+disables it, but the default is @code{t} to enable it.
- @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
+@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. This may be an integer or floating-point number;
+the default is 1.
- @code{blink-matching-paren-distance} specifies how many characters
+@item
+@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 102400.
+is not found in that distance, Emacs stops scanning and nothing is
+displayed. The default is 102400.
+@end itemize
@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 before an opening delimiter or after a closing
-delimiter, both that delimiter and its opposite delimiter are
-highlighted. Use the command @kbd{M-x show-paren-mode} to enable or
-disable this mode.
-
- Show Paren mode uses the faces @code{show-paren-match} and
-@code{show-paren-mismatch} to highlight parentheses; you can customize
-them to control how highlighting looks. @xref{Face Customization}.
+ Show Paren mode, a global minor mode, provides a more powerful kind
+of automatic matching. Whenever point is before an opening delimiter
+or after a closing delimiter, both that delimiter and its opposite
+delimiter are highlighted. To toggle Show Paren mode, type @kbd{M-x
+show-paren-mode}.
+
+@cindex Electric Pair mode
+@cindex inserting matching parentheses
+@findex electric-pair-mode
+ Electric Pair mode, a global minor mode, provides a way to easily
+insert matching delimiters. Whenever you insert an opening delimiter,
+the matching closing delimiter is automatically inserted as well,
+leaving point between the two. To toggle Electric Pair mode, type
+@kbd{M-x electric-pair-mode}.
@node Comments
@section Manipulating Comments
also do spell checking on comments with Flyspell Prog mode
(@pxref{Spelling}).
+ Some major modes have special rules for indenting different kinds of
+comments. For example, in Lisp code, comments starting with two
+semicolons are indented as if they were lines of code, while those
+starting with three semicolons are supposed to be aligned to the left
+margin and are often used for sectioning purposes. Emacs understand
+these conventions; for instance, typing @key{TAB} on a comment line
+will indent the comment to the appropriate position.
+
+@example
+;; This function is just an example.
+;;; Here either two or three semicolons are appropriate.
+(defun foo (x)
+;;; And now, the first part of the function:
+ ;; The following line adds one.
+ (1+ x)) ; This line adds one.
+@end example
+
@menu
* Comment Commands:: Inserting, killing, and aligning comments.
* Multi-Line Comments:: Commands for adding and editing multi-line comments.
@cindex indentation for comments
@cindex alignment for comments
- The commands in this table insert, kill and align comments:
+ The following commands operate on comments:
@table @asis
@item @kbd{M-;}
-Insert or realign comment on current line; alternatively, comment or
-uncomment the region (@code{comment-dwim}).
+Insert or realign comment on current line; if the region is active,
+comment or uncomment the region instead (@code{comment-dwim}).
@item @kbd{C-u M-;}
Kill comment on current line (@code{comment-kill}).
@item @kbd{C-x ;}
(@code{comment-indent-new-line}). @xref{Multi-Line Comments}.
@item @kbd{M-x comment-region}
@itemx @kbd{C-c C-c} (in C-like modes)
-Add or remove comment delimiters on all the lines in the region.
+Add comment delimiters to all the lines in the region.
@end table
@kindex M-;
different jobs relating to comments, depending on the situation where
you use it.
- When a region is active, @kbd{M-;} either adds or removes comment
-delimiters on each line of the region. @xref{Mark}. If every line in
-the region is a comment, it removes comment delimiters from each;
-otherwise, it adds comment delimiters to each. You can also use the
-commands @code{comment-region} and @code{uncomment-region} to
-explicitly comment or uncomment the text in the region
-(@pxref{Multi-Line Comments}). If you supply a prefix argument to
-@kbd{M-;} when a region is active, that specifies how many comment
-delimiters to add or how many to delete.
-
- If the region is not active, @kbd{M-;} inserts a new comment if
-there is no comment already on the line. The new comment is normally
-aligned at a specific column called the @dfn{comment column}; if the
-text of the line extends past the comment column, @kbd{M-;} aligns the
-comment start string to a suitable boundary (usually, at least one
-space is inserted). The comment begins with the string Emacs thinks
-comments should start with (the value of @code{comment-start}; see
-below). Emacs places point after that string, so you can insert the
-text of the comment right away. If the major mode has specified a
-string to terminate comments, @kbd{M-;} inserts that string after
-point, to keep the syntax valid.
+ When a region is active (@pxref{Mark}), @kbd{M-;} either adds
+comment delimiters to the region, or removes them. If every line in
+the region is already a comment, it ``uncomments'' each of those lines
+by removing their comment delimiters. Otherwise, it adds comment
+delimiters to enclose the text in the region.
+
+ If you supply a prefix argument to @kbd{M-;} when a region is
+active, that specifies the number of comment delimiters to add or
+delete. A positive argument @var{n} adds @var{n} delimiters, while a
+negative argument @var{-n} removes @var{n} delimiters.
+
+ If the region is not active, and there is no existing comment on the
+current line, @kbd{M-;} adds a new comment to the current line. If
+the line is blank (i.e.@: empty or containing only whitespace
+characters), the comment is indented to the same position where
+@key{TAB} would indent to (@pxref{Basic Indent}). If the line is
+non-blank, the comment is placed after the last non-whitespace
+character on the line; normally, Emacs tries putting it at the column
+specified by the variable @code{comment-column} (@pxref{Options for
+Comments}), but if the line already extends past that column, it puts
+the comment at some suitable position, usually separated from the
+non-comment text by at least one space. In each case, Emacs places
+point after the comment's starting delimiter, so that you can start
+typing the comment text right away.
You can also use @kbd{M-;} to align an existing comment. If a line
already contains the comment-start string, @kbd{M-;} realigns it to
-the conventional alignment and moves point after it. (Exception:
-comments starting in column 0 are not moved.) Even when an existing
-comment is properly aligned, @kbd{M-;} is still useful for moving
-directly to the start of the text inside the comment.
+the conventional alignment and moves point after the comment's
+starting delimiter. As an exception, comments starting in column 0
+are not moved. Even when an existing comment is properly aligned,
+@kbd{M-;} is still useful for moving directly to the start of the
+comment text.
@findex comment-kill
@kindex C-u M-;
- @kbd{C-u M-;} kills any comment on the current line, along with the
-whitespace before it. To reinsert the comment on another line, move
-to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
-realign it.
-
- Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}
-(@code{comment-dwim}) with a prefix argument. That command is
-programmed so that when it receives a prefix argument it calls
-@code{comment-kill}. However, @code{comment-kill} is a valid command
-in its own right, and you can bind it directly to a key if you wish.
-
- Some major modes have special rules for aligning certain kinds of
-comments in certain contexts. For example, in Lisp code, comments which
-start with two semicolons are indented as if they were lines of code,
-instead of at the comment column. Comments which start with three
-semicolons are supposed to start at the left margin and are often used
-for sectioning purposes. Emacs understands
-these conventions by indenting a double-semicolon comment using @key{TAB},
-and by not changing the indentation of a triple-semicolon comment at all.
+ @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
+comment on the current line, along with the whitespace before it.
+Since the comment is saved to the kill ring, you can reinsert it on
+another line by moving to the end of that line, doing @kbd{C-y}, and
+then @kbd{M-;} to realign the command. You can achieve the same
+effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
+(@code{comment-dwim} actually calls @code{comment-kill} as a
+subroutine when it is given a prefix argument).
-@example
-;; This function is just an example.
-;;; Here either two or three semicolons are appropriate.
-(defun foo (x)
-;;; And now, the first part of the function:
- ;; The following line adds one.
- (1+ x)) ; This line adds one.
-@end example
+@kindex C-c C-c (C mode)
+@findex comment-region
+@findex uncomment-region
+ The command @kbd{M-x comment-region} is equivalent to calling
+@kbd{M-;} on an active region, except that it always acts on the
+region, even if the mark is inactive. In C mode and related modes,
+this command is bound to @kbd{C-c C-c}. The command @kbd{M-x
+uncomment-region} uncomments each line in the region; a numeric prefix
+argument specifies the number of comment delimiters to remove
+(negative arguments specify the number of comment to delimiters to
+add).
For C-like modes, you can configure the exact effect of @kbd{M-;} by
setting the variables @code{c-indent-comment-alist} and
@kindex M-j
@cindex blank lines in programs
@findex comment-indent-new-line
-
- If you are typing a comment and wish to continue it on another line,
-you can use the command @kbd{C-M-j} or @kbd{M-j}
-(@code{comment-indent-new-line}). If @code{comment-multi-line}
-(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new
-line within the comment. Otherwise it closes the comment and starts a
-new comment on a new line. When Auto Fill mode is on, going past the
-fill column while typing a comment causes the comment to be continued
-in just this fashion.
-
-@kindex C-c C-c (C mode)
-@findex comment-region
- To turn existing lines into comment lines, use the @kbd{M-x
-comment-region} command (or type @kbd{C-c C-c} in C-like modes). It
-adds comment delimiters to the lines that start in the region, thus
-commenting them out. With a negative argument, it does the
-opposite---it deletes comment delimiters from the lines in the region.
-
- With a positive argument, @code{comment-region} duplicates the last
-character of the comment start sequence it adds; the argument
-specifies how many copies of the character to insert. Thus, in Lisp
-mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line.
-Duplicating the comment delimiter is a way of calling attention to the
-comment. It can also affect how the comment is aligned or indented.
-In Lisp, for proper indentation, you should use an argument of two or
-three, if between defuns; if within a defun, it must be three.
+@vindex comment-multi-line
+ If you are typing a comment and wish to continue it to another line,
+type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}). This
+breaks the current line, and inserts the necessary comment delimiters
+and indentation to continue the comment.
+
+ For languages with closing comment delimiters (e.g.@: @samp{*/} in
+C), the exact behavior of @kbd{M-j} depends on the value of the
+variable @code{comment-multi-line}. If the value is @code{nil}, the
+command closes the comment on the old line and starts a new comment on
+the new line. Otherwise, it opens a new line within the current
+comment delimiters.
+
+ When Auto Fill mode is on, going past the fill column while typing a
+comment also continues the comment, in the same way as an explicit
+invocation of @kbd{M-j}.
+
+ To turn existing lines into comment lines, use @kbd{M-;} with the
+region active, or use @kbd{M-x comment-region}
+@ifinfo
+(@pxref{Comment Commands}).
+@end ifinfo
+@ifnotinfo
+as described in the preceding section.
+@end ifnotinfo
You can configure C Mode such that when you type a @samp{/} at the
start of a line in a multi-line block comment, this closes the
@vindex comment-column
@kindex C-x ;
@findex comment-set-column
- The @dfn{comment column}, the column at which Emacs tries to place
-comments, is stored in the variable @code{comment-column}. You can
-set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
-(@code{comment-set-column}) sets the comment column to the column
-point is at. @kbd{C-u C-x ;} sets the comment column to match the
-last comment before point in the buffer, and then does a @kbd{M-;} to
-align the current line's comment under the previous one.
-
- The variable @code{comment-column} is per-buffer: setting the variable
-in the normal fashion affects only the current buffer, but there is a
-default value which you can change with @code{setq-default}.
-@xref{Locals}. Many major modes initialize this variable for the
-current buffer.
+ As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
+adds a comment to a line, it tries to place the comment at the column
+specified by the buffer-local variable @code{comment-column}. You can
+set either the local value or the default value of this buffer-local
+variable in the usual way (@pxref{Locals}). Alternatively, you can
+type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
+@code{comment-column} in the current buffer to the column where point
+is currently located. @kbd{C-u C-x ;} sets the comment column to
+match the last comment before point in the buffer, and then does a
+@kbd{M-;} to align the current line's comment under the previous one.
@vindex comment-start-skip
The comment commands recognize comments based on the regular
than the comment starting delimiter in the strictest sense of the word;
for example, in C mode the value of the variable is
@c This stops M-q from breaking the line inside that @code.
-@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces
-after the @samp{/*} itself, and accepts C++ style comments also.
-(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
-the string, which is needed to deny the first star its special meaning
-in regexp syntax. @xref{Regexp Backslash}.)
+@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
+spaces after the @samp{/*} itself, and accepts C++ style comments
+also. (Note that @samp{\\} is needed in Lisp syntax to include a
+@samp{\} in the string, which is needed to deny the first star its
+special meaning in regexp syntax. @xref{Regexp Backslash}.)
@vindex comment-start
@vindex comment-end
When a comment command makes a new comment, it inserts the value of
-@code{comment-start} to begin it. The value of @code{comment-end} is
-inserted after point, so that it will follow the text that you will
-insert into the comment. When @code{comment-end} is non-empty, it
-should start with a space. For example, in C mode,
-@code{comment-start} has the value @w{@code{"/* "}} and
-@code{comment-end} has the value @w{@code{" */"}}.
+@code{comment-start} as an opening comment delimiter. It also inserts
+the value of @code{comment-end} after point, as a closing comment
+delimiter. For example, in Lisp mode, @code{comment-start} is
+@samp{";"} and @code{comment-end} is @code{""} (the empty string). In
+C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
+@code{" */"}.
@vindex comment-padding
- The variable @code{comment-padding} specifies how many spaces
-@code{comment-region} should insert on each line between the comment
-delimiter and the line's original text. The default is 1, to insert
-one space. @code{nil} means 0. Alternatively, @code{comment-padding}
-can hold the actual string to insert.
+ The variable @code{comment-padding} specifies a string that the
+commenting commands should insert between the comment delimiter(s) and
+the comment text. The default, @samp{" "}, specifies a single space.
+Alternatively, the value can be a number, which specifies that number
+of spaces, or @code{nil}, which means no spaces at all.
-@vindex comment-multi-line
- The variable @code{comment-multi-line} controls how @kbd{C-M-j}
-(@code{indent-new-comment-line}) behaves when used inside a comment.
-Specifically, when @code{comment-multi-line} is @code{nil}, the
-command inserts a comment terminator, begins a new line, and finally
-inserts a comment starter. Otherwise it does not insert the
-terminator and starter, so it effectively continues the current
-comment across multiple lines. In languages that allow multi-line
-comments, the choice of value for this variable is a matter of taste.
-The default for this variable depends on the major mode.
+ The variable @code{comment-multi-line} controls how @kbd{M-j} and
+Auto Fill mode continue comments over multiple lines.
+@xref{Multi-Line Comments}.
@vindex comment-indent-function
The variable @code{comment-indent-function} should contain a function
@node Man Page
@subsection Man Page Lookup
-@cindex manual page
+@cindex man page
On Unix, the main form of on-line documentation was the @dfn{manual
page} or @dfn{man page}. In the GNU operating system, we aim to
replace man pages with better-organized manuals that you can browse
@findex manual-entry
You can read the man page for an operating system command, library
-function, or system call, with the @kbd{M-x man} command. It
-runs the @code{man} program to format the man page; if the system
-permits, it runs @code{man} asynchronously, so that you can keep on
-editing while the page is being formatted. (On MS-DOS and MS-Windows
-3, you cannot edit while Emacs waits for @code{man} to finish.) The
-result goes in a buffer named @samp{*Man @var{topic}*}. These buffers
-use a special major mode, Man mode, that facilitates scrolling and
-jumping to other manual pages. For details, type @kbd{C-h m} while in
-a man page buffer.
+function, or system call, with the @kbd{M-x man} command. This
+prompts for a topic, with completion (@pxref{Completion}), and runs
+the @command{man} program to format the corresponding man page. If
+the system permits, it runs @command{man} asynchronously, so that you
+can keep on editing while the page is being formatted. 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
+mode buffer.
@cindex sections of manual pages
Each man page belongs to one of ten or more @dfn{sections}, each
-named by a digit or by a digit and a letter. Sometimes there are
-multiple man pages with the same name in different sections. To read
-a man page from a specific section, type
-@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}}
-when @kbd{M-x manual-entry} prompts for the topic. For example, to
-read the man page for the C library function @code{chmod} (as opposed
-to a command of the same name), type @kbd{M-x manual-entry @key{RET}
-chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in
-section @samp{2}.)
+named by a digit or by a digit and a letter. 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, the man page for the C library function
+@code{chmod} is in section 2, but there is a shell command of the same
+name, whose man page is in section 1; to view the former, type
+@kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}.
@vindex Man-switches
- If you do not specify a section, the results depend on how the
-@code{man} program works on your system. Some of them display only
-the first man page they find. Others display all man pages that have
-the specified name, so you can move between them with the @kbd{M-n}
-and @kbd{M-p} keys@footnote{On some systems, the @code{man} program
-accepts a @samp{-a} command-line option which tells it to display all
-the man pages for the specified topic. If you want this behavior, you
-can add this option to the value of the variable @code{Man-switches}.}.
-The mode line shows how many manual pages are present in the Man buffer.
-
-@vindex Man-fontify-manpage-flag
- By default, Emacs highlights the text in man pages. For a long man
-page, highlighting can take substantial time. You can turn off
-highlighting of man pages by setting the variable
-@code{Man-fontify-manpage-flag} to @code{nil}.
-
-@findex Man-fontify-manpage
- If you insert the text of a man page into an Emacs buffer in some
-other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
-perform the same conversions that @kbd{M-x manual-entry} does.
+@kindex M-n @r{(Man mode)}
+@kindex M-p @r{(Man mode)}
+ If you do not specify a section, @kbd{M-x man} normally displays
+only the first man page found. 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. To make use of
+this, change the value of the variable @code{Man-switches} to
+@samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and
+@kbd{M-p} to switch between man pages in different sections. The mode
+line shows how many manual pages are available.
@findex woman
@cindex manual pages, on MS-DOS/MS-Windows
An alternative way of reading manual pages is the @kbd{M-x woman}
-command@footnote{The name of the command, @code{woman}, is an acronym
-for ``w/o (without) man,'' since it doesn't use the @code{man}
-program.}. Unlike @kbd{M-x man}, it does not run any external
-programs to format and display the man pages; instead it does the job
-in Emacs Lisp, so it works on systems such as MS-Windows, where the
-@code{man} program (and other programs it uses) are not generally
-available.
-
- @kbd{M-x woman} prompts for a name of a manual page, and provides
-completion based on the list of manual pages that are installed on
-your machine; the list of available manual pages is computed
-automatically the first time you invoke @code{woman}. The word at
-point in the current buffer is used to suggest the default for the
-name of the manual page.
-
- With a numeric argument, @kbd{M-x woman} recomputes the list of the
-manual pages used for completion. This is useful if you add or delete
-manual pages.
+command. Unlike @kbd{M-x man}, it does not run any external programs
+to format and display the man pages; the formatting is done by Emacs,
+so it works on systems such as MS-Windows where the @command{man}
+program may be unavailable. It prompts for a man page, and displays
+it in a buffer named @samp{*WoMan @var{section} @var{topic}}.
+
+ @kbd{M-x woman} computes the completion list for manpages the first
+time you invoke the command. With a numeric argument, it recomputes
+this list; this is useful if you add or delete manual pages.
If you type a name of a manual page and @kbd{M-x woman} finds that
several manual pages by the same name exist in different sections, it
them.
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}.
+@ifinfo
+@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
+WoMan Manual}.
+@end ifinfo
+@ifnotinfo
+the WoMan Info manual, which is distributed with Emacs.
+@end ifnotinfo
@node Lisp Doc
@subsection Emacs Lisp Documentation Lookup
- 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.
+ When editing Emacs Lisp code, you can use the commands @kbd{C-h f}
+(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable})
+to view the built-in documentation for the Lisp functions and
+variables that you want to use. @xref{Name Help}.
@cindex Eldoc mode
@findex eldoc-mode
- A more automatic but less powerful method is Eldoc mode. This minor
-mode constantly displays in the echo area the argument list for the
-function being called at point. (In other words, it finds the
-function call that point is contained in, and displays the argument
-list of that function.) If point is over a documented variable, it
-shows the first line of the variable's docstring. Eldoc mode applies
-in Emacs Lisp and Lisp Interaction modes, and perhaps a few others
-that provide special support for looking up doc strings. Use the
-command @kbd{M-x eldoc-mode} to enable or disable this feature.
+ Eldoc is a buffer-local minor mode that helps with looking up Lisp
+documention. When it is enabled, the echo area displays some useful
+information whenever there is a Lisp function or variable at point;
+for a function, it shows the argument list, and for a variable it
+shows the first line of the variable's documentation string. To
+toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used
+with the Emacs Lisp and Lisp Interaction major modes.
@node Hideshow
@section Hideshow minor mode
+@cindex Hideshow mode
+@cindex mode, Hideshow
@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.
+ Hideshow mode is a buffer-local minor mode that allows you to
+selectively display portions of a program, which are referred to as
+@dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode
+(@pxref{Minor Modes}).
+
+ When you use Hideshow mode to hide a block, the block disappears
+from the screen, to be replaced by an ellipsis (three periods in a
+row). Just what constitutes a block depends on the major mode. In C
+mode and related modes, blocks are delimited by braces, while in Lisp
+mode they are delimited by parentheses. Multi-line comments also
+count as blocks.
- 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.
+ Hideshow mode provides the following commands:
@findex hs-hide-all
@findex hs-hide-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}).
+Toggle hiding for 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}).
+Show all blocks 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}).
@vindex hs-hide-comments-when-hiding-all
@vindex hs-isearch-open
@vindex hs-special-modes-alist
- These variables exist for customizing Hideshow mode.
+ These variables can be used to customize Hideshow mode:
@table @code
@item hs-hide-comments-when-hiding-all
-Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
+If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides
+comments too.
@item hs-isearch-open
-Specifies what kind of hidden blocks incremental search should make
-visible. The value should be one of these four symbols:
-
-@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
-
-@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.
+This variable specifies the conditions under which incremental search
+should unhide a hidden block when matching text occurs within the
+block. Its value should be either @code{code} (unhide only code
+blocks), @code{comment} (unhide only comments), @code{t} (unhide both
+code blocks and comments), or @code{nil} (unhide neither code blocks
+nor comments). The default value is @code{code}.
@end table
@node Symbol Completion
@section Completion for Symbol Names
@cindex completion (symbol names)
- In Emacs, completion is something you normally do in the minibuffer
-(@pxref{Completion}). But one kind of completion is available in all
-buffers: completion for symbol names.
+ Completion is normally done in the minibuffer (@pxref{Completion}),
+but you can also complete symbol names in ordinary Emacs buffers.
@kindex M-TAB
- The character @kbd{M-@key{TAB}} runs a command to complete the
-partial symbol before point against the set of meaningful symbol
-names. This command inserts at point any additional characters that
-it can determine from the partial name.
-
- If your window manager defines @kbd{M-@key{TAB}} to switch windows,
-you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead.
-However, most window managers let you customize these shortcuts, so
-you can change any that interfere with the way you use Emacs.
-
- 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.
+@kindex C-M-i
+ In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}}
+to complete the partial symbol before point. On graphical displays,
+the @kbd{M-@key{TAB}} key is usually reserved by the window manager
+for switching graphical windows, so you should type @kbd{C-M-i} or
+@kbd{@key{ESC} @key{TAB}} instead.
@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.
+ In-buffer symbol completion generates its completion list in a
+number of different ways. If Semantic mode is enabled, Emacs tries to
+use the Semantic parser data for completion (@pxref{Semantic}). If
+Semantic mode is not enabled or it fails at performing completion,
+Emacs normally tries to complete using a tags table (@pxref{Tags}).
@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 Emacs Lisp mode, completion is performed using the function,
+variable, and property names defined in the current Emacs session. If
+there is an open parenthesis immediately before the beginning of the
+partial symbol, only symbols with function definitions are considered.
+
+ In all other respects, in-buffer symbol completion behaves like
+minibuffer completion. For instance, if Emacs cannot complete to a
+unique symbol, it displays a list of completion alternatives in
+another window. @xref{Completion}.
In Text mode and related modes, @kbd{M-@key{TAB}} completes words
based on the spell-checker's dictionary. @xref{Spelling}.
@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 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.
+@cindex camel case
+@findex mode, Glasses
+
+ Glasses mode is a buffer-local minor mode that makes it easier to
+read mixed-case (or ``CamelCase'') symbols like
+@samp{unReadableSymbol}, by altering how they are displayed. By
+default, it displays extra underscores between each lower-case letter
+and the following capital letter. This does not alter the buffer
+text, only how it is displayed.
+
+ To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
+Modes}). When Glasses mode is enabled, the minor mode indicator
+@samp{o^o} appears in the mode line. For more information about
+Glasses mode, type @kbd{C-h P glasses @key{RET}}.
@node Semantic
@section Semantic
Semantic is a package that provides language-aware editing commands
based on @code{source code parsers}. This section provides a brief
-description of Semantic;
+description of Semantic; for full details,
@ifnottex
-for full details, see @ref{Top, Semantic,, semantic, Semantic}.
+see @ref{Top, Semantic,, semantic, Semantic}.
@end ifnottex
@iftex
-for full details, type @kbd{C-h i} (@code{info}) and then select the
-Semantic manual.
+see the Semantic Info manual, which is distributed with Emacs.
@end iftex
- Most of the ``language aware'' features in Emacs, such as font lock
-(@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular
+ Most of the ``language aware'' features in Emacs, such as Font Lock
+mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular
expressions and syntax tables.} that usually give good results but are
never completely exact. In contrast, the parsers used by Semantic
have an exact understanding of programming language syntax. This
allows Semantic to provide search, navigation, and completion commands
that are powerful and precise.
+@cindex Semantic mode
+@cindex mode, Semantic
To begin using Semantic, type @kbd{M-x semantic-mode} or click on
the menu item named @samp{Source Code Parsers (Semantic)} in the
@samp{Tools} menu. This enables Semantic mode, a global minor mode.
@kindex C-c , @key{SPC}
Display a list of possible completions for the symbol at point
(@code{semantic-complete-analyze-inline}). This also activates a set
-of special keybindings for choosing a completion: @key{RET} accepts
+of special key bindings for choosing a completion: @key{RET} accepts
the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible
completions, @key{TAB} completes as far as possible and then cycles,
and @kbd{C-g} or any other key aborts completion.
@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.
+ Some 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.
-
- 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}).
-
+(@pxref{Words}), while sentences can be found in strings and comments
+(@pxref{Sentences}). As for paragraphs, they are defined in most
+programming language modes to begin and end at blank lines
+(@pxref{Paragraphs}). Therefore, 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.
+
+ Apart from Hideshow mode (@pxref{Hideshow}), another way to
+selectively display parts of a program is to use the selective display
+feature (@pxref{Selective Display}). Programming modes often also
+support Outline minor mode (@pxref{Outline Mode}), which can be used
+with the Foldout package (@pxref{Foldout}).
+
+@ifinfo
The ``automatic typing'' features may be useful for writing programs.
@xref{Top,,Autotyping, autotype, Autotyping}.
+@end ifinfo
@node C Modes
@section C and Related Modes
This section gives a brief description of the special features
available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
-(These are called ``C mode and related modes.'') @xref{Top, , CC Mode,
-ccmode, CC Mode}, for a more extensive description of these modes
-and their special features.
+(These are called ``C mode and related modes.'')
+@ifinfo
+@xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
+@end ifinfo
+@ifnotinfo
+For more details, see the CC mode Info manual, which is distributed
+with Emacs.
+@end ifnotinfo
@menu
* Motion in C:: Commands to move by C statements, etc.
related modes.
@table @code
-@item M-x c-beginning-of-defun
-@itemx M-x c-end-of-defun
+@item C-M-a
+@itemx C-M-e
@findex c-beginning-of-defun
@findex c-end-of-defun
Move point to the beginning or end of the current function or
-top-level definition. These are found by searching for the least
+top-level definition. In languages with enclosing scopes (such as
+C++'s classes) the @dfn{current function} is the immediate one,
+possibly inside a scope. Otherwise it is the one defined by the least
enclosing braces. (By contrast, @code{beginning-of-defun} and
-@code{end-of-defun} search for braces in column zero.) If you are
-editing code where the opening brace of a function isn't placed in
-column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to
-these commands. @xref{Moving by Defuns}.
+@code{end-of-defun} search for braces in column zero.) @xref{Moving
+by Defuns}.
@item C-c C-u
@kindex C-c C-u @r{(C mode)}
HCoop / bpt / emacs.git / blobdiff