; Improve documentation of 'set-fontset-font'

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

1 files changed, 8 insertions, 0 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