master 0aad846 5/6: Merge from origin/emacs-28

[Eli Zaretskii]

branch: master
commit 0aad84639579024f3648f5e39f4285e43976f5ae
Merge: 99a1456 9bdb1d0
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Merge from origin/emacs-28
    
    9bdb1d0 ; * etc/PROBLEMS: Describe a crash in xwidgets due to Bubblew...
    550887c ; * etc/PROBLEMS: Rearrange and update the section about cras...
    c2e3cd6 Clarify "text area of a window" in the documentation
    4e7e78d Improve docstring of kmacro-set-format
---
 doc/lispref/windows.texi |  54 +++++++------
 etc/PROBLEMS             | 202 +++++++++++++++++++++++++----------------------
 lisp/kmacro.el           |  40 ++++++++--
 src/keyboard.c           |   2 +
 4 files changed, 174 insertions(+), 124 deletions(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 9ce185a..d718ac5 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -131,8 +131,8 @@ including for the case where @var{object} is a deleted 
window.
        |______________ Header Line ______________|  | |
      ^ |LS|LM|LF|                       |RF|RM|RS|  | |
      | |  |  |  |                       |  |  |  |  | |
-Window |  |  |  |       Text Area       |  |  |  |  | Window
-Body | |  |  |  |     (Window Body)     |  |  |  |  | Total
+Window |  |  |  |                       |  |  |  |  | Window
+Body | |  |  |  |      Window Body      |  |  |  |  | Total
 Height |  |  |  |                       |  |  |  |  | Height
      | |  |  |  |<- Window Body Width ->|  |  |  |  | |
      v |__|__|__|_______________________|__|__|__|  | |
@@ -145,27 +145,29 @@ Height |  |  |  |                       |  |  |  |  | 
Height
 @end smallexample
 
 @cindex window body
-@cindex text area of a window
 @cindex body of a window
 @cindex window decorations
 @cindex left and right window decorations
 @cindex top and bottom window decorations
-  At the center of that window is the @dfn{text area}, or @dfn{body},
-where the buffer text is displayed.  The text area can be surrounded by
-a series of optional areas which we will call @dfn{window decorations}.
-On the left and right, from innermost to outermost, these are the left
-and right fringes, denoted by LF and RF (@pxref{Fringes}); the left and
-right margins, denoted by LM and RM in the schematic (@pxref{Display
+  At the center of that window is the @dfn{body}, where the buffer
+text is displayed.  The body can be surrounded by a series of optional
+areas which we will call @dfn{window decorations}.  On the left and
+right, from innermost to outermost, these are the left and right
+fringes, denoted by LF and RF (@pxref{Fringes}); the left and right
+margins, denoted by LM and RM in the schematic (@pxref{Display
 Margins}); the left or right vertical scroll bar, only one of which is
-present at any time, denoted by LS and RS (@pxref{Scroll Bars}); and the
-right divider, denoted by RD (@pxref{Window Dividers}).  Together these
-are the window's @dfn{left and right decorations}.
+present at any time, denoted by LS and RS (@pxref{Scroll Bars}); and
+the right divider, denoted by RD (@pxref{Window Dividers}).  Together
+these are the window's @dfn{left and right decorations}.
 
+@cindex text area of a window
   At the top of the window are the tab line and the header line
-(@pxref{Header Lines}).  At the bottom of the window are the horizontal
-scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
-Format}); and the bottom divider (@pxref{Window Dividers}).  Together
-these form the window's @dfn{top and bottom decorations}.
+(@pxref{Header Lines}).  The @dfn{text area} of the window includes
+the header line and the tab line, if they are present in the window.
+At the bottom of the window are the horizontal scroll bar
+(@pxref{Scroll Bars}); the mode line (@pxref{Mode Line Format}); and
+the bottom divider (@pxref{Window Dividers}).  Together these form the
+window's @dfn{top and bottom decorations}.
 
   There are two special areas omitted in the schematic:
 
@@ -818,7 +820,7 @@ that of the root window on that frame.  If @var{window} is 
omitted or
 
 @cindex window body height
 @cindex body height of a window
-The @dfn{body height} of a window is the height of its text area, which
+The @dfn{body height} of a window is the height of its body, which
 does not include any of its top or bottom decorations (@pxref{Basic
 Windows}).
 
@@ -839,9 +841,9 @@ exceed its total height as returned by 
@code{window-total-height}.
 
 @cindex window body width
 @cindex body width of a window
-The @dfn{body width} of a window is the width of its text area, which
-does not include any of its left or right decorations (@pxref{Basic
-Windows}).
+The @dfn{body width} of a window is the width of its body and of the
+text area, which does not include any of its left or right decorations
+(@pxref{Basic Windows}).
 
 Note that when one or both fringes are removed (by setting their width
 to zero), the display engine reserves two character cells, one on each
@@ -1014,8 +1016,8 @@ Normally, the variables @code{window-min-height} and
 is non-@code{nil}, this function ignores @code{window-min-height} and
 @code{window-min-width}, as well as @code{window-size-fixed}.  Instead,
 it considers the minimum height of a window as the sum of its top and
-bottom decorations plus a text area of one line; and its minimum width
-as the sum of its left and right decorations plus a text area of two
+bottom decorations plus the text of one line; and its minimum width
+as the sum of its left and right decorations plus text that takes two
 columns.
 
 If the optional argument @var{pixelwise} is non-@code{nil},
@@ -1355,7 +1357,7 @@ Sizes}).  Thus, it signals an error if splitting would 
result in making
 a window smaller than those variables specify.  However, a
 non-@code{nil} value for @var{size} causes those variables to be
 ignored; in that case, the smallest allowable window is considered to be
-one that has space for a text area one line tall and/or two columns
+one that has space for a text that is one line tall and/or two columns
 wide.
 
 Hence, if @var{size} is specified, it's the caller's responsibility to
@@ -5201,7 +5203,7 @@ window.
 If @var{count} is negative, it scrolls backward instead.  If
 @var{count} is @code{nil} (or omitted), the distance scrolled is
 @code{next-screen-context-lines} lines less than the height of the
-window's text area.
+window's body.
 
 If the selected window cannot be scrolled any further, this function
 signals an error.  Otherwise, it returns @code{nil}.
@@ -5701,8 +5703,8 @@ and its neighbor.
 If the optional argument @var{body} is @code{nil}, this means to
 return the edges corresponding to the total size of @var{window}.
 @var{body} non-@code{nil} means to return the edges of @var{window}'s
-body (aka text area).  If @var{body} is non-@code{nil}, @var{window}
-must specify a live window.
+body.  If @var{body} is non-@code{nil}, @var{window} must specify a
+live window.
 
 If the optional argument @var{absolute} is @code{nil}, this means to
 return edges relative to the native position of @var{window}'s frame.
diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index 1f99ead..95f57e5 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -123,98 +123,6 @@ load-path.
 
 * Crash bugs
 
-** Emacs crashes when running in a terminal, if compiled with GCC 4.5.0
-
-This version of GCC is buggy: see
-
-  https://debbugs.gnu.org/6031
-  https://gcc.gnu.org/bugzilla/show_bug.cgi?id=43904
-
-You can work around this error in gcc-4.5 by omitting sibling call
-optimization.  To do this, configure Emacs with
-
- ./configure CFLAGS="-g -O2 -fno-optimize-sibling-calls"
-
-** Emacs compiled with GCC 4.6.1 crashes on MS-Windows when C-g is pressed
-
-This is known to happen when Emacs is compiled with MinGW GCC 4.6.1
-with the -O2 option (which is the default in the Windows build).  The
-reason is a bug in MinGW GCC 4.6.1; to work around, either add the
-'-fno-omit-frame-pointer' switch to GCC or compile without
-optimizations ('--no-opt' switch to the configure.bat script).
-
-** Emacs crashes in x-popup-dialog.
-
-This can happen if the dialog widget cannot find the font it wants to
-use.  You can work around the problem by specifying another font with
-an X resource--for example, 'Emacs.dialog*.font: 9x15' (or any font that
-happens to exist on your X server).
-
-** Emacs crashes when you use Bibtex mode.
-
-This happens if your system puts a small limit on stack size.  You can
-prevent the problem by using a suitable shell command (often 'ulimit')
-to raise the stack size limit before you run Emacs.
-
-Patches to raise the stack size limit automatically in 'main'
-(src/emacs.c) on various systems would be greatly appreciated.
-
-** Error message 'Symbol’s value as variable is void: x', followed by
-a segmentation fault and core dump.
-
-This has been tracked to a bug in tar!  People report that tar erroneously
-added a line like this at the beginning of files of Lisp code:
-
-   x FILENAME, N bytes, B tape blocks
-
-If your tar has this problem, install GNU tar--if you can manage to
-untar it :-).
-
-** Emacs can crash when displaying PNG images with transparency.
-
-This is due to a bug introduced in ImageMagick 6.8.2-3.  The bug should
-be fixed in ImageMagick 6.8.3-10.  See <URL:https://debbugs.gnu.org/13867>.
-
-** Crashes when displaying GIF images in Emacs built with version
-libungif-4.1.0 are resolved by using version libungif-4.1.0b1.
-Configure checks for the correct version, but this problem could occur
-if a binary built against a shared libungif is run on a system with an
-older version.
-
-** SVG images may be cropped incorrectly with librsvg 2.45 and below.
-Librsvg 2.46 and above have improved geometry code which Emacs is able
-to take advantage of.
-
-** Emacs aborts inside the function 'tparam1'.
-
-This can happen if Emacs was built without terminfo support, but the
-terminal's capabilities use format that is only supported by terminfo.
-If your system has ncurses installed, this might happen if your
-version of ncurses is broken; upgrading to a newer version of ncurses
-and reconfiguring and rebuilding Emacs should solve this.
-
-All modern systems support terminfo, so even if ncurses is not the
-problem, you should look for a way to configure Emacs so that it uses
-terminfo when built.
-
-** Emacs crashes when using some version of the Exceed X server.
-
-Upgrading to a newer version of Exceed has been reported to prevent
-these crashes.  You should consider switching to a free X server, such
-as Xming or Cygwin/X.
-
-** Emacs crashes with SIGSEGV in XtInitializeWidgetClass.
-
-It crashes on X, but runs fine when called with option "-nw".
-
-This has been observed when Emacs is linked with GNU ld but without passing
-the -z nocombreloc flag.  Emacs normally knows to pass the -z nocombreloc
-flag when needed, so if you come across a situation where the flag is
-necessary but missing, please report it via M-x report-emacs-bug.
-
-On platforms such as Solaris, you can also work around this problem by
-configuring your compiler to use the native linker instead of GNU ld.
-
 ** When Emacs is compiled with Gtk+, closing a display kills Emacs.
 
 There is a long-standing bug in GTK that prevents it from recovering
@@ -270,11 +178,27 @@ The relevant bug report is here:
 A workaround is to set XLIB_SKIP_ARGB_VISUALS=1 in the environment
 before starting Emacs, or run Emacs as root.
 
+** Emacs crashes with SIGTRAP when trying to start a WebKit xwidget.
+
+This could happen if the version of WebKitGTK installed on your system
+is buggy, and errors out trying to start a subprocess through
+Bubblewrap sandboxing.  You can avoid the crash by setting the
+environment variables SNAP, SNAP_NAME and SNAP_REVISION, which will
+make WebKit use GLib to launch subprocesses instead.
+
 ** Emacs crashes when you try to view a file with complex characters.
 
 One possible reason for this could be a bug in the libotf or the
 libm17n-flt/m17n-db libraries Emacs uses for displaying complex
-scripts.  Make sure you have the latest versions of these libraries
+scripts.
+
+The easiest and the recommended way of solving these crashes is to
+build Emacs with HarfBuzz as the shaping engine library instead of
+libm17n-flt.  Building with HarfBuzz is the default since Emacs 27.1.
+
+If you must use libm17n-flt, read on.
+
+Make sure you have the latest versions of these libraries
 installed.  If the problem still persists with the latest released
 versions of these libraries, you can try building these libraries from
 their CVS repository:
@@ -322,6 +246,98 @@ element from LD_LIBRARY_PATH before starting emacs proper.
 Or you could recompile Emacs with an -Wl,-rpath option that
 gives the location of the correct libotf.
 
+** Emacs crashes in x-popup-dialog.
+
+This can happen if the dialog widget cannot find the font it wants to
+use.  You can work around the problem by specifying another font with
+an X resource--for example, 'Emacs.dialog*.font: 9x15' (or any font that
+happens to exist on your X server).
+
+** Emacs crashes when you use Bibtex mode.
+
+This happens if your system puts a small limit on stack size.  You can
+prevent the problem by using a suitable shell command (often 'ulimit')
+to raise the stack size limit before you run Emacs.
+
+Patches to raise the stack size limit automatically in 'main'
+(src/emacs.c) on various systems would be greatly appreciated.
+
+** Error message 'Symbol’s value as variable is void: x', followed by
+a segmentation fault and core dump.
+
+This has been tracked to a bug in tar!  People report that tar erroneously
+added a line like this at the beginning of files of Lisp code:
+
+   x FILENAME, N bytes, B tape blocks
+
+If your tar has this problem, install GNU tar--if you can manage to
+untar it :-).
+
+** Emacs crashes when running in a terminal, if compiled with GCC 4.5.0
+
+This version of GCC is buggy: see
+
+  https://debbugs.gnu.org/6031
+  https://gcc.gnu.org/bugzilla/show_bug.cgi?id=43904
+
+You can work around this error in gcc-4.5 by omitting sibling call
+optimization.  To do this, configure Emacs with
+
+ ./configure CFLAGS="-g -O2 -fno-optimize-sibling-calls"
+
+** Emacs compiled with GCC 4.6.1 crashes on MS-Windows when C-g is pressed
+
+This is known to happen when Emacs is compiled with MinGW GCC 4.6.1
+with the -O2 option (which is the default in the Windows build).  The
+reason is a bug in MinGW GCC 4.6.1; to work around, either add the
+'-fno-omit-frame-pointer' switch to GCC or compile without
+optimizations ('--no-opt' switch to the configure.bat script).
+
+** Emacs can crash when displaying PNG images with transparency.
+
+This is due to a bug introduced in ImageMagick 6.8.2-3.  The bug should
+be fixed in ImageMagick 6.8.3-10.  See <URL:https://debbugs.gnu.org/13867>.
+
+** Crashes when displaying GIF images in Emacs built with version
+libungif-4.1.0 are resolved by using version libungif-4.1.0b1.
+Configure checks for the correct version, but this problem could occur
+if a binary built against a shared libungif is run on a system with an
+older version.
+
+** SVG images may be cropped incorrectly with librsvg 2.45 and below.
+Librsvg 2.46 and above have improved geometry code which Emacs is able
+to take advantage of.
+
+** Emacs aborts inside the function 'tparam1'.
+
+This can happen if Emacs was built without terminfo support, but the
+terminal's capabilities use format that is only supported by terminfo.
+If your system has ncurses installed, this might happen if your
+version of ncurses is broken; upgrading to a newer version of ncurses
+and reconfiguring and rebuilding Emacs should solve this.
+
+All modern systems support terminfo, so even if ncurses is not the
+problem, you should look for a way to configure Emacs so that it uses
+terminfo when built.
+
+** Emacs crashes when using some version of the Exceed X server.
+
+Upgrading to a newer version of Exceed has been reported to prevent
+these crashes.  You should consider switching to a free X server, such
+as Xming or Cygwin/X.
+
+** Emacs crashes with SIGSEGV in XtInitializeWidgetClass.
+
+It crashes on X, but runs fine when called with option "-nw".
+
+This has been observed when Emacs is linked with GNU ld but without passing
+the -z nocombreloc flag.  Emacs normally knows to pass the -z nocombreloc
+flag when needed, so if you come across a situation where the flag is
+necessary but missing, please report it via M-x report-emacs-bug.
+
+On platforms such as Solaris, you can also work around this problem by
+configuring your compiler to use the native linker instead of GNU ld.
+
 * Problems when reading or debugging Emacs C code
 
 Because Emacs does not install a copy of its C source code, users
diff --git a/lisp/kmacro.el b/lisp/kmacro.el
index bb41a96..3f492a8 100644
--- a/lisp/kmacro.el
+++ b/lisp/kmacro.el
@@ -260,8 +260,12 @@ Can be set directly via `kmacro-set-format', which see.")
 Interactively, ARG defaults to 1.  With \\[universal-argument], insert
 the previous value of `kmacro-counter', and do not increment the
 current value.
+
 The previous value of the counter is the one it had before
-the last increment."
+the last increment.
+
+See Info node `(emacs) Keyboard Macro Counter' for more
+information."
   (interactive "P")
   (if kmacro-initial-counter-value
       (setq kmacro-counter kmacro-initial-counter-value
@@ -273,7 +277,24 @@ the last increment."
 
 
 (defun kmacro-set-format (format)
-  "Set the format of `kmacro-counter' to FORMAT."
+  "Set the format of `kmacro-counter' to FORMAT.
+
+The default format is \"%d\", which means to insert the number in
+decimal without any padding.  You can specify any format string
+that the `format' function accepts and that makes sense with a
+single integer extra argument.
+
+If you run this command while no keyboard macro is being defined,
+the new format affects all subsequent macro definitions.
+
+If you run this command while defining a keyboard macro, it
+affects only that macro, from that point on.
+
+Do not put the format string inside double quotes when you insert
+it in the minibuffer.
+
+See Info node `(emacs) Keyboard Macro Counter' for more
+information."
   (interactive "sMacro Counter Format: ")
   (setq kmacro-counter-format
        (if (equal format "") "%d" format))
@@ -283,7 +304,10 @@ the last increment."
 
 
 (defun kmacro-display-counter (&optional value)
-  "Display current counter value."
+  "Display current counter value.
+
+See Info node `(emacs) Keyboard Macro Counter' for more
+information."
   (unless value (setq value kmacro-counter))
   (message "New macro counter value: %s (%d)"
            (format kmacro-counter-format value) value))
@@ -291,7 +315,10 @@ the last increment."
 (defun kmacro-set-counter (arg)
   "Set the value of `kmacro-counter' to ARG, or prompt for value if no 
argument.
 With \\[universal-argument] prefix, reset counter to its value prior to this 
iteration of the
-macro."
+macro.
+
+See Info node `(emacs) Keyboard Macro Counter' for more
+information."
   (interactive "NMacro counter value: ")
   (if (not (or defining-kbd-macro executing-kbd-macro))
       (kmacro-display-counter (setq kmacro-initial-counter-value arg))
@@ -305,7 +332,10 @@ macro."
 
 (defun kmacro-add-counter (arg)
   "Add the value of numeric prefix arg (prompt if missing) to `kmacro-counter'.
-With \\[universal-argument], restore previous counter value."
+With \\[universal-argument], restore previous counter value.
+
+See Info node `(emacs) Keyboard Macro Counter' for more
+information."
   (interactive "NAdd to macro counter: ")
   (if kmacro-initial-counter-value
       (setq kmacro-counter kmacro-initial-counter-value
diff --git a/src/keyboard.c b/src/keyboard.c
index 5d4bb6e..aa6a4b9 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -11331,6 +11331,8 @@ The elements of this list correspond to the arguments of
 DEFUN ("posn-at-x-y", Fposn_at_x_y, Sposn_at_x_y, 2, 4, 0,
        doc: /* Return position information for pixel coordinates X and Y.
 By default, X and Y are relative to text area of the selected window.
+Note that the text area includes the header-line and the tab-line of
+the window, if any of them are present.
 Optional third arg FRAME-OR-WINDOW non-nil specifies frame or window.
 If optional fourth arg WHOLE is non-nil, X is relative to the left
 edge of the window.