; Improve documentation of 'set-fontset-font'

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

(cherry picked from commit 3dd09516c9a87f663fefde77befb7d569cbed9f0)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 2bfcdd1716bc7bcd5bd895c6d4399db149128597..59e1f5cd2f288a2e99e125e4a3b4bb5aa0ab00a0 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4051,6 +4051,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 bac0411995739eea156836658a483cc411260edb..9e914abc1ffa9600a2b475f23a64bd1f1ab0121f 100644 (file)
--- a/src/fontset.c
+++ b/src/fontset.c
@@ -1528,7 +1528,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)
 {