Merge from origin/emacs-26

b94d767 (origin/emacs-26) Minor copyedits in last manual change
73508e6 Improve documentation of face numbers
bf235ce * doc/emacs/custom.texi (Authentication): Refer to the "Help ...
ceccb3c New node Authentication in the Emacs manual
9078f34 Fix a loop in c-fl-decl-start.  This fixes bug #34186.
a177fe7 Fix LaTeX output of month and day from cal-tex.el
90177d7 Avoid elisp crash for OpenPGP User IDs with no e-mail address
68e55a0 image-mode: Do not use default scaling (bug#33990)
b6c762a create-image: Expand documentation (bug#33990)
928d342 Improve documentation of 'isearch-filter-predicate'
9034dd6 Fix cursor column positioning on Grep hits

# Conflicts:
#	doc/emacs/custom.texi

1 files changed, 7 insertions, 0 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 350b3108715..95379b342b3 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3079,10 +3079,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