From: Eli Zaretskii Date: Mon, 5 Oct 2020 05:37:02 +0000 (+0300) Subject: Fix the documentation parts of a recent commit X-Git-Tag: emacs-28.0.90~5748 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c0577d7a39284d05da824906debd28b2be03edf1;p=emacs.git Fix the documentation parts of a recent commit * lisp/international/mule-util.el (truncate-string-ellipsis): Doc fix. * doc/lispref/display.texi (Size of Displayed Text): Improve wording and accuracy of the documentation of 'truncate-string-to-width'. Document the function 'truncate-string-ellipsis'. * etc/NEWS: Improve the wording of the entry for 'truncate-string-to-width'. --- diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index a70f61e43e2..d2e6cad6c45 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1970,37 +1970,45 @@ This function returns the width in columns of the string @var{string}, if it were displayed in the current buffer and the selected window. @end defun -@defun truncate-string-to-width string width &optional start-column padding ellipsis -This function returns the part of @var{string} that fits within -@var{width} columns, as a new string. +@defun truncate-string-to-width string width &optional start-column padding ellipsis ellipsis-text-property +This function returns a new string that is a truncation of @var{string} +which fits within @var{width} columns on display. -If @var{string} does not reach @var{width}, then the result ends where -@var{string} ends. If one multi-column character in @var{string} -extends across the column @var{width}, that character is not included in -the result. Thus, the result can fall short of @var{width} but cannot -go beyond it. +If @var{string} is narrower than @var{width}, the result is equal to +@var{string}; otherwise excess characters are omitted from the result. +If a multi-column character in @var{string} exceeds the goal +@var{width}, that character is omitted from the result. Thus, the +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 value. If one multi-column character in +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 not included. +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 extend -it to exactly @var{width} columns. The padding character is used at the -end of the result if it falls short of @var{width}. It is also used at -the beginning of the result if one multi-column character in +character added at the beginning and end of the result string, to +extend it to exactly @var{width} columns. The padding character is +appended at the end of the result if it falls short of @var{width}, as +many times as needed to reach @var{width}. It is also prepended at +the beginning of the result if a multi-column character in @var{string} extends across the column @var{start-column}. -@vindex truncate-string-ellipsis If @var{ellipsis} is non-@code{nil}, it should be a string which will -replace the end of @var{string} (including any padding) if it extends -beyond @var{width}, unless the display width of @var{string} is equal -to or less than the display width of @var{ellipsis}. If -@var{ellipsis} is non-@code{nil} and not a string, it stands for -the value of the variable @code{truncate-string-ellipsis}, or -to three dots when it's nil. +replace the end of @var{string} when it is truncated. In this case, +more charcaters will be removed from @var{string} to free enough space +for @var{ellipsis} to fit within @var{width} columns. However, if +the display width of @var{string} is less than the display width of +@var{ellipsis}, @var{ellipsis} will not be appended to the result. If +@var{ellipsis} is non-@code{nil} and not a string, it stands for the +value returned by the function @code{truncate-string-ellipsis}, +described below. + +The optional argument @var{ellipsis-text-property}, if non-@code{nil}, +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. @example (truncate-string-to-width "\tab\t" 12 4) @@ -2010,6 +2018,16 @@ to three dots when it's nil. @end example @end defun +@defun truncate-string-ellipsis +This function returns the string to be used as an ellipses in +@code{truncate-string-to-width} and other similar contexts. The value +is that of the variable @code{truncate-string-ellipsis}, if it's +non-@code{nil}, the string with the single character @sc{U+2026 +HORIZONTAL ELLIPSIS} if that character can be displayed on the +selected frame, and the string @samp{...} otherwise. +@end defun + + The following function returns the size in pixels of text as if it were displayed in a given window. This function is used by @code{fit-window-to-buffer} and @code{fit-frame-to-buffer} diff --git a/etc/NEWS b/etc/NEWS index cda4430c81d..d05b706ea34 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1479,10 +1479,10 @@ ledit.el, lmenu.el, lucid.el and old-whitespace.el. * Lisp Changes in Emacs 28.1 +++ -** 'truncate-string-ellipsis' uses the character '…' by default. -Modes that use 'truncate-string-to-width' with non-nil non-string -argument 'ellipsis', now indicate truncation using '…' when -the selected frame can display it, and "..." otherwise. +** 'truncate-string-ellipsis' now uses '…' by default. +Modes that use 'truncate-string-to-width' with non-nil, non-string +argument 'ellipsis', will now indicate truncation using '…' when +the selected frame can display it, and using "..." otherwise. +++ *** New command 'make-directory-autoloads'. diff --git a/lisp/international/mule-util.el b/lisp/international/mule-util.el index d792b2530c4..c757e866981 100644 --- a/lisp/international/mule-util.el +++ b/lisp/international/mule-util.el @@ -50,7 +50,7 @@ Serves as default value of ELLIPSIS argument to `truncate-string-to-width' returned by the function `truncate-string-ellipsis'.") (defun truncate-string-ellipsis () - "Return a string to use to indicate truncation. + "Return the string used to indicate truncation. Use the value of the variable `truncate-string-ellipsis' when it's non-nil. Otherwise, return `…' when it's displayable on the selected frame, or `...'. This function needs to be called on every use of