@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 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
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
based on a certain mode-line specification.
@defun format-mode-line format &optional face window buffer
-This function formats a line of text according to @var{format} as if
-it were generating the mode line for @var{window}, but instead of
-displaying the text in the mode line or the header line, it returns
-the text as a string. The argument @var{window} defaults to the
-selected window. If @var{buffer} is non-@code{nil}, all the
-information used is taken from @var{buffer}; by default, it comes from
-@var{window}'s buffer.
+This function formats a line of text according to @var{format} as if it
+were generating the mode line for @var{window}, but it also returns the
+text as a string. The argument @var{window} defaults to the selected
+window. If @var{buffer} is non-@code{nil}, all the information used is
+taken from @var{buffer}; by default, it comes from @var{window}'s
+buffer.
The value string normally has text properties that correspond to the
-faces, keymaps, etc., that the mode line would have. And any character
-for which no @code{face} property is specified gets a default
-value which is usually @var{face}. (If @var{face} is @code{t},
-that stands for either @code{mode-line} if @var{window} is selected,
+faces, keymaps, etc., that the mode line would have. Any character for
+which no @code{face} property is specified by @var{format} gets a
+default value determined by @var{face}. If @var{face} is @code{t}, that
+stands for either @code{mode-line} if @var{window} is selected,
otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
-omitted, that stands for no face property.)
+omitted, that stands for the default face. If @var{face} is an integer,
+the value returned by this function will have no text properties.
+
+You can also specify other valid faces as the value of @var{face}.
+If specified, that face provides the @code{face} property for characters
+whose face is not specified by @var{format}.
-However, if @var{face} is an integer, the value has no text properties.
+Note that using @code{mode-line}, @code{mode-line-inactive}, or
+@code{header-line} as @var{face} will actually redisplay the mode line
+or the header line, respectively, using the current definitions of the
+corresponding face, in addition to returning the formatted string.
+(Other faces do not cause redisplay.)
For example, @code{(format-mode-line header-line-format)} returns the
text that would appear in the selected window's header line (@code{""}
if it has no header line). @code{(format-mode-line header-line-format
'header-line)} returns the same text, with each character
-carrying the face that it will have in the header line itself.
+carrying the face that it will have in the header line itself, and also
+redraws the header line.
@end defun
@node Imenu
@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.
+ 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}).
-@table @code
-@item font-lock-comment-face
-@vindex font-lock-comment-face
-Used (typically) for comments.
+ 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-comment-delimiter-face
-@vindex font-lock-comment-delimiter-face
-Used (typically) for comments delimiters.
-
-@item font-lock-doc-face
-@vindex font-lock-doc-face
-Used (typically) for documentation strings in the code.
-
-@item font-lock-string-face
-@vindex font-lock-string-face
-Used (typically) for string constants.
-
-@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.
+ 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-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