From: Eli Zaretskii <eliz@gnu.org>
Date: Tue, 29 Jan 2019 16:28:13 +0000 (+0200)
Subject: Improve documentation of face numbers
X-Git-Tag: emacs-26.1.92~43
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=73508e62459113be4c7c101648afbe541dd18558;p=emacs.git

Improve documentation of face numbers

* doc/lispref/display.texi (Face Functions): Mention where the
face number is used and that it depends on the 'face' property
of the face symbol.  Improve indexing.
---

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index b3ce7fbf6af..921d58a1f3a 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3038,10 +3038,17 @@ value, which inherits from @var{face}'s global definition.
 This function returns a list of all defined face names.
 @end defun
 
+@cindex face number
+@cindex face property of face symbols
 @defun face-id face
 This function returns the @dfn{face number} of face @var{face}.  This
 is a number that uniquely identifies a face at low levels within
 Emacs.  It is seldom necessary to refer to a face by its face number.
+However, functions that manipulate glyphs, such as
+@code{make-glyph-code} and @code{glyph-face} (@pxref{Glyphs}) access
+the face numbers internally.  Note that the face number is stored as
+the value of the @code{face} property of the face symbol, so we
+recommend not to set that property of a face to any value of your own.
 @end defun
 
 @defun face-documentation face