; Improve documentation of 'set-fontset-font'

* doc/lispref/display.texi (Fontsets):
* src/fontset.c (Fset_fontset_font): Doc fix (bug#70993).

2 files changed, 18 insertions, 1 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index c6b29e87b3a..f20064519fc 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4015,6 +4015,14 @@ the charset @code{japanese-jisx0208}:
 (set-fontset-font t 'japanese-jisx0208
                   (font-spec :family "Kochi Gothic"))
 @end smallexample
+
+Note that this function should generally be called from the user's
+init files, and more generally before any of @var{characters} were
+displayed in the current Emacs session.  That's because for some
+scripts, Emacs caches the way they are displayed, and the cached
+information includes the font used for them -- once these characters
+are displayed once, the cached font will continue to be used
+regardless of changes in the fontsets.
 @end defun
 
 @defun char-displayable-p char
diff --git a/src/fontset.c b/src/fontset.c
index 7af6782a37c..4aa2fb7b2c7 100644
--- a/src/fontset.c
+++ b/src/fontset.c
@@ -1499,7 +1499,16 @@ Optional 5th argument ADD, if non-nil, specifies how to add FONT-SPEC
 to the previously set font specifications for CHARACTERS.  If it is
 `prepend', FONT-SPEC is prepended to the existing font specifications.
 If it is `append', FONT-SPEC is appended.  By default, FONT-SPEC
-overwrites the previous settings.  */)
+overwrites the previous settings.
+
+For reliable results, this function should be called before any
+of CHARACTERS were displayed in the current Emacs session.  In
+particular, if some of CHARACTERS are displayed using character
+compositions, those compositions will be cached after they are first
+produced, and the cached values include the font used for displaying
+the composed characters -- calling this function will not affect the
+font recorded in the cache of compositions, thus they will continue
+to be shown using the fonts from before the call.  */)
   (Lisp_Object fontset, Lisp_Object characters, Lisp_Object font_spec,
    Lisp_Object frame, Lisp_Object add)
 {