@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/modes
@node Modes, Documentation, Keymaps, Top
The hook variable's value can also be a single function---either a
lambda expression or a symbol with a function definition---which
@code{run-hooks} calls. But this usage is obsolete.
+
+If the hook variable is buffer-local, the buffer-local variable will
+be used instead of the global variable. However, if the buffer-local
+variable contains the element @code{t}, the global hook variable will
+be run as well.
@end defun
@defun run-hook-with-args hook &rest args
value is a single function; it sets or changes the value to a list of
functions.
-If @var{local} is non-@code{nil}, that says to add @var{function} to
-the buffer-local hook list instead of to the global hook list. If
-needed, this makes the hook buffer-local and adds @code{t} to the
-buffer-local value. The latter acts as a flag to run the hook
-functions in the default value as well as in the local value.
+If @var{local} is non-@code{nil}, that says to add @var{function} to the
+buffer-local hook list instead of to the global hook list. This makes
+the hook buffer-local and adds @code{t} to the buffer-local value. The
+latter acts as a flag to run the hook functions in the default value as
+well as in the local value.
@end defun
@defun remove-hook hook function &optional local
setting up a buffer-local value for the variable
@code{font-lock-defaults} (@pxref{Font Lock Mode}).
+@item
+Each face that the mode defines should, if possible, inherit from an
+existing Emacs face. This reduces the chance of conflicting with a
+user's face customizations. Useful faces include:
+
+@table @asis
+@item @code{highlight}
+for stretches of text that should temporarily stand out.
+
+@item @code{match}
+for text matching a search command.
+
+@item @code{link} and @code{link-visited}
+for clickable text buttons that send the user to a different buffer or
+``location''.
+
+@item @code{button}
+for clickable text buttons that perform other actions.
+
+@item @asis{Font Lock faces}
+for other kinds of syntactic highlighting, if highlighting is not
+handled by Font Lock mode or some Font Lock faces are not in use.
+@xref{Faces for Font Lock}, for how to assign Font Lock faces.
+@end table
+
@item
The mode should specify how Imenu should find the definitions or
sections of a buffer, by setting up a buffer-local value for the
value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
@item
-If this mode is appropriate only for specially-prepared text, then the
-major mode command symbol should have a property named @code{mode-class}
-with value @code{special}, put on as follows:
+If this mode is appropriate only for specially-prepared text produced by
+the mode itself (rather than by the user typing at the keyboard or by an
+external file), then the major mode command symbol should have a
+property named @code{mode-class} with value @code{special}, put on as
+follows:
@kindex mode-class @r{(property)}
-@cindex @code{special}
+@cindex @code{special} modes
@example
(put 'funny-mode 'mode-class 'special)
@end example
@noindent
-This tells Emacs that new buffers created while the current buffer is
-in Funny mode should not inherit Funny mode, in case the default value
-of @code{major-mode} is @code{nil}. Modes such as Dired, Rmail,
-and Buffer List use this feature.
+This tells Emacs that new buffers created while the current buffer is in
+Funny mode should not be put in Funny mode, even though the default
+value of @code{major-mode} is @code{nil}. By default, the value of
+@code{nil} for @code{major-mode} means to use the current buffer's major
+mode when creating new buffers (@pxref{Auto Major Mode}), but with such
+@code{special} modes, Fundamental mode is used instead. Modes such as
+Dired, Rmail, and Buffer List use this feature.
The @code{define-derived-mode} macro automatically marks the derived
mode as special if the parent mode is special. The special mode
@var{find-file} is normally @code{nil}. In this case,
@code{normal-mode} unconditionally processes any file local variables.
-If @code{normal-mode} processes the local variables list and this list
-specifies a major mode, that mode overrides any mode chosen by
-@code{set-auto-mode}. If neither @code{set-auto-mode} nor
-@code{hack-local-variables} specify a major mode, the buffer stays in
-the major mode determined by the default value of @code{major-mode}
-(see below).
+The function calls @code{set-auto-mode} to choose a major mode. If this
+does not specify a mode, the buffer stays in the major mode determined
+by the default value of @code{major-mode} (see below).
@cindex file mode specification error
@code{normal-mode} uses @code{condition-case} around the call to the
@cindex visited file mode
This function selects the major mode that is appropriate for the
current buffer. It bases its decision (in order of precedence) on
-the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using
+the @w{@samp{-*-}} line, on any @samp{mode:} local variable near the
+end of a file, on the @w{@samp{#!}} line (using
@code{interpreter-mode-alist}), on the text at the beginning of the
buffer (using @code{magic-mode-alist}), and finally on the visited
file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How
-Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this
-function does not look for the @samp{mode:} local variable near the
-end of a file; the @code{hack-local-variables} function does that.
+Major Modes are Chosen, emacs, The GNU Emacs Manual}.
If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
-does not check the @w{@samp{-*-}} line for a mode tag either.
+does not check the @w{@samp{-*-}} line, or near the end of the file,
+for any mode tag.
If @var{keep-mode-if-same} is non-@code{nil}, this function does not
call the mode command if the buffer is already in the proper major
@end group
@group
;; @r{These four lines are absent from the current version}
- ;; @r{not because this is done some other way, but rather}
- ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
+ ;; @r{not because this is done some other way, but because}
+ ;; @r{nowadays Text mode uses the normal definition of paragraphs.}
(set (make-local-variable 'paragraph-start)
(concat "[ \t]*$\\|" page-delimiter))
(set (make-local-variable 'paragraph-separate) paragraph-start)
@smallexample
@group
- (set (make-local-variable 'paragraph-start) (concat page-delimiter "\\|$" ))
- (set (make-local-variable 'paragraph-separate) paragraph-start)
+ (set (make-local-variable 'paragraph-start)
+ (concat page-delimiter "\\|$" ))
+ (set (make-local-variable 'paragraph-separate)
+ paragraph-start)
@dots{}
@end group
@group
- (set (make-local-variable 'comment-indent-function) 'lisp-comment-indent))
+ (set (make-local-variable 'comment-indent-function)
+ 'lisp-comment-indent))
@dots{}
@end group
@end smallexample
This variable displays the buffer's major and minor modes. Its
default value also displays the recursive editing level, information
on the process status, and whether narrowing is in effect.
+@end defopt
+
+@defopt mode-line-remote
+This variable is used to show whether @code{default-directory} for the
+current buffer is remote.
+@end defopt
+
+@defopt mode-line-client
+This variable is used to identify @code{emacsclient} frames.
@end defopt
The following three variables are used in @code{mode-line-modes}:
@cindex faces for font lock
@cindex font lock faces
- You can make Font Lock mode use any face, but several faces are
-defined specifically for Font Lock mode. Each of these symbols is both
-a face name, and a variable whose default value is the symbol itself.
-Thus, the default value of @code{font-lock-comment-face} is
-@code{font-lock-comment-face}. This means you can write
-@code{font-lock-comment-face} in a context such as
-@code{font-lock-keywords} where a face-name-valued expression is used.
-
-@table @code
-@item font-lock-comment-face
-@vindex font-lock-comment-face
-Used (typically) for comments.
-
-@item font-lock-comment-delimiter-face
-@vindex font-lock-comment-delimiter-face
-Used (typically) for comments delimiters.
+ Font Lock mode can highlight using any face, but Emacs defines several
+faces specifically for syntactic highlighting. These @dfn{Font Lock
+faces} are listed below. They can also be used by major modes for
+syntactic highlighting outside of Font Lock mode (@pxref{Major Mode
+Conventions}).
-@item font-lock-doc-face
-@vindex font-lock-doc-face
-Used (typically) for documentation strings in the code.
+ Each of these symbols is both a face name, and a variable whose
+default value is the symbol itself. Thus, the default value of
+@code{font-lock-comment-face} is @code{font-lock-comment-face}.
-@item font-lock-string-face
-@vindex font-lock-string-face
-Used (typically) for string constants.
+ The faces are listed with descriptions of their typical usage, and in
+order of greater to lesser ``prominence''. If a mode's syntactic
+categories do not fit well with the usage descriptions, the faces can be
+assigned using the ordering as a guide.
-@item font-lock-keyword-face
-@vindex font-lock-keyword-face
-Used (typically) for keywords---names that have special syntactic
-significance, like @code{for} and @code{if} in C.
-
-@item font-lock-builtin-face
-@vindex font-lock-builtin-face
-Used (typically) for built-in function names.
+@table @code
+@item font-lock-warning-face
+@vindex font-lock-warning-face
+for a construct that is peculiar, or that greatly changes the meaning of
+other text, like @samp{;;;###autoload} in Emacs Lisp and @samp{#error}
+in C.
@item font-lock-function-name-face
@vindex font-lock-function-name-face
-Used (typically) for the name of a function being defined or declared,
-in a function definition or declaration.
+for the name of a function being defined or declared.
@item font-lock-variable-name-face
@vindex font-lock-variable-name-face
-Used (typically) for the name of a variable being defined or declared,
-in a variable definition or declaration.
+for the name of a variable being defined or declared.
+
+@item font-lock-keyword-face
+@vindex font-lock-keyword-face
+for a keyword with special syntactic significance, like @samp{for} and
+@samp{if} in C.
+
+@item font-lock-comment-face
+@vindex font-lock-comment-face
+for comments.
+
+@item font-lock-comment-delimiter-face
+@vindex font-lock-comment-delimiter-face
+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
@vindex font-lock-type-face
-Used (typically) for names of user-defined data types,
-where they are defined and where they are used.
+for the names of user-defined data types.
@item font-lock-constant-face
@vindex font-lock-constant-face
-Used (typically) for constant names.
+for the names of constants, like @samp{NULL} in C.
+
+@item font-lock-builtin-face
+@vindex font-lock-builtin-face
+for the names of built-in functions.
@item font-lock-preprocessor-face
@vindex font-lock-preprocessor-face
-Used (typically) for preprocessor commands.
+for preprocessor commands. This inherits, by default, from
+@code{font-lock-builtin-face}.
+
+@item font-lock-string-face
+@vindex font-lock-string-face
+for string constants.
+
+@item font-lock-doc-face
+@vindex font-lock-doc-face
+for documentation strings in the code. This inherits, by default, from
+@code{font-lock-string-face}.
@item font-lock-negation-char-face
@vindex font-lock-negation-char-face
-Used (typically) for easily-overlooked negation characters.
-
-@item font-lock-warning-face
-@vindex font-lock-warning-face
-Used (typically) for constructs that are peculiar, or that greatly
-change the meaning of other text. For example, this is used for
-@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
-directives in C.
+for easily-overlooked negation characters.
@end table
@node Syntactic Font Lock
@menu
* Font Lock Multiline:: Marking multiline chunks with a text property.
-* Region to Fontify:: Controlling which region gets refontified
+* Region to Refontify:: Controlling which region gets refontified
after a buffer change.
@end menu
Font-Lock looks at it, or use
@code{font-lock-fontify-region-function}.
-@node Region to Fontify
+@node Region to Refontify
@subsubsection Region to Fontify after a Buffer Change
When a buffer is changed, the region that Font Lock refontifies is
example, when a change alters the syntactic meaning of text on an
earlier line.
- You can enlarge (or even reduce) the region to fontify by setting
-one the following variables:
+ You can enlarge (or even reduce) the region to refontify by setting
+the following variable:
@defvar font-lock-extend-after-change-region-function
This buffer-local variable is either @code{nil} or a function for
Font-Lock to call to determine the region to scan and fontify.
The function is given three parameters, the standard @var{beg},
-@var{end}, and @var{old-len} from after-change-functions
+@var{end}, and @var{old-len} from @code{after-change-functions}
(@pxref{Change Hooks}). It should return either a cons of the
beginning and end buffer positions (in that order) of the region to
fontify, or @code{nil} (which means choose the region in the standard
@end defvar
@node Auto-Indentation
-@section Auto-indention of code
+@section Auto-indentation of code
For programming languages, an important feature of a major mode is to
provide automatic indentation. This is controlled in Emacs by
or right-associativity of infix operators, nesting of tokens like
parentheses and many other cases.
-@c ยกLet's leave this undocumented to leave it more open for change!
+@c Let's leave this undocumented to leave it more open for change!
@c @defvar smie-grammar
@c The value of this variable is an alist specifying the left and right
@c precedence of each token. It is meant to be initialized by using one of
(inst ("IF" exp "THEN" insts "ELSE" insts "END")
("CASE" exp "OF" cases "END")
...)
- (cases (cases "|" cases) (caselabel ":" insts) ("ELSE" insts))
+ (cases (cases "|" cases)
+ (caselabel ":" insts)
+ ("ELSE" insts))
...
@end example
rule:
@example
((equal token "if")
- (and (not (smie-rule-bolp)) (smie-rule-prev-p "else")
+ (and (not (smie-rule-bolp))
+ (smie-rule-prev-p "else")
(save-excursion
- (sample-smie-backward-token) ;Jump before the "else".
+ (sample-smie-backward-token)
(cons 'column (current-column)))))
@end example