describe-face should show an example of text in the face.

[Yoni Rabkin Katzenell]

Hello, I'm using GNU Emacs 22.0.50.1 (i686-pc-linux-gnu, X toolkit, Xaw3d 
scroll bars)
 of 2006-10-15 on ardbeg

emacs/etc/TODO says: "describe-face should show an example of text in
the face."

The attached patch against `faces.el' adds the word "sample", rendered
in the appropriate face, to the top row of the `describe-face' pop-up
buffer.

An example result can be seen in this screenshot:
http://yrk.nfshost.com/images/faces-sample.png

Index: faces.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/faces.el,v
retrieving revision 1.354
diff -u -r1.354 faces.el
--- faces.el    14 Sep 2006 23:54:44 -0000      1.354
+++ faces.el    15 Oct 2006 18:01:00 -0000
@@ -32,6 +32,8 @@
   ;; Warning suppression -- can't require x-win in batch:
   (autoload 'xw-defined-colors "x-win"))
 
+(defvar faces-example-overlay nil)
+
 (defvar help-xref-stack-item)
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -1253,6 +1255,14 @@
            (setq faces (cdr faces)))))))
 
 
+(defun faces-sample-overlay (face)
+  (let ((f (if (facep face) face 'default))
+       (start (point)))
+    (insert " sample")
+    (setq faces-example-overlay (make-overlay start (point)))
+    (overlay-put faces-example-overlay 'face f)))
+
+
 (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
@@ -1293,6 +1303,7 @@
              (insert "   undefined face.\n")
            (let ((customize-label "customize this face")
                  file-name)
+             (faces-sample-overlay f)
              (princ (concat " (" customize-label ")\n"))
              (insert "Documentation: "
                      (or (face-documentation f)


-- 
   "Cut your own wood and it will warm you twice"