master ba9ae32: Move the documentation of 'string-glyph-split' to proper place

[Eli Zaretskii]

branch: master
commit ba9ae325e52a46299d914bd021f2200736c6bc85
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Move the documentation of 'string-glyph-split' to proper place
    
    * doc/lispref/strings.texi (Creating Strings): Move the
    description of 'string-glyph-split' from here...
    * doc/lispref/display.texi (Size of Displayed Text): ...to here.
---
 doc/lispref/display.texi | 25 +++++++++++++++++++++++++
 doc/lispref/strings.texi | 22 ++--------------------
 2 files changed, 27 insertions(+), 20 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 884b703..f88f65f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2212,6 +2212,31 @@ selected window.  The value includes the line spacing of 
the line
 (@pxref{Line Height}).
 @end defun
 
+@cindex grapheme cluster
+@defun string-glyph-split string
+When character compositions are in effect, sequence of characters can
+be composed for display to form @dfn{grapheme clusters}, for example
+to display accented characters, or ligatures, or Emoji, or when
+complex text shaping requires that for some scripts.  When that
+happens, characters no longer map in a simple way to display columns,
+and display layout decisions with such strings, such as truncating too
+wide strings, can be a complex job.  This function helps in performing
+suvh jobs: it splits up its argument @var{string} into a list of
+substrings, where each substring produces a single grapheme cluster
+that should be displayed as a unit.  Lisp programs can then use this
+list to construct visually-valid substrings of @var{string} which will
+look correctly on display, or compute the width of any substring of
+@var{string} by adding the width of its constituents in the returned
+list, etc.
+
+For instance, if you want to display a string without the first glyph,
+you can say:
+
+@example
+(apply #'insert (cdr (string-glyph-split string))))
+@end example
+@end defun
+
 When a buffer is displayed with line numbers (@pxref{Display Custom,,,
 emacs, The GNU Emacs Manual}), it is sometimes useful to know the
 width taken for displaying the line numbers.  The following function
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index a9e1105..0914f20 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -248,24 +248,6 @@ equivalent to 0.  Thus, @w{@code{(substring-no-properties
 properties removed.
 @end defun
 
-@defun string-glyph-split string
-Special care has to be taken when handling strings that are meant to
-be displayed.  @code{substring} and friends work on individual
-characters (i.e., code points), but things like emojis are often
-represented by @dfn{grapheme clusters}, which are basically a bunch of
-code points ``glued together'' in various ways.  This function splits
-up strings like that into a list of strings, where each of these
-resulting strings represents a glyph that should be displayed as a
-unit.
-
-For instance, if you want to display a string without the first glyph,
-you can say:
-
-@example
-(apply #'insert (cdr (string-glyph-split string))))
-@end example
-@end defun
-
 @defun concat &rest sequences
 @cindex copying strings
 @cindex concatenating strings
@@ -448,8 +430,8 @@ middle of a character representation.
 This function measures the string length in characters or bytes, and
 thus is generally inappropriate if you need to shorten strings for
 display purposes; use @code{truncate-string-to-width} or
-@code{window-text-pixel-size} instead (@pxref{Size of Displayed
-Text}).
+@code{window-text-pixel-size} or @code{string-glyph-split} instead
+(@pxref{Size of Displayed Text}).
 @end defun
 
 @defun string-lines string &optional omit-nulls