Re: master 4d03f70b7f0 1/4: Correct doc strings for x-*-keysym

Re: master 4d03f70b7f0 1/4: Correct doc strings for x-*-keysym

[Eli Zaretskii]

> Auto-Submitted: auto-generated
> Date: Sat, 16 Mar 2024 03:26:54 -0400 (EDT)
> From: Po Lu <luangruo@yahoo.com>
> 
> branch: master
> commit 4d03f70b7f01477a8d72f827ba8b0dabba8c0a61
> Author: Po Lu <luangruo@yahoo.com>
> Commit: Po Lu <luangruo@yahoo.com>
> 
>     Correct doc strings for x-*-keysym
>     
>     * src/xterm.c (syms_of_xterm): Clarify whether x-*-keysym
>     affects the modifier key reported for a keysym or the other way
>     around.
> ---
>  src/xterm.c | 42 ++++++++++++++++++++++--------------------
>  1 file changed, 22 insertions(+), 20 deletions(-)
> 
> diff --git a/src/xterm.c b/src/xterm.c
> index c8a43785564..bebc30c9103 100644
> --- a/src/xterm.c
> +++ b/src/xterm.c
> @@ -32536,38 +32536,40 @@ Android does not support scroll bars at all.  */);
>    DEFSYM (Qreally_fast, "really-fast");
>  
>    DEFVAR_LISP ("x-ctrl-keysym", Vx_ctrl_keysym,
> -    doc: /* Which keys Emacs uses for the ctrl modifier.
> -This should be one of the symbols `ctrl', `alt', `hyper', `meta',
> -`super'.  For example, `ctrl' means use the Ctrl_L and Ctrl_R keysyms.
> -The default is nil, which is the same as `ctrl'.  */);
> +    doc: /* Which modifer value Emacs reports when Ctrl is depressed.
> +This should be one of the symbols `ctrl', `alt', `hyper', `meta', or
> +`super', representing a modifier to be reported in key events with the
> +Ctrl modifier (i.e. the keysym Ctrl_L or Ctrl_R) depressed.  */);
>    Vx_ctrl_keysym = Qnil;

This loses the information about the meaning of the default value of
nil, doesn't it?  This leaves the user who looks at the default value
confused as to what that means.

Also, the "depressed" part at the end of the last sentence is not
right: a modifier reported in a key event cannot be "depressed", it
can only be "set".  Right?

Re: master 4d03f70b7f0 1/4: Correct doc strings for x-*-keysym

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> This loses the information about the meaning of the default value of
> nil, doesn't it?  This leaves the user who looks at the default value
> confused as to what that means.

I'll fix this, thanks.

> Also, the "depressed" part at the end of the last sentence is not
> right: a modifier reported in a key event cannot be "depressed", it
> can only be "set".  Right?

In this context, "depressed" is interchangable with "pressed" or "set,"
I think.  The X Keyboard Extension's preferred nomenclature uses
"depressed."

Re: master 4d03f70b7f0 1/4: Correct doc strings for x-*-keysym

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: emacs-devel@gnu.org
> Date: Sat, 16 Mar 2024 18:43:12 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > This loses the information about the meaning of the default value of
> > nil, doesn't it?  This leaves the user who looks at the default value
> > confused as to what that means.
> 
> I'll fix this, thanks.

Thanks.

> > Also, the "depressed" part at the end of the last sentence is not
> > right: a modifier reported in a key event cannot be "depressed", it
> > can only be "set".  Right?
> 
> In this context, "depressed" is interchangable with "pressed" or "set,"
> I think.  The X Keyboard Extension's preferred nomenclature uses
> "depressed."

Well, "depressed" is confusing when used in the context of talking
about variables and their bits.

Re: master 4d03f70b7f0 1/4: Correct doc strings for x-*-keysym

[Eli Zaretskii]

> Date: Sat, 16 Mar 2024 11:10:35 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> >    DEFVAR_LISP ("x-ctrl-keysym", Vx_ctrl_keysym,
> > -    doc: /* Which keys Emacs uses for the ctrl modifier.
> > -This should be one of the symbols `ctrl', `alt', `hyper', `meta',
> > -`super'.  For example, `ctrl' means use the Ctrl_L and Ctrl_R keysyms.
> > -The default is nil, which is the same as `ctrl'.  */);
> > +    doc: /* Which modifer value Emacs reports when Ctrl is depressed.
> > +This should be one of the symbols `ctrl', `alt', `hyper', `meta', or
> > +`super', representing a modifier to be reported in key events with the
> > +Ctrl modifier (i.e. the keysym Ctrl_L or Ctrl_R) depressed.  */);
> >    Vx_ctrl_keysym = Qnil;
> 
> This loses the information about the meaning of the default value of
> nil, doesn't it?  This leaves the user who looks at the default value
> confused as to what that means.
> 
> Also, the "depressed" part at the end of the last sentence is not
> right: a modifier reported in a key event cannot be "depressed", it
> can only be "set".  Right?

Ping!  I don't see the changes you promised in the current master
branch.

Re: master 4d03f70b7f0 1/4: Correct doc strings for x-*-keysym

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sat, 16 Mar 2024 11:10:35 +0200
>> From: Eli Zaretskii <eliz@gnu.org>
>> Cc: emacs-devel@gnu.org
>> 
>> >    DEFVAR_LISP ("x-ctrl-keysym", Vx_ctrl_keysym,
>> > -    doc: /* Which keys Emacs uses for the ctrl modifier.
>> > -This should be one of the symbols `ctrl', `alt', `hyper', `meta',
>> > -`super'.  For example, `ctrl' means use the Ctrl_L and Ctrl_R keysyms.
>> > -The default is nil, which is the same as `ctrl'.  */);
>> > +    doc: /* Which modifer value Emacs reports when Ctrl is depressed.
>> > +This should be one of the symbols `ctrl', `alt', `hyper', `meta', or
>> > +`super', representing a modifier to be reported in key events with the
>> > +Ctrl modifier (i.e. the keysym Ctrl_L or Ctrl_R) depressed.  */);
>> >    Vx_ctrl_keysym = Qnil;
>> 
>> This loses the information about the meaning of the default value of
>> nil, doesn't it?  This leaves the user who looks at the default value
>> confused as to what that means.
>> 
>> Also, the "depressed" part at the end of the last sentence is not
>> right: a modifier reported in a key event cannot be "depressed", it
>> can only be "set".  Right?
>
> Ping!  I don't see the changes you promised in the current master
> branch.

Oh right, this slipped my mind.  Thanks for the reminder.