[Emacs-diffs] /srv/bzr/emacs/trunk r103085: * modes.texi (Major Mode Conventions): Add face guidelines.

[Chong Yidong]

------------------------------------------------------------
revno: 103085
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2011-02-02 15:44:19 -0500
message:
  * modes.texi (Major Mode Conventions): Add face guidelines.
  (Faces for Font Lock): List faces in order of prominence.
modified:
  doc/lispref/ChangeLog
  doc/lispref/modes.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-02-01 07:23:48 +0000
+++ b/doc/lispref/ChangeLog     2011-02-02 20:44:19 +0000
@@ -1,3 +1,8 @@
+2011-02-02  Chong Yidong  <address@hidden>
+
+       * modes.texi (Major Mode Conventions): Add face guidelines.
+       (Faces for Font Lock): List faces in order of prominence.
+
 2011-02-01  Paul Eggert  <address@hidden>
 
        format-time-string now supports subsecond time stamp resolution

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2011-01-25 04:08:28 +0000
+++ b/doc/lispref/modes.texi    2011-02-02 20:44:19 +0000
@@ -415,6 +415,31 @@
 @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:
+
address@hidden @asis
address@hidden @code{highlight}
+for stretches of text that should temporarily stand out.
+
address@hidden @code{match}
+for text matching a search command.
+
address@hidden @code{link} and @code{link-visited}
+for clickable text buttons that send the user to a different buffer or
+``location''.
+
address@hidden @code{button}
+for clickable text buttons that perform other actions.
+
address@hidden @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.
address@hidden for Font Lock}, for how to assign Font Lock faces.
address@hidden table
+
address@hidden
 The mode should specify how Imenu should find the definitions or
 sections of a buffer, by setting up a buffer-local value for the
 variable @code{imenu-generic-expression}, for the two variables
@@ -2879,73 +2904,79 @@
 @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
address@hidden  This means you can write
address@hidden in a context such as
address@hidden 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}).
+
+  Each of these symbols is both a face name, and a variable whose
+default value is the symbol itself.  Thus, the default value of
address@hidden is @code{font-lock-comment-face}.
+
+  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.
 
 @table @code
address@hidden font-lock-warning-face
address@hidden 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.
+
address@hidden font-lock-function-name-face
address@hidden font-lock-function-name-face
+for the name of a function being defined or declared.
+
address@hidden font-lock-variable-name-face
address@hidden font-lock-variable-name-face
+for the name of a variable being defined or declared.
+
address@hidden font-lock-keyword-face
address@hidden font-lock-keyword-face
+for a keyword with special syntactic significance, like @samp{for} and
address@hidden in C.
+
 @item font-lock-comment-face
 @vindex font-lock-comment-face
-Used (typically) for comments.
+for comments.
 
 @item font-lock-comment-delimiter-face
 @vindex font-lock-comment-delimiter-face
-Used (typically) for comments delimiters.
-
address@hidden font-lock-doc-face
address@hidden font-lock-doc-face
-Used (typically) for documentation strings in the code.
-
address@hidden font-lock-string-face
address@hidden font-lock-string-face
-Used (typically) for string constants.
-
address@hidden font-lock-keyword-face
address@hidden font-lock-keyword-face
-Used (typically) for keywords---names that have special syntactic
-significance, like @code{for} and @code{if} in C.
-
address@hidden font-lock-builtin-face
address@hidden font-lock-builtin-face
-Used (typically) for built-in function names.
-
address@hidden font-lock-function-name-face
address@hidden font-lock-function-name-face
-Used (typically) for the name of a function being defined or declared,
-in a function definition or declaration.
-
address@hidden font-lock-variable-name-face
address@hidden font-lock-variable-name-face
-Used (typically) for the name of a variable being defined or declared,
-in a variable definition or declaration.
+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.
+
address@hidden font-lock-builtin-face
address@hidden 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
address@hidden
+
address@hidden font-lock-string-face
address@hidden font-lock-string-face
+for string constants.
+
address@hidden font-lock-doc-face
address@hidden font-lock-doc-face
+for documentation strings in the code.  This inherits, by default, from
address@hidden
 
 @item font-lock-negation-char-face
 @vindex font-lock-negation-char-face
-Used (typically) for easily-overlooked negation characters.
-
address@hidden font-lock-warning-face
address@hidden 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
address@hidden;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
-directives in C.
+for easily-overlooked negation characters.
 @end table
 
 @node Syntactic Font Lock