procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
* 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.
This commit is contained in:
Eli Zaretskii 2021-10-30 20:29:40 +03:00
parent a0fb3939ab
commit ba9ae325e5
2 changed files with 27 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
doc/lispref/display.texi
View file

@ -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

22
doc/lispref/strings.texi
View file

@ -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