master c30f950: Merge from origin/emacs-28

[Eli Zaretskii]

branch: master
commit c30f95078c0735447c0bf293f2e6f573bc7057a3
Merge: c3499b8 20ebd91
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Merge from origin/emacs-28
    
    20ebd91a73 Improve documentation of string truncation APIs
    3f998a3fc8 * lisp/textmodes/css-mode.el: Fix typo.  (Bug#51488)
---
 doc/lispref/display.texi        | 20 +++++++++++++++-----
 doc/lispref/strings.texi        | 18 ++++++++++++------
 lisp/emacs-lisp/subr-x.el       | 12 ++++++------
 lisp/international/mule-util.el | 13 +++++++++----
 lisp/textmodes/css-mode.el      |  4 ++--
 5 files changed, 44 insertions(+), 23 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index ece0d5d..884b703 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2023,11 +2023,11 @@ If a multi-column character in @var{string} exceeds the 
goal
 result can sometimes fall short of @var{width}, but cannot go beyond
 it.
 
-The optional argument @var{start-column} specifies the starting column.
-If this is non-@code{nil}, then the first @var{start-column} columns of
-the string are omitted from the result.  If one multi-column character in
-@var{string} extends across the column @var{start-column}, that
-character is omitted.
+The optional argument @var{start-column} specifies the starting
+column; it defaults to zero.  If this is non-@code{nil}, then the
+first @var{start-column} columns of the string are omitted from the
+result.  If one multi-column character in @var{string} extends across
+the column @var{start-column}, that character is omitted.
 
 The optional argument @var{padding}, if non-@code{nil}, is a padding
 character added at the beginning and end of the result string, to
@@ -2052,12 +2052,22 @@ means hide the excess parts of @var{string} with a 
@code{display} text
 property (@pxref{Display Property}) showing the ellipsis, instead of
 actually truncating the string.
 
+@group
 @example
 (truncate-string-to-width "\tab\t" 12 4)
      @result{} "ab"
 (truncate-string-to-width "\tab\t" 12 4 ?\s)
      @result{} "    ab  "
 @end example
+@end group
+
+This function uses @code{string-width} and @code{char-width} to find
+the suitable truncation point when @var{string} is too wide, so it
+suffers from the same basic issues as @code{string-width} does.  In
+particular, when character composition happens within @var{string},
+the display width of a string could be smaller than the sum of widths
+of the constituent characters, and this function might return
+inaccurate results.
 @end defun
 
 @defun truncate-string-ellipsis
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 9756e63..7212677 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -414,18 +414,24 @@ will not be shortened.
 @end defun
 
 @defun string-limit string length &optional end coding-system
-If @var{string} is shorter than @var{length}, @var{string} is returned
-as is.  Otherwise, return a substring of @var{string} consisting of
-the first @var{length} characters.  If the optional @var{end}
-parameter is given, return a string of the @var{length} last
+If @var{string} is shorter than @var{length} characters, @var{string}
+is returned as is.  Otherwise, return a substring of @var{string}
+consisting of the first @var{length} characters.  If the optional
+@var{end} parameter is given, return a string of the @var{length} last
 characters instead.
 
 If @var{coding-system} is non-@code{nil}, @var{string} will be encoded
 before limiting, and the result will be a unibyte string that's
-shorter than @code{length}.  If @var{string} contains characters that
-are encoded into several bytes (for instance, when using
+shorter than @code{length} bytes.  If @var{string} contains characters
+that are encoded into several bytes (for instance, when using
 @code{utf-8}), the resulting unibyte string is never truncated in the
 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}).
 @end defun
 
 @defun string-lines string &optional omit-nulls
diff --git a/lisp/emacs-lisp/subr-x.el b/lisp/emacs-lisp/subr-x.el
index 00668d4..9a82fe2 100644
--- a/lisp/emacs-lisp/subr-x.el
+++ b/lisp/emacs-lisp/subr-x.el
@@ -266,13 +266,13 @@ result will have lines that are longer than LENGTH."
     (buffer-string)))
 
 (defun string-limit (string length &optional end coding-system)
-  "Return (up to) a LENGTH substring of STRING.
-If STRING is shorter than or equal to LENGTH, the entire string
-is returned unchanged.
+  "Return a substring of STRING that is (up to) LENGTH characters long.
+If STRING is shorter than or equal to LENGTH characters, return the
+entire string unchanged.
 
-If STRING is longer than LENGTH, return a substring consisting of
-the first LENGTH characters of STRING.  If END is non-nil, return
-the last LENGTH characters instead.
+If STRING is longer than LENGTH characters, return a substring
+consisting of the first LENGTH characters of STRING.  If END is
+non-nil, return the last LENGTH characters instead.
 
 If CODING-SYSTEM is non-nil, STRING will be encoded before
 limiting, and LENGTH is interpreted as the number of bytes to
diff --git a/lisp/international/mule-util.el b/lisp/international/mule-util.el
index 38d29cb..c2f91e7 100644
--- a/lisp/international/mule-util.el
+++ b/lisp/international/mule-util.el
@@ -67,10 +67,15 @@ decide whether the selected frame can display that Unicode 
character."
                                      ellipsis-text-property)
   "Truncate string STR to end at column END-COLUMN.
 The optional 3rd arg START-COLUMN, if non-nil, specifies the starting
-column; that means to return the characters occupying columns
-START-COLUMN ... END-COLUMN of STR.  Both END-COLUMN and START-COLUMN
-are specified in terms of character display width in the current
-buffer; see also `char-width'.
+column (default: zero); that means to return the characters occupying
+columns START-COLUMN ... END-COLUMN of STR.  Both END-COLUMN and
+START-COLUMN are specified in terms of character display width in the
+current buffer; see `char-width'.
+
+Since character composition on display can produce glyphs whose
+width is smaller than the sum of `char-width' values of the
+composed characters, this function can produce inaccurate results
+when used in such cases.
 
 The optional 4th arg PADDING, if non-nil, specifies a padding
 character (which should have a display width of 1) to add at the end
diff --git a/lisp/textmodes/css-mode.el b/lisp/textmodes/css-mode.el
index 9f123dc..e5017a6 100644
--- a/lisp/textmodes/css-mode.el
+++ b/lisp/textmodes/css-mode.el
@@ -305,14 +305,14 @@
     ;; CSS Box Alignment Module Level 3
     ;; (https://www.w3.org/TR/css-align-3/#property-index)
     ("align-content"
-     baseline-position content-distibution overflow-position content-position)
+     baseline-position content-distribution overflow-position content-position)
     ("align-items"
      "normal" "stretch" baseline-position overflow-position self-position)
     ("align-self"
      "auto" "normal" "stretch"
      baseline-position overflow-position self-position)
     ("justify-content" "normal"
-     content-distibution overflow-position content-position "left" "right")
+     content-distribution overflow-position content-position "left" "right")
     ("justify-items"
      "normal" "stretch" baseline-position overflow-position self-position
      "left" "right" "legacy")