Add support for user-customizable icons

* doc/emacs/custom.texi (Specific Customization): Mention it.

* doc/emacs/display.texi (Icons): New node.

* doc/lispref/display.texi (Icons): New node.

* lisp/button.el (buttonize):
(button--properties, buttonize-region): Allow not overriding faces.

* lisp/cus-edit.el (custom-save-all): Save icons.
(custom-icon): New widget.
(custom-icon-value-create, custom-toggle-hide-icon)
(custom--icons-widget-value, custom-icon-set): Helper functions
for the widget.
(customize-icon): Main command.
(custom-icon-state-set, custom-icon-state): Helper functions.
(custom-theme-set-icons): Function to be used by theme writers.
(custom-set-icons): Function to be used in .emacs.
(custom-save-icons): New function.

* lisp/custom.el (custom-push-theme): Add icons.

* lisp/emacs-lisp/icons.el: New file.

* test/lisp/emacs-lisp/icons-tests.el: Add some tests.

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 96e05a902d6..b87ca81faea 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -24,6 +24,7 @@ the text is displayed.
 * Faces::                  How to change the display style using faces.
 * Colors::                 Specifying colors for faces.
 * Standard Faces::         The main predefined faces.
+* Icons::                  How to change how icons look.
 * Text Scale::             Increasing or decreasing text size in a buffer.
 * Font Lock::              Minor mode for syntactic highlighting using faces.
 * Highlight Interactively:: Tell Emacs what text to highlight.
@@ -851,6 +852,38 @@ This face is used to display on text-mode terminals the menu item that
 would be selected if you click a mouse or press @key{RET}.
 @end table
 
+@node Icons
+@section Icons
+
+Emacs sometimes displays clickable buttons (or other informative
+icons), and the look of these can be customized by the user.
+
+@vindex icon-preference
+The main customization point here is the @code{icon-preference} user
+option.  By using this, you can tell Emacs your overall preferences
+for icons.  This is a list of icon types, and the first icon type
+that's supported will be used.  The supported types are:
+
+@table @code
+@item image
+Use an image for the icon.
+
+@item emoji
+Use a colorful emoji for the icon.
+
+@item symbol
+Use a monochrome symbol for the icon.
+
+@item text
+Use a simple text for the icon.
+@end table
+
+In addition, each individual icon can be customized with @kbd{M-x
+customize-icon}, and themes can further alter the looks of the icons.
+
+To get a quick description of an icon, use the @kbd{M-x describe-icon}
+command.
+
 @node Text Scale
 @section Text Scale