; Improve documentation of 'string-glyph-split'

* doc/lispref/display.texi (Size of Displayed Text):
* lisp/emacs-lisp/subr-x.el (string-glyph-split): Document a
caveat (bug#79576).

2 files changed, 8 insertions, 1 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index f363b044203..6abbefff7a5 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2459,6 +2459,10 @@ you can say:
 @example
 (apply #'insert (cdr (string-glyph-split string))))
 @end example
+
+Caveat: for this function to recognize and process character
+compositions, @code{auto-composition-mode} must be enabled, and the
+current buffer must be displayed in some window.
 @end defun
 
 When a buffer is displayed with line numbers (@pxref{Display Custom,,,
diff --git a/lisp/emacs-lisp/subr-x.el b/lisp/emacs-lisp/subr-x.el
index 2fa0652bc5c..aa8ef0d4ecc 100644
--- a/lisp/emacs-lisp/subr-x.el
+++ b/lisp/emacs-lisp/subr-x.el
@@ -365,7 +365,10 @@ substring that does not include newlines."
 This takes into account combining characters and grapheme clusters:
 if compositions are enabled, each sequence of characters composed
 on display into a single grapheme cluster is treated as a single
-indivisible unit."
+indivisible unit.
+Caveat: for this function to recognize characters compositions, the
+automatic compositions should be enabled (see `auto-composition-mode')
+and the current buffer must be displayed in some window."
   (declare (side-effect-free t))
   (let ((result nil)
         (start 0)