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
txtlmvPaIoaUB.txt
Description: widget.texi patch
--- End Message ---