@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Programs, Building, Text, Top
@chapter Editing Programs
of a program.
* Program Indent:: Adjusting indentation to show the nesting.
* Parentheses:: Commands that operate on parentheses.
-* Comments:: Inserting, killing, and aligning comments.
+* Comments:: Inserting, killing, and aligning comments.
* 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.
+* 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.
@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.
+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
@cindex Modula2 mode
@cindex Prolog mode
@cindex Python mode
+@cindex Ruby mode
@cindex Simula mode
@cindex VHDL mode
@cindex M4 mode
@cindex PostScript mode
@cindex Conf mode
@cindex DNS mode
- The existing programming language major modes include Lisp, Scheme (a
-variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
-ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
-format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
-companion for font creation), Modula2, Objective-C, Octave, Pascal,
-Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL. An
-alternative mode for Perl is called CPerl mode. Modes are available for
-the scripting languages of the common GNU and Unix shells, VMS DCL, and
-MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for
-editing makefiles, DNS master files, and various sorts of configuration
-files.
+@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.
@kindex DEL @r{(programming modes)}
@findex c-electric-backspace
In most programming languages, indentation should vary from line to
line to illustrate the structure of the program. So the major modes
for programming languages arrange for @key{TAB} to update the
-indentation of the current line. They also rebind @key{DEL} to treat
-a tab as if it were the equivalent number of spaces; this lets you
-delete one column of indentation without worrying whether the
-whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a
-tab character before point, in these modes.
+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
@ref{Fortran}.
@end ifnottex
-
@cindex mode hook
@vindex c-mode-hook
@vindex lisp-mode-hook
@node Defuns
@section Top-Level Definitions, or Defuns
- In Emacs, a major definition at the top level in the buffer,
-something like a function, is called a @dfn{defun}. The name comes
-from Lisp, but in Emacs we use it for all languages.
+ In Emacs, a major definition at the top level in the buffer, such as
+a function, is called a @dfn{defun}. The name comes from Lisp, but in
+Emacs we use it for all languages.
@menu
* Left Margin Paren:: An open-paren or similar opening delimiter
@cindex open-parenthesis in leftmost column
@cindex ( in leftmost column
- Emacs assumes by default that any opening delimiter found at the
-left margin is the start of a top-level definition, or defun.
-Therefore, @strong{don't 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.
+ Many programming-language modes assume by default that any opening
+delimiter found at the left margin is the start of a top-level
+definition, or defun. Therefore, @strong{don't 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.
+
+ The convention speeds up many Emacs operations, which would
+otherwise have to scan back to the beginning of the buffer to analyze
+the syntax of the code.
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}).
+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
highlights confusing opening delimiters (those that ought to be
quoted) in bold red.
-If you need to override this convention, you can so by setting this
-user option:
+ If you need to override this convention, you can do so by setting
+this user option:
@defvar open-paren-in-column-0-is-defun-start
If this user option is set to @code{t} (the default), opening
outermost level.
@end defvar
- Usually, you shouldn't need to set
-@code{open-paren-in-column-0-is-defun-start} to @code{nil}. However,
-if your buffer contains parentheses or braces in column zero which
-don't start defuns and this confuses Emacs, it sometimes helps to set
-the option to @code{nil}. Be aware, though, that this will make
-scrolling and display in large buffers quite sluggish, and that
-parentheses and braces must be correctly matched throughout the buffer
-for it to work properly.
-
- In the earliest days, the original Emacs found defuns by moving
-upward a level of parentheses or braces until there were no more
-levels to go up. This always required scanning all the way back to
-the beginning of the buffer, even for a small function. To speed up
-the operation, we changed Emacs to assume that any opening delimiter
-at the left margin is the start of a defun. This heuristic is nearly
-always right, and avoids the need to scan back to the beginning of the
-buffer. However, now that modern computers are so powerful, this
-scanning is rarely slow enough to annoy, so we've provided a way to
-disable the heuristic.
+ Usually, you should leave this option at its default value of
+@code{t}. If your buffer contains parentheses or braces in column
+zero which don't start defuns, and it is somehow impractical to remove
+these parentheses or braces, it might be helpful to set the option to
+@code{nil}. Be aware that this might make scrolling and display in
+large buffers quite sluggish. Furthermore, the parentheses and braces
+must be correctly matched throughout the buffer for it to work
+properly.
@node Moving by Defuns
@subsection Moving by Defuns
@kindex C-M-h @r{(C mode)}
@findex c-mark-function
- To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})
-which puts point at the beginning and mark at the end of the current
-defun. This is the easiest way to get ready to kill the defun in
-order to move it to a different place in the file. If you use the
-command while point is between defuns, it uses the following defun.
-Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode
-when the mark is active, extends the end of the region to include one
-more defun each time.
+ To operate on the current defun, use @kbd{C-M-h}
+(@code{mark-defun}), which sets the mark at the end of the current
+defun and puts point at its beginning. @xref{Marking Objects}. 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. If you use the
+command while the mark is already active, it sets the mark but does
+not move point; furthermore, each successive use of @kbd{C-M-h}
+extends the end of the region to include one more 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
@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 is global; it applies to
-all buffers, both existing ones and those yet to be created. However,
-it takes effect only in certain major modes, those listed in the value
-of @code{which-func-modes}. If the value is @code{t}, then Which
-Function mode applies to all major modes that know how to support
-it---in other words, all the major modes that support Imenu.
+@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.
@node Program Indent
@section Indentation for Programs
@cindex indentation for programs
The best way to keep a program properly indented is to use Emacs to
-reindent it as you change it. Emacs has commands to indent properly
-either a single line, a specified number of lines, or all of the lines
-inside a single parenthetical grouping.
+reindent it as you change it. Emacs has commands to indent either a
+single line, a specified number of lines, or all of the lines inside a
+single parenthetical grouping.
@menu
-* Basic Indent:: Indenting a single line.
+* Basic Indent:: Indenting a single line.
* Multi-line Indent:: Commands to reindent many lines at once.
-* Lisp Indent:: Specifying how each Lisp function should be indented.
-* C Indent:: Extra features for indenting C and related modes.
-* Custom C Indent:: Controlling indentation style for C and related modes.
+* Lisp Indent:: Specifying how each Lisp function should be indented.
+* C Indent:: Extra features for indenting C and related modes.
+* Custom C Indent:: Controlling indentation style for C and related modes.
@end menu
@cindex pretty-printer
The basic indentation commands indent a single line according to the
usual conventions of the language you are editing.
-@need 1000
@table @kbd
@item @key{TAB}
Adjust indentation of current line.
@findex c-indent-command
@findex indent-line-function
@findex indent-for-tab-command
- The basic indentation command is @key{TAB}, which gives the current line
-the correct indentation as determined from the previous lines. The
-function that @key{TAB} runs depends on the major mode; it is
-@code{lisp-indent-line}
-in Lisp mode, @code{c-indent-command} in C mode, etc. These functions
-understand the syntax and conventions of different languages, but they all do
-conceptually the same job: @key{TAB} in any programming-language major mode
-inserts or deletes whitespace at the beginning of the current line,
-independent of where point is in the line. If point 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.
+ 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.
When entering lines of new code, use @kbd{C-j}
(@code{newline-and-indent}), which inserts a newline and then adjusts
indentation after it. (It also deletes any trailing whitespace which
-remains before the new newline.) Thus, @kbd{C-j} at the end of a line
-creates a blank line with appropriate indentation. In programming
-language modes, it is equivalent to @key{RET} @key{TAB}.
-
- @key{TAB} indents a line that starts within a parenthetical grouping
-under the preceding line within the grouping, or the text after the
-parenthesis. Therefore, if you manually give one of these lines a
-nonstandard indentation, the lines below will tend to follow it. This
-behavior is convenient in cases where you have overridden the standard
-result of @key{TAB} because you find it unaesthetic for a particular
-line.
-
- In some modes, an open-parenthesis, open-brace or other opening
-delimiter at the left margin is assumed by Emacs (including the
-indentation routines) to be the start of a function. This speeds up
-indentation commands. If you will be editing text which contains
-opening delimiters in column zero that aren't the beginning of a
-functions, even inside strings or comments, you must set
+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
-Paren}, for more information on this.
+Paren}.
- Normally, lines are indented with tabs and spaces. If you want Emacs
-to use spaces only, set @code{indent-tabs-mode} (@pxref{Just Spaces}).
+ 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
- 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.
+ 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:
@table @kbd
@item C-M-q
-Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}).
+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}
@kindex C-M-q
@findex indent-pp-sexp
- You can reindent the contents of a single parenthetical grouping by
-positioning point before the beginning of it and typing @kbd{C-M-q}
-(@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also
-bound to other suitable commands in other modes). The indentation of
-the line where the grouping starts is not changed; therefore this
-changes only the relative indentation within the grouping, not its
-overall indentation. To correct that as well, type @key{TAB} first.
-
- Another way to specify the range to be reindented is with the
-region. The command @kbd{C-M-\} (@code{indent-region}) applies
-@key{TAB} to every line whose first character is between point and
-mark.
+ 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
+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, you can type @kbd{C-u @key{TAB}} to
-reindent the whole grouping as a rigid unit. (This works in Lisp
-modes and C and related modes.) @key{TAB} with a numeric argument
-reindents the current line as usual, then reindents by the same amount
-all the lines in the parenthetical grouping starting on the current
-line. It is clever, though, and does not alter lines that start
-inside strings. Neither does it alter C preprocessor lines when in C
-mode, but it does reindent any continuation lines that may be attached
-to them.
+ 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
+@kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes,
+@key{TAB} with a numeric argument reindents the current line as usual,
+then reindents by the same amount all the lines in the parenthetical
+grouping starting on the current line. It is clever, though, and does
+not alter lines that start inside strings. Neither does it alter C
+preprocessor lines when in C mode, but it does reindent any
+continuation lines that may be attached to them.
@findex indent-code-rigidly
- You can also perform this operation on the region, using the command
-@kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the
-region sideways, like @code{indent-rigidly} does (@pxref{Indentation
-Commands}). It doesn't alter the indentation of lines that start
-inside a string, unless the region also starts inside that string.
-The prefix arg specifies the number of columns to indent.
+ The command @kbd{M-x indent-code-rigidly} rigidly shifts all the
+lines in the region sideways, like @code{indent-rigidly} does
+(@pxref{Indentation Commands}). It doesn't alter the indentation of
+lines that start inside a string, unless the region also starts inside
+that string. The prefix arg specifies the number of columns to
+indent.
@node Lisp Indent
@subsection Customizing Lisp Indentation
* 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.
+* Matching:: Insertion of a close-delimiter flashes matching open.
@end menu
@node Expressions
@kindex C-M-@key{SPC}
@findex mark-sexp
To set the region around the next balanced expression in the buffer,
-use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place
-that @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like
-@kbd{C-M-f}. In particular, a negative argument is useful for putting
-the mark at the beginning of the previous balanced expression. The
-alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. When you
-repeat this command, or use it in Transient Mark mode when the mark is
-active, it extends the end of the region by one sexp each time.
+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.
In languages that use infix operators, such as C, it is not possible
to recognize all balanced expressions as such because there can be
@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
+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.
+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.
+
@table @kbd
@item C-M-n
Move forward over a parenthetical group (@code{forward-list}).
@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.).
+@kbd{C-M-p} (@code{backward-list}) move forward or backward over one
+(or @var{n}) parenthetical groupings.
@kindex C-M-u
@findex backward-up-list
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.
+lots of time when there is no match. The default is 102400.
@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.
+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
@cindex indentation for comments
@cindex alignment for comments
- The comment commands in this table insert, kill and align comments.
-They are described in this section and following sections.
+ The commands in this table insert, kill and align comments:
@table @asis
@item @kbd{M-;}
different jobs relating to comments, depending on the situation where
you use it.
- If there is no comment already on the line, @kbd{M-;} inserts a new
-comment, aligned at a specific column called the @dfn{comment column}.
-The new comment begins with the string Emacs thinks comments should
-start with (the value of @code{comment-start}; see below). Point is
-after that string, so you can insert the text of the comment right
-away. If the major mode has specified a string to terminate comments,
-@kbd{M-;} inserts that after point, to keep the syntax valid.
-
- If the text of the line extends past the comment column, this
-command aligns the comment start string to a suitable boundary
-(usually, at least one space is inserted).
+ 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.
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
@code{comment-kill}. However, @code{comment-kill} is a valid command
in its own right, and you can bind it directly to a key if you wish.
- @kbd{M-;} does two other jobs when used with an active region in
-Transient Mark mode (@pxref{Transient Mark}). Then it either adds or
-removes comment delimiters on each line of the region. (If every line
-is a comment, it removes comment delimiters from each; otherwise, it
-adds comment delimiters to each.) If you are not using Transient Mark
-mode, then you should use the commands @code{comment-region} and
-@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}),
-or else enable Transient Mark mode momentarily (@pxref{Momentary Mark}).
-A prefix argument used in these circumstances specifies how many
-comment delimiters to add or how many to delete.
-
Some major modes have special rules for aligning certain kinds of
comments in certain contexts. For example, in Lisp code, comments which
start with two semicolons are indented as if they were lines of code,
(1+ x)) ; This line adds one.
@end example
- For C-like modes, you can configure the exact effect of @kbd{M-;}
-more flexibly than for most buffers by setting the variables
-@code{c-indent-comment-alist} and
+ For C-like modes, you can configure the exact effect of @kbd{M-;} by
+setting the variables @code{c-indent-comment-alist} and
@code{c-indent-comments-syntactically-p}. For example, on a line
ending in a closing brace, @kbd{M-;} puts the comment one space after
the brace rather than at @code{comment-column}. For full details see
-@ref{Comment Commands,,, ccmode, The CC Mode Manual}.
+@ref{Comment Commands,,, ccmode, The CC Mode Manual}.
@node Multi-Line Comments
@subsection Multiple Lines of Comments
@findex info-lookup-symbol
@findex info-lookup-file
@kindex C-h S
- For many major modes, that apply to languages that have
-documentation in Info, you can use @kbd{C-h S}
-(@code{info-lookup-symbol}) to view the Info documentation for a
-symbol used in the program. You specify the symbol with the
-minibuffer; the default is the symbol appearing in the buffer at
-point. For example, in C mode this looks for the symbol in the C
-Library Manual. The command only works if the appropriate manual's
-Info files are installed.
+ For major modes that apply to languages which have documentation in
+Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the
+Info documentation for a symbol used in the program. You specify the
+symbol with the minibuffer; the default is the symbol appearing in the
+buffer at point. For example, in C mode this looks for the symbol in
+the C Library Manual. The command only works if the appropriate
+manual's Info files are installed.
The major mode determines where to look for documentation for the
symbol---which Info files to look in, and which indices to search.
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.
+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
@section Completion for Symbol Names
@cindex completion (symbol names)
- In Emacs, completion is something you normally do in the minibuffer.
-But one kind of completion is available in all buffers: completion for
-symbol names.
+ 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.
@kindex M-TAB
The character @kbd{M-@key{TAB}} runs a command to complete the
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, and
-we recommend that you change any that get in the way of use of Emacs.
+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
of the programming language major modes in which you normally want
to use Glasses mode.
+@node Semantic
+@section Semantic
+@cindex Semantic package
+
+Semantic is a package that provides language-aware editing commands
+based on @code{source code parsers}. This section provides a brief
+description of Semantic;
+@ifnottex
+for full details, 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.
+@end iftex
+
+ Most of the ``language aware'' features in Emacs, such as font lock
+(@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.
+
+ 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.
+
+ When Semantic mode is enabled, Emacs automatically attempts to
+parses each file you visit. Currently, Semantic understands C, C++,
+Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer,
+the following commands are available:
+
+@table @kbd
+@item C-c , j
+@kindex C-c , j
+Prompt for the name of a function defined in the current file, and
+move point there (@code{semantic-complete-jump-local}).
+
+@item C-c , J
+@kindex C-c , J
+Prompt for the name of a function defined in any file Emacs has
+parsed, and move point there (@code{semantic-complete-jump}).
+
+@item C-c , @key{SPC}
+@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
+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.
+
+@item C-c , l
+@kindex C-c , l
+Display a list of the possible completions of the symbol at point, in
+another window (@code{semantic-analyze-possible-completions}).
+@end table
+
+@noindent
+In addition to the above commands, the Semantic package provides a
+variety of other ways to make use of parser information. For
+instance, you can use it to display a list of completions when Emacs
+is idle.
+@ifnottex
+@xref{Top, Semantic,, semantic, Semantic}, for details.
+@end ifnottex
+
@node Misc for Programs
@section Other Features Useful for Editing Programs
@table @kbd
@item C-c C-w
-@itemx M-x c-subword-mode
-@findex c-subword-mode
+@itemx M-x subword-mode
+@findex subword-mode
Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word
commands recognize upper case letters in
@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by
the flag @samp{/w} on the mode line after the mode name
-(e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in
+(e.g. @samp{C/law}). You can even use @kbd{M-x subword-mode} in
non-CC Mode buffers.
In the GNU project, we recommend using underscores to separate words
@item M-x hide-ifdef-mode
@findex hide-ifdef-mode
@cindex Hide-ifdef mode
+@vindex hide-ifdef-shadow
Hide-ifdef minor mode hides selected code within @samp{#if} and
-@samp{#ifdef} preprocessor blocks. See the documentation string of
-@code{hide-ifdef-mode} for more information.
+@samp{#ifdef} preprocessor blocks. If you change the variable
+@code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode
+``shadows'' preprocessor blocks by displaying them with a less
+prominent face, instead of hiding them entirely. See the
+documentation string of @code{hide-ifdef-mode} for more information.
@item M-x ff-find-related-file
@cindex related files
HCoop / bpt / emacs.git / blobdiff