Function: describe-face

describe-face is an autoloaded, interactive and byte-compiled function defined in help-fns.el.gz.

Signature

(describe-face FACE &optional FRAME)

Documentation

Display the properties of face FACE on FRAME.

Interactively, FACE defaults to the faces of the character after point and FRAME defaults to the selected frame.

If the optional argument FRAME is given, report on face FACE in that frame. If FRAME is t, report on the defaults for face FACE (for new frames). If FRAME is omitted or nil, use the selected frame.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/help-fns.el.gz
;; Faces.

;;;###autoload
(defun describe-face (face &optional frame)
  "Display the properties of face FACE on FRAME.
Interactively, FACE defaults to the faces of the character after point
and FRAME defaults to the selected frame.

If the optional argument FRAME is given, report on face FACE in that frame.
If FRAME is t, report on the defaults for face FACE (for new frames).
If FRAME is omitted or nil, use the selected frame."
  (interactive (list (read-face-name "Describe face"
                                     (or (face-at-point t) 'default)
                                     t)))
  (let ((help-buffer-under-preparation t))
    (help-setup-xref (list #'describe-face face)
		     (called-interactively-p 'interactive))
    (unless face
      (setq face 'default))
    (setq face (ensure-list face))
    (with-help-window (help-buffer)
      (with-current-buffer standard-output
        (dolist (f face (buffer-string))
	  (if (stringp f) (setq f (intern f)))
	  ;; We may get called for anonymous faces (i.e., faces
	  ;; expressed using prop-value plists).  Those can't be
	  ;; usefully customized, so ignore them.
	  (when (symbolp f)
	    (insert "Face: " (symbol-name f))
	    (if (not (facep f))
                (insert "   undefined face.\n")
	      (let ((customize-label "customize this face")
		    file-name)
                (insert (concat " (" (propertize "sample" 'font-lock-face f) ")"))
                (princ (concat " (" customize-label ")\n"))
                ;; FIXME not sure how much of this belongs here, and
                ;; how much in `face-documentation'.  The latter is
                ;; not used much, but needs to return nil for
                ;; undocumented faces.
                (let ((alias (get f 'face-alias))
		      (face f)
		      obsolete)
		  (when alias
		    (setq face alias)
		    (insert
		     (format-message
                      "\n  %s is an alias for the face `%s'.\n%s"
                      f alias
                      (if (setq obsolete (get f 'obsolete-face))
                          (format-message
                           "  This face is obsolete%s; use `%s' instead.\n"
                           (if (stringp obsolete)
                               (format " since %s" obsolete)
                             "")
                           alias)
                        ""))))
		  (insert "\nDocumentation:\n"
                          (or (face-documentation face)
                              "Not documented as a face.")
			  "\n\n"))
                (with-current-buffer standard-output
		  (save-excursion
                    (re-search-backward (concat "\\(" customize-label "\\)"))
		    (help-xref-button 1 'help-customize-face f)))
                (setq file-name (find-lisp-object-file-name f 'defface))
                (if (not file-name)
                    (setq help-mode--current-data (list :symbol f))
                  (setq help-mode--current-data (list :symbol f
                                                      :file file-name))
                (princ (substitute-quotes "Defined in `"))
		  (princ (help-fns-short-filename file-name))
                (princ (substitute-quotes "'"))
		  ;; Make a hyperlink to the library.
		  (save-excursion
		    (re-search-backward
                     (substitute-command-keys "`\\([^`']+\\)'"))
		    (help-xref-button 1 'help-face-def f file-name))
		  (princ ".")
		  (terpri)
		  (terpri))))
	    (terpri)
            (help-fns--run-describe-functions
             help-fns-describe-face-functions f frame)))))))