+@c -*- coding: utf-8 -*-
@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Programs, Building, Text, Top
+@node Programs
@chapter Editing Programs
@cindex Lisp editing
@cindex C editing
* 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.
+* MixedCase Words:: Dealing with identifiersLikeThis.
* Semantic:: Suite of editing tools based on source code parsing.
+* Prettifying Symbols:: Display symbols as composed characters.
* Misc for Programs:: Other Emacs features useful for editing programs.
* C Modes:: Special commands of C, C++, Objective-C, Java,
IDL, Pike and AWK modes.
@cindex VHDL mode
@cindex M4 mode
@cindex Shell-script mode
-@cindex Delphi mode
+@cindex OPascal mode
@cindex PostScript mode
@cindex Conf mode
@cindex DNS mode
@cindex Javascript mode
Emacs has programming language modes for Lisp, Scheme, the
-Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi,
+Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++,
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
+(@TeX{}'s companion for font creation), Modula2, Object Pascal, 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.
For instance, entering C mode runs the hooks @code{prog-mode-hook} and
@code{c-mode-hook}. @xref{Hooks}, for information about hooks.
-@ifinfo
+@ifnottex
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
+@end ifnottex
+@iftex
The Emacs distribution contains Info manuals for the major modes for
-Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE. For
+Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE@. For
Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized Emacs Features}.
-@end ifnotinfo
+@end iftex
@node Defuns
@section Top-Level Definitions, or Defuns
@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}. 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.
+@kbd{M-x which-function-mode}. Which Function mode is a global minor
+mode. By default, it takes effect in all major modes major modes that
+know how to support it (i.e., all the major modes that support
+Imenu). You can restrict it to a specific list of major modes by
+changing the value of the variable @code{which-func-modes} from
+@code{t} (which means to support all available major modes) to a list
+of major mode names.
@node Program Indent
@section Indentation for Programs
@table @kbd
@item @key{TAB}
Adjust indentation of current line (@code{indent-for-tab-command}).
-@item C-j
+@item @key{RET}
Insert a newline, then adjust indentation of following line
-(@code{newline-and-indent}).
+(@code{newline}).
@end table
@kindex TAB @r{(programming modes)}
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
- 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.
+ The command @key{RET} (@code{newline}), which was documented in
+@ref{Inserting Text}, does the same as @key{C-j} 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
+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
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,
@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 (e.g.@: @samp{(}, @samp{[} or @samp{@{} in C),
+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.
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
-as in @samp{[x)}---a warning message is displayed in the echo area.
+delimiter, Emacs briefly indicates 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 as in
+@samp{[x)}---a warning message is displayed in the echo area.
@vindex blink-matching-paren
@vindex blink-matching-paren-distance
@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.
+disables it, but the default is @code{t} to enable it. Set it to
+@code{jump} to make indication work by momentarily moving the cursor
+to the matching opening delimiter.
@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-delay} says how many seconds to keep indicating
+the matching opening delimiter. This may be an integer or
+floating-point number; the default is 1.
@item
@code{blink-matching-paren-distance} specifies how many characters
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}.
+leaving point between the two. Conversely, when you insert a closing
+delimiter over an existing one, no inserting takes places and that
+position is simply skipped over. These variables control additional
+features of Electric Pair mode:
+
+@itemize @bullet
+@item
+@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
+default pairing logic balance out the number of opening and closing
+delimiters.
+
+@item
+@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
+backspacing between two adjacent delimiters also automatically delete
+the closing delimiter.
+
+@item
+@code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
+makes inserting inserting a newline between two adjacent pairs also
+automatically open and extra newline after point.
+
+@item
+@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
+mode to skip whitespace forward before deciding whether to skip over
+the closing delimiter.
+@end itemize
+
+To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.
@node Comments
@section Manipulating Comments
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
+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
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
+ 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
@cindex Eldoc mode
@findex eldoc-mode
Eldoc is a buffer-local minor mode that helps with looking up Lisp
-documention. When it is enabled, the echo area displays some useful
+documentation. 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
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
+@node MixedCase Words
+@section MixedCase Words
@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.
+ Some programming styles make use of mixed-case (or ``CamelCase'')
+symbols like @samp{unReadableSymbol}. (In the GNU project, we recommend
+using underscores to separate words within an identifier, rather than
+using case distinctions.) Emacs has various features to make it easier
+to deal with such symbols.
+
+@cindex Glasses mode
+@findex mode, Glasses
+ Glasses mode is a buffer-local minor mode that makes it easier to read
+such symbols, 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}}.
+@cindex Subword mode
+@findex subword-mode
+ Subword mode is another buffer-local minor mode. In subword mode,
+Emacs's word commands recognize upper case letters in
+@samp{StudlyCapsIdentifiers} as word boundaries. When Subword mode is
+enabled, the minor mode indicator @samp{,} appears in the mode line.
+See also the similar @code{superword-mode} (@pxref{Misc for Programs}).
+
@node Semantic
@section Semantic
@cindex Semantic package
@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++,
+parse each file you visit. Currently, Semantic understands C, C++,
Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer,
the following commands are available:
@xref{Top, Semantic,, semantic, Semantic}, for details.
@end ifnottex
+@node Prettifying Symbols
+@section Prettifying Symbols
+@cindex prettifying symbols
+@cindex symbol, prettifying
+
+@code{prettify-symbols-mode} and @code{global-prettify-symbols-mode}
+are two minor modes (@pxref{Minor Modes}) that can display specified
+symbols as composed characters. For instance, in Emacs Lisp mode
+(@pxref{Lisp Eval}), this mode will replace the string ``lambda'' with
+the Greek lambda character.
+
+@findex prettify-symbols-mode
+@vindex prettify-symbols-alist
+When Prettify Symbols mode and Font Lock mode (@pxref{Font Lock}) are
+enabled, symbols are prettified (displayed as composed characters)
+according to the rules in @code{prettify-symbols-alist}, which are
+locally defined by major modes (@pxref{Major Modes}) supporting
+prettifying. To add further customizations for a given major mode,
+you can modify @code{prettify-symbols-alist}. For example:
+
+@example
+(add-hook 'emacs-lisp-mode-hook
+ (lambda ()
+ (push '("<=" . ?≤) prettify-symbols-alist)))
+@end example
+
+@findex global-prettify-symbols-mode
+You can enable this mode locally in desired buffers, or use
+@code{global-prettify-symbols-mode} to enable it for all modes that
+support it.
+
@node Misc for Programs
@section Other Features Useful for Editing Programs
programming language major mode, indents the new lines which it
creates.
+@findex superword-mode
+ Superword mode is a buffer-local minor mode that causes editing and
+motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words.
+When Subword mode is enabled, the minor mode indicator
+@iftex
+@samp{@math{^2}}
+@end iftex
+@ifnottex
+@samp{²}
+@end ifnottex
+appears in the mode line. See also the similar @code{subword-mode}
+(@pxref{MixedCase Words}).
+
@findex electric-layout-mode
Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global
minor mode that automatically inserts newlines when you type certain
@subsection Other Commands for C Mode
@table @kbd
-@item C-c C-w
-@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 subword-mode} in
-non-CC Mode buffers.
-
-In the GNU project, we recommend using underscores to separate words
-within an identifier in C or C++, rather than using case distinctions.
-
@item M-x c-context-line-break
@findex c-context-line-break
This command inserts a line break and indents the new line in a manner
appropriate to the context. In normal code, it does the work of
-@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it
-additionally inserts a @samp{\} at the line break, and within comments
-it's like @kbd{M-j} (@code{c-indent-new-comment-line}).
+@key{RET} (@code{newline}), in a C preprocessor line it additionally
+inserts a @samp{\} at the line break, and within comments it's like
+@kbd{M-j} (@code{c-indent-new-comment-line}).
@code{c-context-line-break} isn't bound to a key by default, but it
needs a binding to be useful. The following code will bind it to
-@kbd{C-j}. We use @code{c-initialization-hook} here to make sure
+@kbd{RET}. We use @code{c-initialization-hook} here to make sure
the keymap is loaded before we try to change it.
@example
(defun my-bind-clb ()
- (define-key c-mode-base-map "\C-j"
+ (define-key c-mode-base-map "\C-m"
'c-context-line-break))
(add-hook 'c-initialization-hook 'my-bind-clb)
@end example
@table @kbd
@item @key{TAB}
@code{tab-to-tab-stop}.
+@c FIXME: Maybe this should be consistent with other programming modes.
@item C-j
Insert a newline and then indent using @code{tab-to-tab-stop}.
@item :