GNU bug report logs - #70502
30.0.50; Widget manual typos etc.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 70502 in the body.
You can then email your comments to 70502 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 30.0.50; Widget manual typos etc.
Date: Sun, 21 Apr 2024 21:42:59 +0200

[Message part 1 (text/plain, inline)]

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

[Message part 2 (text/x-patch, attachment)]

Message #8 received at 70502 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 70502 <at> debbugs.gnu.org
Subject: Re: bug#70502: 30.0.50; Widget manual typos etc.
Date: Mon, 22 Apr 2024 08:31:39 +0300

> 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 <at> 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).

Message #11 received at 70502 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 70502 <at> debbugs.gnu.org
Subject: Re: bug#70502: 30.0.50; Widget manual typos etc.
Date: Mon, 22 Apr 2024 11:39:41 +0200

On Mon, 22 Apr 2024 08:31:39 +0300 Eli Zaretskii <eliz <at> 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 <at> 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

Message #14 received at 70502 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 70502 <at> debbugs.gnu.org
Subject: Re: bug#70502: 30.0.50; Widget manual typos etc.
Date: Mon, 22 Apr 2024 12:53:14 +0300

> From: Stephen Berman <stephen.berman <at> gmx.net>
> Cc: 70502 <at> debbugs.gnu.org
> Date: Mon, 22 Apr 2024 11:39:41 +0200
> 
> On Mon, 22 Apr 2024 08:31:39 +0300 Eli Zaretskii <eliz <at> 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.

Message #19 received at 70502-done <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 70502-done <at> debbugs.gnu.org
Subject: Re: bug#70502: 30.0.50; Widget manual typos etc.
Date: Mon, 22 Apr 2024 11:56:43 +0200

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

>> From: Stephen Berman <stephen.berman <at> gmx.net>
>> Cc: 70502 <at> debbugs.gnu.org
>> Date: Mon, 22 Apr 2024 11:39:41 +0200
>>
>> On Mon, 22 Apr 2024 08:31:39 +0300 Eli Zaretskii <eliz <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.