@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Modes
@chapter Major and Minor Modes
in some way. The hook's documentation says how the functions are
called. You can use @code{add-hook} to add a function to an abnormal
hook, but you must write the function to follow the hook's calling
-convention.
+convention. By convention, abnormal hook names end in @samp{-functions}.
- By convention, abnormal hook names end in @samp{-functions} or
-@samp{-hooks}. If the variable's name ends in @samp{-function}, then
-its value is just a single function, not a list of functions.
+@cindex single-function hook
+If the variable's name ends in @samp{-function}, then its value is
+just a single function, not a list of functions. @code{add-hook} cannot be
+used to modify such a @emph{single function hook}, and you have to use
+@code{add-function} instead (@pxref{Advising Functions}).
@menu
* Running Hooks:: How to run a hook.
@code{nil}.
@end defun
-@defmac with-wrapper-hook hook args &rest body
-This macro runs the abnormal hook @code{hook} as a series of nested
-``wrapper functions'' around the @var{body} forms. The effect is
-similar to nested @code{around} advices (@pxref{Around-Advice}).
-
-Each hook function should accept an argument list consisting of a function
-@var{fun}, followed by the additional arguments listed in @var{args}.
-The first hook function is passed a function @var{fun} that, if it is
-called with arguments @var{args}, performs @var{body} (i.e., the default
-operation). The @var{fun} passed to each successive hook function is
-constructed from all the preceding hook functions (and @var{body}); if
-this @var{fun} is called with arguments @var{args}, it does what the
-@code{with-wrapper-hook} call would if the preceding hook functions were
-the only ones in @var{hook}.
-
-Each hook function may call its @var{fun} argument as many times as it
-wishes, including never. In that case, such a hook function acts to
-replace the default definition altogether, and any preceding hook
-functions. Of course, a subsequent hook function may do the same thing.
-
-Each hook function definition is used to construct the @var{fun} passed
-to the next hook function in @var{hook}, if any. The last or
-``outermost'' @var{fun} is called once to produce the overall effect.
-
-When might you want to use a wrapper hook? The function
-@code{filter-buffer-substring} illustrates a common case. There is a
-basic functionality, performed by @var{body}---in this case, to extract
-a buffer-substring. Then any number of hook functions can act in
-sequence to modify that string, before returning the final result.
-A wrapper-hook also allows for a hook function to completely replace the
-default definition (by not calling @var{fun}).
-@end defmac
-
-@defun run-hook-wrapped hook wrap-function &rest args
-This function is similar to @code{run-hook-with-args-until-success}.
-Like that function, it runs the functions on the abnormal hook
-@code{hook}, stopping at the first one that returns non-@code{nil}.
-Instead of calling the hook functions directly, though, it actually
-calls @code{wrap-function} with arguments @code{fun} and @code{args}.
-@end defun
-
@node Setting Hooks
@subsection Setting Hooks
should not be applied to the containing tar file. Similarly, a tiff
image file might just happen to contain a first line that seems to
match the @w{@samp{-*-}} pattern. For these reasons, both these file
-extensions are members of the list @var{inhibit-local-variables-regexps}.
+extensions are members of the list @code{inhibit-local-variables-regexps}.
Add patterns to this list to prevent Emacs searching them for local
variables of any kind (not just mode specifiers).
@defvar interpreter-mode-alist
This variable specifies major modes to use for scripts that specify a
command interpreter in a @samp{#!} line. Its value is an alist with
-elements of the form @code{(@var{interpreter} . @var{mode})}; for
-example, @code{("perl" . perl-mode)} is one element present by
-default. The element says to use mode @var{mode} if the file
-specifies an interpreter which matches @var{interpreter}.
+elements of the form @code{(@var{regexp} . @var{mode})}; this says to
+use mode @var{mode} if the file specifies an interpreter which matches
+@code{\\`@var{regexp}\\'}. For example, one of the default elements
+is @code{("python[0-9.]*" . python-mode)}.
@end defvar
@defvar magic-mode-alist
retrieve the documentation strings of the major and minor mode
commands (@pxref{Accessing Documentation}).
-If called from Lisp with a non-nil @var{buffer} argument, this
+If called from Lisp with a non-@code{nil} @var{buffer} argument, this
function displays the documentation for that buffer's major and minor
modes, rather than those of the current buffer.
@end deffn
Apart from Fundamental mode, there are three major modes that other
major modes commonly derive from: Text mode, Prog mode, and Special
-mode. While Text mode is useful in its own right (e.g. for editing
+mode. While Text mode is useful in its own right (e.g., for editing
files ending in @file{.txt}), Prog mode and Special mode exist mainly to
let other modes derive from them.
As far as possible, new major modes should be derived, either directly
or indirectly, from one of these three modes. One reason is that this
allows users to customize a single mode hook
-(e.g. @code{prog-mode-hook}) for an entire family of relevant modes
-(e.g. all programming language modes).
+(e.g., @code{prog-mode-hook}) for an entire family of relevant modes
+(e.g., all programming language modes).
@deffn Command text-mode
Text mode is a major mode for editing human languages. It defines the
of @code{special} (@pxref{Major Mode Conventions}).
Special mode sets the buffer to read-only. Its keymap defines several
-common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for
-@code{kill-this-buffer}, and @kbd{g} for @code{revert-buffer}
-(@pxref{Reverting}).
+common bindings, including @kbd{q} for @code{quit-window} and @kbd{g}
+for @code{revert-buffer} (@pxref{Reverting}).
An example of a major mode derived from Special mode is Buffer Menu
mode, which is used by the @file{*Buffer List*} buffer. @xref{List
@cindex Tabulated List mode
Tabulated List mode is a major mode for displaying tabulated data,
-i.e.@: data consisting of @dfn{entries}, each entry occupying one row of
+i.e., data consisting of @dfn{entries}, each entry occupying one row of
text with its contents divided into columns. Tabulated List mode
provides facilities for pretty-printing rows and columns, and sorting
the rows according to the values in each column. It is derived from
line.
The derived mode should also define a @dfn{listing command}. This,
-not the mode command, is what the user calls (e.g.@: @kbd{M-x
+not the mode command, is what the user calls (e.g., @kbd{M-x
list-processes}). The listing command should create or switch to a
buffer, turn on the derived mode, specify the tabulated data, and
finally call @code{tabulated-list-print} to populate the buffer.
@cindex mode variable
Define a variable whose name ends in @samp{-mode}. We call this the
@dfn{mode variable}. The minor mode command should set this variable.
-The value will be @code{nil} is the mode is disabled, and non-@code{nil}
+The value will be @code{nil} if the mode is disabled, and non-@code{nil}
if the mode is enabled. The variable should be buffer-local if the
minor mode is buffer-local.
The mode command should accept one optional argument. If called
interactively with no prefix argument, it should toggle the mode
-(i.e.@: enable if it is disabled, and disable if it is enabled). If
+(i.e., enable if it is disabled, and disable if it is enabled). If
called interactively with a prefix argument, it should enable the mode
if the argument is positive and disable it otherwise.
-If the mode command is called from Lisp (i.e.@: non-interactively), it
+If the mode command is called from Lisp (i.e., non-interactively), it
should enable the mode if the argument is omitted or @code{nil}; it
should toggle the mode if the argument is the symbol @code{toggle};
otherwise it should treat the argument in the same way as for an
own definition of @code{self-insert-command} for the standard one. The
editor command loop handles this function specially.)
-The key sequences bound in a minor mode should consist of @kbd{C-c}
-followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other
-punctuation characters are reserved for major modes.)
+Minor modes may bind commands to key sequences consisting of @kbd{C-c}
+followed by a punctuation character. However, sequences consisting of
+@kbd{C-c} followed by one of @kbd{@{@}<>:;}, or a control character or
+digit, are reserved for major modes. Also, @kbd{C-c @var{letter}} is
+reserved for users. @xref{Key Binding Conventions}.
@node Defining Minor Modes
@subsection Defining Minor Modes
disables it. From Lisp, an argument of @code{toggle} toggles the mode,
whereas an omitted or @code{nil} argument enables the mode.
This makes it easy to enable the minor mode in a major mode hook, for example.
-If @var{doc} is nil, the macro supplies a default documentation string
+If @var{doc} is @code{nil}, the macro supplies a default documentation string
explaining the above.
By default, it also defines a variable named @var{mode}, which is set to
defined, and any @var{init-value} argument is unused. @var{place}
can be a different named variable (which you must define yourself), or
anything that can be used with the @code{setf} function
-(@pxref{Generalized Variables,,, cl, Common Lisp Extensions}).
+(@pxref{Generalized Variables}).
@var{place} can also be a cons @code{(@var{get} . @var{set})},
where @var{get} is an expression that returns the current state,
and @var{set} is a function of one argument (a state) that sets it.
This defines a global toggle named @var{global-mode} whose meaning is
to enable or disable the buffer-local minor mode @var{mode} in all
buffers. To turn on the minor mode in a buffer, it uses the function
-@var{turn-on}; to turn off the minor mode, it calls @code{mode} with
+@var{turn-on}; to turn off the minor mode, it calls @var{mode} with
@minus{}1 as argument.
Globally enabling the mode also affects buffers subsequently created
characters which have no @code{face} properties are displayed, by
default, in the face @code{mode-line} or @code{mode-line-inactive}
(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The
-@code{help-echo} and @code{local-map} properties in @var{string} have
+@code{help-echo} and @code{keymap} properties in @var{string} have
special meanings. @xref{Properties in Mode}.
@item @var{symbol}
@subsection @code{%}-Constructs in the Mode Line
Strings used as mode line constructs can use certain
-@code{%}-constructs to substitute various kinds of data. Here is a
-list of the defined @code{%}-constructs, and what they mean. In any
-construct except @samp{%%}, you can add a decimal integer after the
-@samp{%} to specify a minimum field width. If the width is less, the
-field is padded with spaces to the right.
+@code{%}-constructs to substitute various kinds of data. The
+following is a list of the defined @code{%}-constructs, and what they
+mean.
+
+ In any construct except @samp{%%}, you can add a decimal integer
+after the @samp{%} to specify a minimum field width. If the width is
+less, the field is padded to that width. Purely numeric constructs
+(@samp{c}, @samp{i}, @samp{I}, and @samp{l}) are padded by inserting
+spaces to the left, and others are padded by inserting spaces to the
+right.
@table @code
@item %b
The status of the subprocess belonging to the current buffer, obtained with
@code{process-status}. @xref{Process Information}.
-@item %t
-Whether the visited file is a text file or a binary file. This is a
-meaningful distinction only on certain operating systems (@pxref{MS-DOS
-File Types}).
-
@item %z
The mnemonics of keyboard, terminal, and buffer coding systems.
Certain text properties are meaningful in the
mode line. The @code{face} property affects the appearance of text; the
@code{help-echo} property associates help strings with the text, and
-@code{local-map} can make the text mouse-sensitive.
+@code{keymap} can make the text mouse-sensitive.
There are four ways to specify text properties for text in the mode
line:
property.
@end enumerate
- You can use the @code{local-map} property to specify a keymap. This
+ You can use the @code{keymap} property to specify a keymap. This
keymap only takes real effect for mouse clicks; binding character keys
and function keys to it has no effect, since it is impossible to move
point into the mode line.
It is normally @code{nil}, so that ordinary buffers have no header line.
@end defvar
+@defun window-header-line-height &optional window
+This function returns the height in pixels of @var{window}'s header
+line. @var{window} must be a live window, and defaults to the
+selected window.
+@end defun
+
A window that is just one line tall never displays a header line. A
window that is two lines tall cannot display both a mode line and a
header line at once; if it has a mode line, then it does not display a
A nested sub-alist element looks like this:
@example
-(@var{menu-title} @var{sub-alist})
+(@var{menu-title} . @var{sub-alist})
@end example
It creates the submenu @var{menu-title} specified by @var{sub-alist}.
@item font-lock-comment-delimiter-face
@vindex font-lock-comment-delimiter-face
-for comments delimiters, like @samp{/*} and @samp{*/} in C. On most
+for comments delimiters, like @samp{/*} and @samp{*/} in C@. On most
terminals, this inherits from @code{font-lock-comment-face}.
@item font-lock-type-face
This variable is semi-obsolete; we usually recommend setting
@code{syntax-begin-function} instead. One of its uses is to tune the
-behavior of syntactic fontification, e.g.@: to ensure that different
+behavior of syntactic fontification, e.g., to ensure that different
kinds of strings or comments are highlighted differently.
The specified function is called with no arguments. It should leave
@section Automatic Indentation of code
For programming languages, an important feature of a major mode is to
-provide automatic indentation. This is controlled in Emacs by
-@code{indent-line-function} (@pxref{Mode-Specific Indent}).
-Writing a good indentation function can be difficult and to a large
-extent it is still a black art.
-
-Many major mode authors will start by writing a simple indentation
-function that works for simple cases, for example by comparing with the
-indentation of the previous text line. For most programming languages
-that are not really line-based, this tends to scale very poorly:
-improving such a function to let it handle more diverse situations tends
-to become more and more difficult, resulting in the end with a large,
-complex, unmaintainable indentation function which nobody dares to touch.
+provide automatic indentation. There are two parts: one is to decide what
+is the right indentation of a line, and the other is to decide when to
+reindent a line. By default, Emacs reindents a line whenever you
+type a character in @code{electric-indent-chars}, which by default only
+includes Newline. Major modes can add chars to @code{electric-indent-chars}
+according to the syntax of the language.
+
+Deciding what is the right indentation is controlled in Emacs by
+@code{indent-line-function} (@pxref{Mode-Specific Indent}). For some modes,
+the @emph{right} indentation cannot be known reliably, typically because
+indentation is significant so several indentations are valid but with different
+meanings. In that case, the mode should set @code{electric-indent-inhibit} to
+make sure the line is not constantly re-indented against the user's wishes.
+
+Writing a good indentation function can be difficult and to a large extent it
+is still a black art. Many major mode authors will start by writing a simple
+indentation function that works for simple cases, for example by comparing with
+the indentation of the previous text line. For most programming languages that
+are not really line-based, this tends to scale very poorly: improving
+such a function to let it handle more diverse situations tends to become more
+and more difficult, resulting in the end with a large, complex, unmaintainable
+indentation function which nobody dares to touch.
A good indentation function will usually need to actually parse the
text, according to the syntax of the language. Luckily, it is not
purpose of indentation it has the advantage of not needing to
guess a ``safe'' starting point, and it generally enjoys the property
that only a minimum of text will be analyzed to decide the indentation
-of a line, so indentation will tend to be unaffected by syntax errors in
+of a line, so indentation will tend to be less affected by syntax errors in
some earlier unrelated piece of code. Parsing forward on the other hand
is usually easier and has the advantage of making it possible to
reindent efficiently a whole region at a time, with a single parse.
@node SMIE
@subsection Simple Minded Indentation Engine
+@cindex SMIE
SMIE is a package that provides a generic navigation and indentation
engine. Based on a very simple parser using an ``operator precedence
* SMIE Indentation:: Specifying indentation rules.
* SMIE Indentation Helpers:: Helper functions for indentation rules.
* SMIE Indentation Example:: Sample indentation rules.
+* SMIE Customization:: Customizing indentation.
@end menu
@node SMIE setup
@item
A token can be an @code{opener} (something similar to an open-paren),
a @code{closer} (like a close-paren), or @code{neither} of the two
-(e.g. an infix operator, or an inner token like @code{"else"}).
+(e.g., an infix operator, or an inner token like @code{"else"}).
@end itemize
Precedence conflicts can be resolved via @var{resolvers}, which
@node SMIE Grammar
@subsubsection Defining the Grammar of a Language
+@cindex SMIE grammar
+@cindex grammar, SMIE
The usual way to define the SMIE grammar of a language is by
defining a new global variable that holds the precedence table by
@node SMIE Lexer
@subsubsection Defining Tokens
+@cindex SMIE lexer
+@cindex defining tokens, SMIE
SMIE comes with a predefined lexical analyzer which uses syntax tables
in the following way: any sequence of characters that have word or
Notice how those lexers return the empty string when in front of
parentheses. This is because SMIE automatically takes care of the
parentheses defined in the syntax table. More specifically if the lexer
-returns nil or an empty string, SMIE tries to handle the corresponding
+returns @code{nil} or an empty string, SMIE tries to handle the corresponding
text as a sexp according to syntax tables.
@node SMIE Tricks
restructure the grammar. Do not despair: while the parser cannot be
made more clever, you can make the lexer as smart as you want. So, the
solution is then to look at the tokens involved in the conflict and to
-split one of those tokens into 2 (or more) different tokens. E.g. if
+split one of those tokens into 2 (or more) different tokens. E.g., if
the grammar needs to distinguish between two incompatible uses of the
token @code{"begin"}, make the lexer return different tokens (say
@code{"begin-fun"} and @code{"begin-plain"}) depending on which kind of
@node SMIE Indentation
@subsubsection Specifying Indentation Rules
+@cindex indentation rules, SMIE
Based on the provided grammar, SMIE will be able to provide automatic
indentation without any extra effort. But in practice, this default
@end itemize
When @var{arg} is a token, the function is called with point just before
-that token. A return value of nil always means to fallback on the
-default behavior, so the function should return nil for arguments it
+that token. A return value of @code{nil} always means to fallback on the
+default behavior, so the function should return @code{nil} for arguments it
does not expect.
@var{offset} can be:
By @emph{separator}, we mean here a token whose sole purpose is to
separate various elements within some enclosing syntactic construct, and
-which does not have any semantic significance in itself (i.e. it would
+which does not have any semantic significance in itself (i.e., it would
typically not exist as a node in an abstract syntax tree).
Such a token is expected to have an associative syntax and be closely
@itemize
@item
The first case indicates the basic indentation increment to use.
-If @code{sample-indent-basic} is nil, then SMIE uses the global
+If @code{sample-indent-basic} is @code{nil}, then SMIE uses the global
setting @code{smie-indent-basic}. The major mode could have set
@code{smie-indent-basic} buffer-locally instead, but that
is discouraged.
first @code{"if"} of the sequence.
@end itemize
+@c In some sense this belongs more in the Emacs manual.
+@node SMIE Customization
+@subsubsection Customizing Indentation
+
+If you are using a mode whose indentation is provided by SMIE, you can
+customize the indentation to suit your preferences. You can do this
+on a per-mode basis (using the option @code{smie-config}), or a
+per-file basis (using the function @code{smie-config-local} in a
+file-local variable specification).
+
+@defopt smie-config
+This option lets you customize indentation on a per-mode basis.
+It is an alist with elements of the form @code{(@var{mode} . @var{rules})}.
+For the precise form of rules, see the variable's documentation; but
+you may find it easier to use the command @code{smie-config-guess}.
+@end defopt
+
+@deffn Command smie-config-guess
+This command tries to work out appropriate settings to produce
+your preferred style of indentation. Simply call the command while
+visiting a file that is indented with your style.
+@end deffn
+
+@deffn Command smie-config-save
+Call this command after using @code{smie-config-guess}, to save your
+settings for future sessions.
+@end deffn
+
+@deffn Command smie-config-show-indent &optional move
+This command displays the rules that are used to indent the current
+line.
+@end deffn
+
+@deffn Command smie-config-set-indent
+This command adds a local rule to adjust the indentation of the current line.
+@end deffn
+
+@defun smie-config-local rules
+This function adds @var{rules} as indentation rules for the current buffer.
+These add to any mode-specific rules defined by the @code{smie-config} option.
+To specify custom indentation rules for a specific file, add an entry
+to the file's local variables of the form:
+@code{eval: (smie-config-local '(@var{rules}))}.
+@end defun
+
+
@node Desktop Save Mode
@section Desktop Save Mode
@cindex desktop save mode
Here @var{desktop-buffer-misc} is the value returned by the function
optionally bound to @code{desktop-save-buffer}.
@end defvar
-