Commit e0dd6837 authored by Chong Yidong's avatar Chong Yidong
Browse files

* modes.texi (Major Mode Conventions): Add face guidelines.

(Faces for Font Lock): List faces in order of prominence.
parent 83cc5772
2011-02-02 Chong Yidong <cyd@stupidchicken.com>
* modes.texi (Major Mode Conventions): Add face guidelines.
(Faces for Font Lock): List faces in order of prominence.
2011-02-01 Paul Eggert <eggert@cs.ucla.edu> 2011-02-01 Paul Eggert <eggert@cs.ucla.edu>
format-time-string now supports subsecond time stamp resolution format-time-string now supports subsecond time stamp resolution
......
...@@ -414,6 +414,31 @@ The mode should specify how to do highlighting for Font Lock mode, by ...@@ -414,6 +414,31 @@ The mode should specify how to do highlighting for Font Lock mode, by
setting up a buffer-local value for the variable setting up a buffer-local value for the variable
@code{font-lock-defaults} (@pxref{Font Lock Mode}). @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 @item
The mode should specify how Imenu should find the definitions or The mode should specify how Imenu should find the definitions or
sections of a buffer, by setting up a buffer-local value for the sections of a buffer, by setting up a buffer-local value for the
...@@ -2879,73 +2904,79 @@ the normal Font Lock machinery, it should not set the variable ...@@ -2879,73 +2904,79 @@ the normal Font Lock machinery, it should not set the variable
@cindex faces for font lock @cindex faces for font lock
@cindex font lock faces @cindex font lock faces
You can make Font Lock mode use any face, but several faces are Font Lock mode can highlight using any face, but Emacs defines several
defined specifically for Font Lock mode. Each of these symbols is both faces specifically for syntactic highlighting. These @dfn{Font Lock
a face name, and a variable whose default value is the symbol itself. faces} are listed below. They can also be used by major modes for
Thus, the default value of @code{font-lock-comment-face} is syntactic highlighting outside of Font Lock mode (@pxref{Major Mode
@code{font-lock-comment-face}. This means you can write Conventions}).
@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.
@item font-lock-doc-face
@vindex font-lock-doc-face
Used (typically) for documentation strings in the code.
@item font-lock-string-face Each of these symbols is both a face name, and a variable whose
@vindex font-lock-string-face default value is the symbol itself. Thus, the default value of
Used (typically) for string constants. @code{font-lock-comment-face} is @code{font-lock-comment-face}.
@item font-lock-keyword-face The faces are listed with descriptions of their typical usage, and in
@vindex font-lock-keyword-face order of greater to lesser ``prominence''. If a mode's syntactic
Used (typically) for keywords---names that have special syntactic categories do not fit well with the usage descriptions, the faces can be
significance, like @code{for} and @code{if} in C. assigned using the ordering as a guide.
@item font-lock-builtin-face @table @code
@vindex font-lock-builtin-face @item font-lock-warning-face
Used (typically) for built-in function names. @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 @item font-lock-function-name-face
@vindex font-lock-function-name-face @vindex font-lock-function-name-face
Used (typically) for the name of a function being defined or declared, for the name of a function being defined or declared.
in a function definition or declaration.
@item font-lock-variable-name-face @item font-lock-variable-name-face
@vindex font-lock-variable-name-face @vindex font-lock-variable-name-face
Used (typically) for the name of a variable being defined or declared, for the name of a variable being defined or declared.
in a variable definition or declaration.
@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 @item font-lock-type-face
@vindex font-lock-type-face @vindex font-lock-type-face
Used (typically) for names of user-defined data types, for the names of user-defined data types.
where they are defined and where they are used.
@item font-lock-constant-face @item font-lock-constant-face
@vindex 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 @item font-lock-preprocessor-face
@vindex 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 @item font-lock-negation-char-face
@vindex font-lock-negation-char-face @vindex font-lock-negation-char-face
Used (typically) for easily-overlooked negation characters. 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.
@end table @end table
@node Syntactic Font Lock @node Syntactic Font Lock
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment