Merge from origin/emacs-29

525d05c1b8a Merge branch 'emacs-29' of git.savannah.gnu.org:/srv/git/...
29ef2157116 ; * lisp/textmodes/paragraphs.el: Remove leftover comment.
80c9f491fc8 Update to Org 9.6.7-5-gd1d0c3
735f3700f65 ; * src/character.c (Fstring_width): Fix last change.
bf83fdba9e3 ; * src/character.c (Fstring_width, Fchar_width): Doc fixes.
1198cdb5567 Merge branch 'emacs-29' of git.sv.gnu.org:/srv/git/emacs ...
2b8796eea19 Fix rx wrong-code bug: ranges starting with ^
ba60070b81c Backport: Fix some tree-sitter :match regexps
092a2ecb083 ; * admin/make-tarball.txt: Update based on latest experi...
7b9e83d3cf9 Fix bug#64923
0002d4f3166 Avoid spurious whitespace in the modeline of emacsclient ...
96d52f89444 Fix function help for advised aliases (bug#64797)
71419a60c37 Avoid crashes due to invalid 'mode-line-format'
b2cb6e82160 ; Better documentation of HOME on MS-Windows
54e98b5f9bd ; Clarify documentation of 'server-after-make-frame-hook'
d13029cdcde Avoid crashes under 'which-key-mode'
cb1f7db2490 ; Minor documentation fixes
4a687bcc20d Bump Emacs version

1 files changed, 23 insertions, 13 deletions

diff --git a/src/character.c b/src/character.c
index 9389e1c0098..f4164360f21 100644
--- a/src/character.c
+++ b/src/character.c
@@ -260,8 +260,12 @@ char_width (int c, struct Lisp_Char_Table *dp)
 
 
 DEFUN ("char-width", Fchar_width, Schar_width, 1, 1, 0,
-       doc: /* Return width of CHAR when displayed in the current buffer.
-The width is measured by how many columns it occupies on the screen.
+       doc: /* Return width of CHAR in columns when displayed in the current buffer.
+The width of CHAR is measured by how many columns it will occupy on the screen.
+This is based on data in `char-width-table', and ignores the actual
+metrics of the character's glyph as determined by its font.
+If the display table in effect replaces CHAR on display with
+something else, the function returns the width of the replacement.
 Tab is taken to occupy `tab-width' columns.
 usage: (char-width CHAR)  */)
   (Lisp_Object ch)
@@ -457,20 +461,26 @@ lisp_string_width (Lisp_Object string, ptrdiff_t from, ptrdiff_t to,
 }
 
 DEFUN ("string-width", Fstring_width, Sstring_width, 1, 3, 0,
-       doc: /* Return width of STRING when displayed in the current buffer.
-Width is measured by how many columns it occupies on the screen.
+       doc: /* Return width of STRING in columns when displayed in the current buffer.
+Width of STRING is measured by how many columns it will occupy on the screen.
+
 Optional arguments FROM and TO specify the substring of STRING to
 consider, and are interpreted as in `substring'.
 
-When calculating width of a multibyte character in STRING,
-only the base leading-code is considered; the validity of
-the following bytes is not checked.  Tabs in STRING are always
-taken to occupy `tab-width' columns.  The effect of faces and fonts
-used for non-Latin and other unusual characters (such as emoji) is
-ignored as well, as are display properties and invisible text.
-For these reasons, the results are not generally reliable;
-for accurate dimensions of text as it will be displayed,
-use `string-pixel-width' or `window-text-pixel-size' instead.
+Width of each character in STRING is generally taken according to
+`char-width', but character compositions and the display table in
+effect are taken into consideration.
+Tabs in STRING are always assumed to occupy `tab-width' columns,
+although they might take fewer columns depending on the column where
+they begin on display.
+The effect of faces and fonts, including fonts used for non-Latin and
+other unusual characters, such as emoji, is ignored, as are display
+properties and invisible text.
+
+For these reasons, the results are just an approximation, especially
+on GUI frames; for accurate dimensions of text as it will be
+displayed, use `string-pixel-width' or `window-text-pixel-size'
+instead.
 usage: (string-width STRING &optional FROM TO)  */)
   (Lisp_Object str, Lisp_Object from, Lisp_Object to)
 {