Misc manual updates.

[bpt/emacs.git] / lisp / faces.el

diff --git a/lisp/faces.el b/lisp/faces.el
index e7cfa20..bdac3a1 100644 (file)
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -1,6 +1,6 @@
 ;;; faces.el --- Lisp faces
 
 ;;; faces.el --- Lisp faces
 

-;; Copyright (C) 1992-1996, 1998-2011  Free Software Foundation, Inc.
+;; Copyright (C) 1992-1996, 1998-2012  Free Software Foundation, Inc.

 
 ;; Maintainer: FSF
 ;; Keywords: internal
 
 ;; Maintainer: FSF
 ;; Keywords: internal


@@ -119,7 +119,7 @@ REGISTRY, ALTERNATIVE1, ALTERNATIVE2, and etc."
 
 
 (defun face-list ()
 
 
 (defun face-list ()

-  "Return a list of all defined face names."
+  "Return a list of all defined faces."

   (mapcar #'car face-new-frame-defaults))
 
 
   (mapcar #'car face-new-frame-defaults))
 
 


@@ -557,9 +557,10 @@ If FACE is a face-alias, get the documentation for the target face."
 (defun set-face-attribute (face frame &rest args)
   "Set attributes of FACE on FRAME from ARGS.
 
 (defun set-face-attribute (face frame &rest args)
   "Set attributes of FACE on FRAME from ARGS.
 

-FRAME nil means change attributes on all frames.  FRAME t means change
-the default for new frames (this is done automatically each time an
-attribute is changed on all frames).
+If FRAME is nil this function sets the attributes for all
+existing frames, and the default for new frames.  If FRAME is t,
+change the default for new frames (this is done automatically
+each time an attribute is changed on all frames).

 
 ARGS must come in pairs ATTRIBUTE VALUE.  ATTRIBUTE must be a valid
 face attribute name.  All attributes can be set to `unspecified';
 
 ARGS must come in pairs ATTRIBUTE VALUE.  ATTRIBUTE must be a valid
 face attribute name.  All attributes can be set to `unspecified';


@@ -1255,7 +1256,7 @@ arg, prompt for a regular expression."
        (insert
         (substitute-command-keys
          (concat
        (insert
         (substitute-command-keys
          (concat

-          "Use "
+          "\\<help-mode-map>Use "

           (if (display-mouse-p) "\\[help-follow-mouse] or ")
           "\\[help-follow] on a face name to customize it\n"
           "or on its sample text for a description of the face.\n\n")))
           (if (display-mouse-p) "\\[help-follow-mouse] or ")
           "\\[help-follow] on a face name to customize it\n"
           "or on its sample text for a description of the face.\n\n")))


@@ -1445,24 +1446,26 @@ If FRAME is nil, the current FRAME is used."
            options (cdr conjunct)
            match (cond ((eq req 'type)
                         (or (memq (window-system frame) options)
            options (cdr conjunct)
            match (cond ((eq req 'type)
                         (or (memq (window-system frame) options)

+                            (and (memq 'graphic options)
+                                 (memq (window-system frame) '(x w32 ns)))

                             ;; FIXME: This should be revisited to use
                             ;; display-graphic-p, provided that the
                             ;; color selection depends on the number
                             ;; of supported colors, and all defface's
                             ;; are changed to look at number of colors
                             ;; instead of (type graphic) etc.
                             ;; FIXME: This should be revisited to use
                             ;; display-graphic-p, provided that the
                             ;; color selection depends on the number
                             ;; of supported colors, and all defface's
                             ;; are changed to look at number of colors
                             ;; instead of (type graphic) etc.

-                            (and (null (window-system frame))
-                                 (memq 'tty options))
-                            (and (memq 'motif options)
-                                 (featurep 'motif))
-                            (and (memq 'gtk options)
-                                 (featurep 'gtk))
-                            (and (memq 'lucid options)
-                                 (featurep 'x-toolkit)
-                                 (not (featurep 'motif))
-                                 (not (featurep 'gtk)))
-                            (and (memq 'x-toolkit options)
-                                 (featurep 'x-toolkit))))
+                            (if (null (window-system frame))
+                                (memq 'tty options)
+                              (or (and (memq 'motif options)
+                                       (featurep 'motif))
+                                  (and (memq 'gtk options)
+                                       (featurep 'gtk))
+                                  (and (memq 'lucid options)
+                                       (featurep 'x-toolkit)
+                                       (not (featurep 'motif))
+                                       (not (featurep 'gtk)))
+                                  (and (memq 'x-toolkit options)
+                                       (featurep 'x-toolkit))))))

                        ((eq req 'min-colors)
                         (>= (display-color-cells frame) (car options)))
                        ((eq req 'class)
                        ((eq req 'min-colors)
                         (>= (display-color-cells frame) (car options)))
                        ((eq req 'class)


@@ -1510,11 +1513,23 @@ If SPEC is nil, return nil."
 
 (defun face-spec-reset-face (face &optional frame)
   "Reset all attributes of FACE on FRAME to unspecified."
 
 (defun face-spec-reset-face (face &optional frame)
   "Reset all attributes of FACE on FRAME to unspecified."

-  (let (reset-args)
-    (dolist (attr-and-name face-attribute-name-alist)
-      (push 'unspecified reset-args)
-      (push (car attr-and-name) reset-args))
-    (apply 'set-face-attribute face frame reset-args)))
+  (apply 'set-face-attribute face frame
+        (if (eq face 'default)
+            ;; For the default face, avoid making any attribute
+            ;; unspecified.  Instead, set attributes to default values
+            ;; (see also realize_default_face in xfaces.c).
+            (append
+             '(:underline nil :overline nil :strike-through nil
+               :box nil :inverse-video nil :stipple nil :inherit nil)
+             (unless (display-graphic-p frame)
+               '(:family "default" :foundry "default" :width normal
+                 :height 1 :weight normal :slant normal
+                 :foreground "unspecified-fg"
+                 :background "unspecified-bg")))
+          ;; For all other faces, unspecify all attributes.
+          (apply 'append
+                 (mapcar (lambda (x) (list (car x) 'unspecified))
+                         face-attribute-name-alist)))))

 
 (defun face-spec-set (face spec &optional for-defface)
   "Set FACE's face spec, which controls its appearance, to SPEC.
 
 (defun face-spec-set (face spec &optional for-defface)
   "Set FACE's face spec, which controls its appearance, to SPEC.


@@ -1702,13 +1717,14 @@ If omitted or nil, that stands for the selected frame's display."
       (> (tty-color-gray-shades display) 2)))))
 
 (defun read-color (&optional prompt convert-to-RGB allow-empty-name msg)
       (> (tty-color-gray-shades display) 2)))))
 
 (defun read-color (&optional prompt convert-to-RGB allow-empty-name msg)

-  "Read a color name or RGB triplet of the form \"#RRRRGGGGBBBB\".
+  "Read a color name or RGB triplet.

 Completion is available for color names, but not for RGB triplets.
 
 Completion is available for color names, but not for RGB triplets.
 

-RGB triplets have the form #XXXXXXXXXXXX, where each X is a hex
-digit.  The number of Xs must be a multiple of 3, with the same
-number of Xs for each of red, green, and blue.  The order is red,
-green, blue.
+RGB triplets have the form \"#RRGGBB\".  Each of the R, G, and B
+components can have one to four digits, but all three components
+must have the same number of digits.  Each digit is a hex value
+between 0 and F; either upper case or lower case for A through F
+are acceptable.

 
 In addition to standard color names and RGB hex values, the
 following are available as color candidates.  In each case, the
 
 In addition to standard color names and RGB hex values, the
 following are available as color candidates.  In each case, the


@@ -1821,109 +1837,6 @@ Return nil if it has no specified face."
           (cond ((memq 'background-color face) (cdr (memq 'background-color face)))
                 ((memq ':background face) (cadr (memq ':background face)))))
          (t nil))))                    ; Invalid face value.
           (cond ((memq 'background-color face) (cdr (memq 'background-color face)))
                 ((memq ':background face) (cadr (memq ':background face)))))
          (t nil))))                    ; Invalid face value.

-\f
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;; Background mode.
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-
-(defcustom frame-background-mode nil
-  "The brightness of the background.
-Set this to the symbol `dark' if your background color is dark,
-`light' if your background is light, or nil (automatic by default)
-if you want Emacs to examine the brightness for you.  Don't set this
-variable with `setq'; this won't have the expected effect."
-  :group 'faces
-  :set #'(lambda (var value)
-          (set-default var value)
-          (mapc 'frame-set-background-mode (frame-list)))
-  :initialize 'custom-initialize-changed
-  :type '(choice (const dark)
-                (const light)
-                (const :tag "automatic" nil)))
-
-
-(declare-function x-get-resource "frame.c"
-                 (attribute class &optional component subclass))
-
-(defvar inhibit-frame-set-background-mode nil)
-
-(defun frame-set-background-mode (frame &optional keep-face-specs)
-  "Set up display-dependent faces on FRAME.
-Display-dependent faces are those which have different definitions
-according to the `background-mode' and `display-type' frame parameters.
-
-If optional arg KEEP-FACE-SPECS is non-nil, don't recalculate
-face specs for the new background mode."
-  (unless inhibit-frame-set-background-mode
-    (let* ((bg-resource
-           (and (window-system frame)
-                (x-get-resource "backgroundMode" "BackgroundMode")))
-          (bg-color (frame-parameter frame 'background-color))
-          (terminal-bg-mode (terminal-parameter frame 'background-mode))
-          (tty-type (tty-type frame))
-          (default-bg-mode
-            (if (or (window-system frame)
-                    (and tty-type
-                         (string-match "^\\(xterm\\|\\rxvt\\|dtterm\\|eterm\\)"
-                                       tty-type)))
-                'light
-              'dark))
-          (non-default-bg-mode (if (eq default-bg-mode 'light) 'dark 'light))
-          (bg-mode
-           (cond (frame-background-mode)
-                 (bg-resource (intern (downcase bg-resource)))
-                 (terminal-bg-mode)
-                 ((equal bg-color "unspecified-fg") ; inverted colors
-                  non-default-bg-mode)
-                 ((not (color-values bg-color frame))
-                  default-bg-mode)
-                 ((>= (apply '+ (color-values bg-color frame))
-                      ;; Just looking at the screen, colors whose
-                      ;; values add up to .6 of the white total
-                      ;; still look dark to me.
-                      (* (apply '+ (color-values "white" frame)) .6))
-                  'light)
-                 (t 'dark)))
-          (display-type
-           (cond ((null (window-system frame))
-                  (if (tty-display-color-p frame) 'color 'mono))
-                 ((display-color-p frame)
-                  'color)
-                 ((x-display-grayscale-p frame)
-                  'grayscale)
-                 (t 'mono)))
-          (old-bg-mode
-           (frame-parameter frame 'background-mode))
-          (old-display-type
-           (frame-parameter frame 'display-type)))
-
-      (unless (and (eq bg-mode old-bg-mode) (eq display-type old-display-type))
-       (let ((locally-modified-faces nil)
-             ;; Prevent face-spec-recalc from calling this function
-             ;; again, resulting in a loop (bug#911).
-             (inhibit-frame-set-background-mode t)
-             (params (list (cons 'background-mode bg-mode)
-                           (cons 'display-type display-type))))
-         (if keep-face-specs
-             (modify-frame-parameters frame params)
-           ;; If we are recomputing face specs, first collect a list
-           ;; of faces that don't match their face-specs.  These are
-           ;; the faces modified on FRAME, and we avoid changing them
-           ;; below.  Use a negative list to avoid consing (we assume
-           ;; most faces are unmodified).
-           (dolist (face (face-list))
-             (and (not (get face 'face-override-spec))
-                  (not (face-spec-match-p face
-                                          (face-user-default-spec face)
-                                          (selected-frame)))
-                  (push face locally-modified-faces)))
-           ;; Now change to the new frame parameters
-           (modify-frame-parameters frame params)
-           ;; For all unmodified named faces, choose face specs
-           ;; matching the new frame parameters.
-           (dolist (face (face-list))
-             (unless (memq face locally-modified-faces)
-               (face-spec-recalc face frame)))))))))

 
 \f
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 \f
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;


@@ -2020,12 +1933,13 @@ settings, X resources, and `face-new-frame-defaults'.
 Finally, apply any relevant face attributes found amongst the
 frame parameters in PARAMETERS."
   (let ((window-system-p (memq (window-system frame) '(x w32))))
 Finally, apply any relevant face attributes found amongst the
 frame parameters in PARAMETERS."
   (let ((window-system-p (memq (window-system frame) '(x w32))))

-    (dolist (face (nreverse (face-list))) ;Why reverse?  --Stef
+    ;; The `reverse' is so that `default' goes first.
+    (dolist (face (nreverse (face-list)))

       (condition-case ()
          (progn
            ;; Initialize faces from face spec and custom theme.
            (face-spec-recalc face frame)
       (condition-case ()
          (progn
            ;; Initialize faces from face spec and custom theme.
            (face-spec-recalc face frame)

-           ;; X resouces for the default face are applied during
+           ;; X resources for the default face are applied during

            ;; `x-create-frame'.
            (and (not (eq face 'default)) window-system-p
                 (make-face-x-resource-internal face frame))
            ;; `x-create-frame'.
            (and (not (eq face 'default)) window-system-p
                 (make-face-x-resource-internal face frame))


@@ -2165,9 +2079,9 @@ terminal type to a different value."
     (((supports :underline t))
      :underline t)
     (t
     (((supports :underline t))
      :underline t)
     (t

-     ;; default to italic, even it doesn't appear to be supported,
-     ;; because in some cases the display engine will do it's own
-     ;; workaround (to `dim' on ttys)
+     ;; Default to italic, even if it doesn't appear to be supported,
+     ;; because in some cases the display engine will do its own
+     ;; workaround (to `dim' on ttys).

      :slant italic))
   "Basic italic face."
   :group 'basic-faces)
      :slant italic))
   "Basic italic face."
   :group 'basic-faces)


@@ -2211,7 +2125,7 @@ terminal type to a different value."
 
 (defface link
   '((((class color) (min-colors 88) (background light))
 
 (defface link
   '((((class color) (min-colors 88) (background light))

-     :foreground "blue1" :underline t)
+     :foreground "RoyalBlue3" :underline t)

     (((class color) (background light))
      :foreground "blue" :underline t)
     (((class color) (min-colors 88) (background dark))
     (((class color) (background light))
      :foreground "blue" :underline t)
     (((class color) (min-colors 88) (background dark))


@@ -2466,6 +2380,10 @@ used to display the prompt text."
   '((((background light)) :background "black")
     (((background dark))  :background "white"))
   "Basic face for the cursor color under X.
   '((((background light)) :background "black")
     (((background dark))  :background "white"))
   "Basic face for the cursor color under X.

+Currently, only the `:background' attribute is meaningful; all
+other attributes are ignored.  The cursor foreground color is
+taken from the background color of the underlying text.
+

 Note: Other faces cannot inherit from the cursor face."
   :version "21.1"
   :group 'cursor
 Note: Other faces cannot inherit from the cursor face."
   :version "21.1"
   :group 'cursor


@@ -2515,12 +2433,45 @@ Note: Other faces cannot inherit from the cursor face."
 It is used for characters of no fonts too."
   :version "24.1"
   :group 'basic-faces)
 It is used for characters of no fonts too."
   :version "24.1"
   :group 'basic-faces)

+
+(defface error
+  '((((class color) (min-colors 88) (background light)) (:foreground "Red1" :weight bold))
+    (((class color) (min-colors 88) (background dark)) (:foreground "Pink" :weight bold))
+    (((class color) (min-colors 16) (background light)) (:foreground "Red1" :weight bold))
+    (((class color) (min-colors 16) (background dark)) (:foreground "Pink" :weight bold))
+    (((class color) (min-colors 8)) (:foreground "red"))
+    (t (:inverse-video t :weight bold)))
+  "Basic face used to highlight errors and to denote failure."
+  :version "24.1"
+  :group 'basic-faces)
+
+(defface warning
+  '((((class color) (min-colors 16)) (:foreground "DarkOrange" :weight bold))
+    (((class color)) (:foreground "yellow" :weight bold))
+    (t (:weight bold)))
+  "Basic face used to highlight warnings."
+  :version "24.1"
+  :group 'basic-faces)
+
+(defface success
+  '((((class color) (min-colors 16) (background light))
+     (:foreground "ForestGreen" :weight bold))
+    (((class color) (min-colors 88) (background dark))
+     (:foreground "Green1" :weight bold))
+    (((class color) (min-colors 16) (background dark))
+     (:foreground "Green" :weight bold))
+    (((class color)) (:foreground "green" :weight bold))
+    (t (:weight bold)))
+  "Basic face used to indicate successful operation."
+  :version "24.1"
+  :group 'basic-faces)
+

 \f
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;; Manipulating font names.
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 \f
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;; Manipulating font names.
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 

-;; This is here for compatibilty with Emacs 20.2.  For example,
+;; This is here for compatibility with Emacs 20.2.  For example,

 ;; international/fontset.el uses x-resolve-font-name.  The following
 ;; functions are not used in the face implementation itself.
 
 ;; international/fontset.el uses x-resolve-font-name.  The following
 ;; functions are not used in the face implementation itself.