--- a/lisp/ChangeLog	Thu Mar 17 21:50:34 2011 +0000
+++ b/lisp/ChangeLog	Sat Mar 19 22:13:14 2011 +0900
@@ -1,3 +1,9 @@
+2011-03-19  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* faces.el (face-spec-set-match-display):
+	Protect against `display-color-cells' returning nil.
+	Delete unreferenced let-binding of `min-colors'.
+
 2011-03-17  Aidan Kehoe  <kehoea@parhasard.net>
 
 	* bytecomp.el (byte-compile-catch):

--- a/lisp/faces.el	Thu Mar 17 21:50:34 2011 +0000
+++ b/lisp/faces.el	Sat Mar 19 22:13:14 2011 +0900
@@ -1702,7 +1702,6 @@
 	   (type (plist-get props 'type))
 	   (class (plist-get props 'class))
 	   (background (plist-get props 'background))
-           (min-colors (plist-get props 'min-colors))
 	   (match t)
 	   (entries display)
 	   entry req options)
@@ -1715,7 +1714,9 @@
 		      (type       (memq type options))
 		      (class      (memq class options))
 		      (background (memq background options))
-		      (min-colors (>= (display-color-cells frame)
+		      ;; `display-color-cells' can return nil (eg, TTYs).
+		      ;; If so, assume monochrome.
+		      (min-colors (>= (or (display-color-cells frame) 2)
 				      (car options)))
 		      (t (warn "Unknown req `%S' with options `%S'"
 			       req options)

--- a/man/ChangeLog	Thu Mar 17 21:50:34 2011 +0000
+++ b/man/ChangeLog	Sat Mar 19 22:13:14 2011 +0900
@@ -1,3 +1,13 @@
+2011-03-19  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* lispref/customize.texi (Face Definitions): New node.
+	(Customization): Add entry to menu.
+	(Variable Definitions): Add cross-ref for `defface'.
+	(Customization Types): Fixup Previous link.
+
+	* lispref/faces.texi (Faces):
+	Clarify that built-in properties of faces are computed at runtime.
+
 2011-03-15  Aidan Kehoe  <kehoea@parhasard.net>
 
 	* lispref/objects.texi (Character Type):

--- a/man/lispref/customize.texi	Thu Mar 17 21:50:34 2011 +0000
+++ b/man/lispref/customize.texi	Sat Mar 19 22:13:14 2011 +0900
@@ -15,6 +15,7 @@
 * Common Keywords::
 * Group Definitions::
 * Variable Definitions::
+* Face Definitions::
 * Customization Types::
 * Enabling Behavior::
 @end menu
@@ -163,6 +164,7 @@
 @section Defining Customization Variables
 
   Use @code{defcustom} to declare user-editable variables.
+For face declarations, use @code{defface} instead.  @xref{Face Definitions}.
 
 @tindex defcustom
 @defmac defcustom option default doc [keyword value]...
@@ -288,7 +290,67 @@
 customization buffer.  The @code{saved-value} property is actually a
 list whose car is an expression which evaluates to the value.
 
-@node Customization Types, Enabling Behavior, Variable Definitions, Customization
+@node Face Definitions, Customization Types, Variable Definitions, Customization
+@section Face Definitions
+
+Use @code{defface} to declare a new face.  Conventions used in
+specifying properties are similar to those for general customizable
+variables.  @xref{Variable Definitions}.
+
+@defun defface face spec doc &rest args
+
+Declare @var{face} as a customizable face that defaults to @var{spec}.
+@var{face} does not need to be quoted.
+
+Third argument @var{doc} is the face documentation.
+
+If @var{face} has been set with `custom-set-face', set the face attributes
+as specified by that function, otherwise set the face attributes
+according to @var{spec}.
+
+The remaining arguments @var{args} are a property list, which has the
+form
+
+   @var{keyword} @var{value}...
+
+The following @var{keyword}s are defined:
+
+@table @code
+@item :group
+@var{value} is a customization group.  Add @var{face} to that group.
+@end table
+
+@var{spec} is an alist of the form ((@var{display} @var{atts})...).
+
+@var{atts} is a list of face attributes and their values.  The possible
+attributes are defined in the variable `custom-face-attributes'.
+
+The @var{atts} of the first entry in @var{spec} where the
+@var{display} matches the frame take effect in that frame.
+@var{display} can either be the symbol t, which will match all frames,
+or an alist of the form \((@var{req} @var{item}...)...)
+
+For @var{display} to match a frame, the @var{req} property of the
+frame must match one of the @var{item}.  The following @var{req} are
+defined:
+
+@table @code
+@item @code{type} (the value of @code{window-system})
+  Should be one of @code{x}, @code{mswindows}, or @code{tty}.
+
+@code{class} (the frame's color support)
+  Should be one of @code{color}, @code{grayscale}, or @code{mono}.
+
+@code{min-colors} (the minimum number of colors the frame supports)
+  Should be in integer which is compared to @code{display-color-cells}
+
+@code{background} (what color is used for the background text)
+  Should be one of @code{light} or @code{dark}.
+@end table
+@end defun
+
+
+@node Customization Types, Enabling Behavior, Face Definitions, Customization
 @section Customization Types
 
   When you define a user option with @code{defcustom}, you must specify

--- a/man/lispref/faces.texi	Thu Mar 17 21:50:34 2011 +0000
+++ b/man/lispref/faces.texi	Sat Mar 19 22:13:14 2011 +0900
@@ -26,10 +26,13 @@
 
 Each built-in property of a face is controlled using a specifier,
 which allows it to have separate values in particular buffers, frames,
-windows, and devices and to further vary according to device type
-(X or TTY), device class (color, mono, or grayscale) and number of
-displayable colors (min-colors).
-@xref{Specifiers}, for more information.
+windows, and devices.  These properties are computed when the face is
+instantiated, allowing them to vary according to properties of the
+display device, such as type (X or TTY), visual class (color, mono, or
+grayscale), and number of colors displayable on the device.
+@xref{Specifiers}, for more information on specifiers.
+@xref{Face Definitions}, for defining faces whose properties vary
+according to their runtime environments.
 
 The face named @code{default} is used for ordinary text.  The face named
 @code{modeline} is used for displaying the modeline.  The face named