bug#70502: 30.0.50; Widget manual typos etc.

bug#70502: 30.0.50; Widget manual typos etc.

[Stephen Berman via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 4725 bytes --]

I've noticed a few typos, texinfo markup problems and omissions in two
nodes of the Widget manual.  The attached patch contains possible
corrections, which the rest of this post tries to justify.

The node "Widgets and the Buffer" begins with this entry:

 -- Const: widget-keymap

In wid-edit.el widget-keymap is defined not with defconst but with
defvar, as are all the other widget keymaps except widget-global-map,
which is defined with defvar-local, and is listed right below
widget-keymap in this node as a Variable, not a Const.

The description of widget-keymap continues: "Binds <TAB> and ‘C-<TAB>’
to ‘widget-forward’ and ‘widget-backward’, respectively."  ‘C-<TAB>’ is
a typo, it should be either ‘S-<TAB>’ or ‘M-<TAB>’ (or both; both of
these bindings are listed further down in this node, as are the other
bindings, so maybe they can be omitted here, though the patch keeps
them).

Further down is a table of bindings for editable-field widgets,
beginning with:

‘<C-e>’
      -- Command: widget-end-of-line

Presumably this should be ‘C-e’ like the following entry ‘C-k’.  The
angle brackets are due to the presumably incorrect texinfo markup in
widget.texi: @key{C-e} instead of @kbd{C-e} (or just C-e, since the
table starts with @table @kbd in widget.texi).

‘M-TAB’
      -- Command: widget-complete

This should presumably be ‘M-<TAB>’ like the same key binding in
widget-keymap (for the widget-backward command) mentioned above.  This
is again presumably a texinfo markup mistake in widget.texi: instead of
@kbd{M-TAB} it should be @kbd{M-@key{TAB}} (or just M-@key{TAB}).  In
addition, since the ‘M-<TAB>’ key combination is commonly used in
desktop GUIs to switch focus among the desktop apps, it would be helpful
to mention the equivalent binding ‘C-M-i’.

The next entry is:

‘C-m’
      -- Command: widget-field-activate
          Invoke the editable field at point.

Here it would be helpful to also list the equivalent binding ‘<RET>’.

The immediately following entry begins:

   The following two are commands that can execute widget actions.
‘<RET>’
      -- Command: widget-button-press POS &optional EVENT

First, the introductory text should perhaps be more specific, since this
table is concerned with button widgets as opposed to editable-field
widgets.  Second, an empty line should separate from the table of key
bindings.  Third, as with the preceding binding for
widget-field-activate, it might be helpful to add the equivalent binding
‘C-m’.

The node "Customization" begins by documenting three widget faces as
follows:

 -- Face: widget-field-face
     Face used for other editing fields.

 -- Face: widget-button-face
     Face used for buttons.

 -- User Option: widget-mouse-face
     Face used for highlighting a button when the mouse pointer moves
     across it.

     The default value is ‘highlight’.

The first two mistakenly use the names of variables whose values are the
actual faces names defined with defface in widget.el: `widget-field' and
`widget-button', i.e. "-face" should be omitted.  In addition, in the
documentation of the widget-field face, "other" is a non-sequitur here,
since no other editing fields are mentioned.  In fact, wid-edit.el
defines the face `widget-single-line-field', which is presumably the
"other" type of field; however, that face is not currently used in
wid-edit.el (it's commented out in the definitions of the regexp and
file widgets with the remark: "Doesn't work well with terminating
newline.").

But wid-edit.el defines three other faces that are not documented in the
Widget manual: `widget-documentation', `widget-inactive' and
`widget-button-pressed'.  The patch adds documentation for these.

Finally, the user option `widget-mouse-face' is indeed defined in
wid-edit.el with defcustom; though it's not clear why it is not a
defface, the patch does not change this.


In GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
 3.24.41, cairo version 1.18.0) of 2024-04-21 built on strobelfs
Repository revision: 4773ecb93193495f141e5d60c0c5ded58eaa2c98
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101013
System Description: Linux From Scratch r12.1-41

Configured using:
 'configure 'CFLAGS=-Og -g3' PKG_CONFIG_PATH=/opt/qt5/lib/pkgconfig'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG
LCMS2 LIBSYSTEMD LIBXML2 MODULES NATIVE_COMP NOTIFY INOTIFY PDUMPER PNG
RSVG SECCOMP SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER
WEBP X11 XDBE XIM XINPUT2 XPM GTK3 ZLIB


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: widget.texi patch --]
[-- Type: text/x-patch, Size: 3133 bytes --]

diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi
index f74605c92c0..2e378e86fc7 100644
--- a/doc/misc/widget.texi
+++ b/doc/misc/widget.texi
@@ -760,14 +760,14 @@ Widgets and the Buffer
 contain widgets.

 @cindex widget keybindings
-@defvr Const widget-keymap
+@defvar widget-keymap
 Keymap containing useful bindings for buffers containing widgets.

-Binds @key{TAB} and @kbd{C-@key{TAB}} to @code{widget-forward} and
-@code{widget-backward}, respectively.  It also binds @key{RET} to
-@code{widget-button-press} and @kbd{down-mouse-1} and
+Binds @key{TAB} to @code{widget-forward} and both @kbd{S-@key{TAB}} and
+@kbd{M-@key{TAB}} to @code{widget-backward}.  It also binds @key{RET} to
+@code{widget-button-press} and both @kbd{down-mouse-1} and
 @kbd{down-mouse-2} to @code{widget-button-click}.
-@end defvr
+@end defvar

 There's also a keymap for events that the Widget library doesn't need
 to handle.
@@ -788,8 +788,8 @@ Widgets and the Buffer
 @deffn Command widget-forward &optional count
 Move point @var{count} buttons or editing fields forward.
 @end deffn
-@item @kbd{M-@key{TAB}}
-@itemx @kbd{S-@key{TAB}}
+@item M-@key{TAB}
+@itemx S-@key{TAB}
 @deffn Command widget-backward &optional count
 Move point @var{count} buttons or editing fields backward.
 @end deffn
@@ -805,30 +805,35 @@ Widgets and the Buffer
 are available:

 @table @kbd
-@item @key{C-e}
+@item C-e
 @deffn Command widget-end-of-line
 Move point to the end of field or end of line, whichever is first.
 @end deffn

-@item @kbd{C-k}
+@item C-k
 @deffn Command widget-kill-line
 Kill to end of field or end of line, whichever is first.
 @end deffn

-@item @kbd{M-TAB}
+@item M-@key{TAB}
+@itemx C-M-i
 @deffn Command widget-complete
 Complete the content of the editable field at point.
 @end deffn

-@item @kbd{C-m}
+@item C-m
+@itemx @key{RET}
 @deffn Command widget-field-activate
 Invoke the editable field at point.
 @end deffn
 @end table

-The following two are commands that can execute widget actions.
+The following two commands can execute the action associated with a
+button widget (e.g., a radio button or checkbox):
+
 @table @kbd
 @item @key{RET}
+@itemx C-m
 @findex widget-button-press
 @deffn Command widget-button-press @var{pos} &optional @var{event}
 Invoke the button at @var{pos}, defaulting to point.
@@ -3262,14 +3267,26 @@ Customization
 This chapter is about the customization options for the Widget
 library, for the end user.

-@deffn Face widget-field-face
-Face used for other editing fields.
+@deffn Face widget-documentation
+Face used for documentation text.
+@end deffn
+
+@deffn Face widget-field
+Face used for editable fields.
 @end deffn

-@deffn Face widget-button-face
+@deffn Face widget-button
 Face used for buttons.
 @end deffn

+@deffn Face widget-button-pressed
+Face used for pressed buttons.
+@end deffn
+
+@deffn Face widget-inactive
+Face used for inactive widgets.
+@end deffn
+
 @defopt widget-mouse-face
 Face used for highlighting a button when the mouse pointer moves
 across it.

bug#70502: 30.0.50; Widget manual typos etc.

[Eli Zaretskii]

> Date: Sun, 21 Apr 2024 21:42:59 +0200
> From:  Stephen Berman via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> I've noticed a few typos, texinfo markup problems and omissions in two
> nodes of the Widget manual.  The attached patch contains possible
> corrections, which the rest of this post tries to justify.

Everything you say is correct, and the patch is OK.  Thanks, feel free
to install on the emacs-29 branch (assuming the same problems exist in
this manual there as well).

bug#70502: 30.0.50; Widget manual typos etc.

[Stephen Berman via Bug reports for GNU Emacs, the Swiss army knife of text editors]

On Mon, 22 Apr 2024 08:31:39 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> Date: Sun, 21 Apr 2024 21:42:59 +0200
>> From:  Stephen Berman via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>>
>> I've noticed a few typos, texinfo markup problems and omissions in two
>> nodes of the Widget manual.  The attached patch contains possible
>> corrections, which the rest of this post tries to justify.
>
> Everything you say is correct, and the patch is OK.  Thanks, feel free
> to install on the emacs-29 branch (assuming the same problems exist in
> this manual there as well).

Thanks, done as commit 2a533514929.  The only differences before that
between widget.texi in emacs-29 and master were the recent changes in
commit 91333dacfa1 on master (bug#70413).  Will those differences
prevent merging the new changes in emacs-29 to master?

Steve Berman

bug#70502: 30.0.50; Widget manual typos etc.

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: 70502@debbugs.gnu.org
> Date: Mon, 22 Apr 2024 11:39:41 +0200
> 
> On Mon, 22 Apr 2024 08:31:39 +0300 Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > Everything you say is correct, and the patch is OK.  Thanks, feel free
> > to install on the emacs-29 branch (assuming the same problems exist in
> > this manual there as well).
> 
> Thanks, done as commit 2a533514929.  The only differences before that
> between widget.texi in emacs-29 and master were the recent changes in
> commit 91333dacfa1 on master (bug#70413).  Will those differences
> prevent merging the new changes in emacs-29 to master?

I hope not.  But even if they do, resolving these conflicts is almost
trivial, and is routinely done at merge time.

bug#70502: 30.0.50; Widget manual typos etc.

[Stephen Berman via Bug reports for GNU Emacs, the Swiss army knife of text editors]

On Mon, 22 Apr 2024 12:53:14 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Stephen Berman <stephen.berman@gmx.net>
>> Cc: 70502@debbugs.gnu.org
>> Date: Mon, 22 Apr 2024 11:39:41 +0200
>>
>> On Mon, 22 Apr 2024 08:31:39 +0300 Eli Zaretskii <eliz@gnu.org> wrote:
>>
>> > Everything you say is correct, and the patch is OK.  Thanks, feel free
>> > to install on the emacs-29 branch (assuming the same problems exist in
>> > this manual there as well).
>>
>> Thanks, done as commit 2a533514929.  The only differences before that
>> between widget.texi in emacs-29 and master were the recent changes in
>> commit 91333dacfa1 on master (bug#70413).  Will those differences
>> prevent merging the new changes in emacs-29 to master?
>
> I hope not.  But even if they do, resolving these conflicts is almost
> trivial, and is routinely done at merge time.

Ok, thanks.  So now I'm closing this bug.

Steve Berman