Improve documentation of string truncation APIs

* doc/lispref/display.texi (Size of Displayed Text):
* lisp/international/mule-util.el (truncate-string-to-width):
Document caveats of using 'truncate-string-to-width' when
character composition is involved.

* lisp/emacs-lisp/subr-x.el (string-limit):
* doc/lispref/strings.texi (Creating Strings): Improve the
documentation of 'string-limit'.

doc/lispref/display.texi

@@ -1997,11 +1997,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.
+The optional argument @var{start-column} specifies the starting
-If this is non-@code{nil}, then the first @var{start-column} columns of
+column; it defaults to zero.  If this is non-@code{nil}, then the
-the string are omitted from the result.  If one multi-column character in
+first @var{start-column} columns of the string are omitted from the
-@var{string} extends across the column @var{start-column}, that
+result.  If one multi-column character in @var{string} extends across
-character is omitted.
+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
@@ -2026,12 +2026,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

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
+If @var{string} is shorter than @var{length} characters, @var{string}
-as is.  Otherwise, return a substring of @var{string} consisting of
+is returned as is.  Otherwise, return a substring of @var{string}
-the first @var{length} characters.  If the optional @var{end}
+consisting of the first @var{length} characters.  If the optional
-parameter is given, return a string of the @var{length} last
+@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
+shorter than @code{length} bytes.  If @var{string} contains characters
-are encoded into several bytes (for instance, when using
+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

lisp/emacs-lisp/subr-x.el

@@ -264,13 +264,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.
+  "Return a substring of STRING that is (up to) LENGTH characters long.
-If STRING is shorter than or equal to LENGTH, the entire string
+If STRING is shorter than or equal to LENGTH characters, return the
-is returned unchanged.
+entire string unchanged.
 
-If STRING is longer than LENGTH, return a substring consisting of
+If STRING is longer than LENGTH characters, return a substring
-the first LENGTH characters of STRING.  If END is non-nil, return
+consisting of the first LENGTH characters of STRING.  If END is
-the last LENGTH characters instead.
+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

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
+column (default: zero); that means to return the characters occupying
-START-COLUMN ... END-COLUMN of STR.  Both END-COLUMN and START-COLUMN
+columns START-COLUMN ... END-COLUMN of STR.  Both END-COLUMN and
-are specified in terms of character display width in the current
+START-COLUMN are specified in terms of character display width in the
-buffer; see also `char-width'.
+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