GNU bug report logs - #61183
29.0.60; Add describe-repeat-maps to the manual

Previous Next

Package: emacs;

Reported by: Juri Linkov <juri <at> linkov.net>

Date: Mon, 30 Jan 2023 17:32:02 UTC

Severity: normal

Tags: patch

Found in version 29.0.60

Done: Eli Zaretskii <eliz <at> gnu.org>

Bug is archived. No further changes may be made.

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

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

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#61183; Package emacs. (Mon, 30 Jan 2023 17:32:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Juri Linkov <juri <at> linkov.net>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Mon, 30 Jan 2023 17:32:02 GMT) Full text and rfc822 format available.

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

From: Juri Linkov <juri <at> linkov.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.60; Add describe-repeat-maps to the manual
Date: Mon, 30 Jan 2023 19:19:56 +0200
Tags: patch

This patch adds describe-repeat-maps to the Info manual:

```
diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 2cc45a8805e..849647664b7 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -887,6 +887,7 @@ Repeating
 subsequent @kbd{z} repeats it once again.
 
 @findex repeat-mode
+@findex describe-repeat-maps
 @vindex repeat-exit-key
 @vindex repeat-exit-timeout
   Also you can activate @code{repeat-mode} that temporarily enables a
@@ -895,11 +896,11 @@ Repeating
 @kbd{C-x u C-x u} to undo many changes, @kbd{C-x o o} instead of
 @kbd{C-x o C-x o} to switch several windows, @kbd{C-x @{ @{ @} @} ^ ^
 v v} to resize the selected window interactively, @kbd{M-g n n p p} to
-navigate @code{next-error} matches, and @kbd{C-x ] ] [ [} to navigate
-through pages.  Any other key exits transient mode and then is
-executed normally.  The user option @code{repeat-exit-key} defines an
-additional key to exit this transient mode.  Also it's possible to
-break the repetition chain automatically after some idle time by
-customizing the user option @code{repeat-exit-timeout} to specify the
-idle time in seconds after which this transient mode will be turned
-off.
+navigate @code{next-error} matches, @kbd{C-x ] ] [ [} to navigate
+through pages, and other listed in @code{describe-repeat-maps}.
+Any other key exits transient mode and then is executed normally.  The
+user option @code{repeat-exit-key} defines an additional key to exit
+this transient mode.  Also it's possible to break the repetition chain
+automatically after some idle time by customizing the user option
+@code{repeat-exit-timeout} to specify the idle time in seconds after
+which this transient mode will be turned off.
```




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#61183; Package emacs. (Mon, 30 Jan 2023 18:00:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Juri Linkov <juri <at> linkov.net>
Cc: 61183 <at> debbugs.gnu.org
Subject: Re: bug#61183: 29.0.60; Add describe-repeat-maps to the manual
Date: Mon, 30 Jan 2023 19:59:44 +0200
> From: Juri Linkov <juri <at> linkov.net>
> Date: Mon, 30 Jan 2023 19:19:56 +0200
> 
> This patch adds describe-repeat-maps to the Info manual:

Thanks.

> +navigate @code{next-error} matches, @kbd{C-x ] ] [ [} to navigate
> +through pages, and other listed in @code{describe-repeat-maps}.

"and other commands", I presume?

Also, saying that commands are "listed in" a function sounds
awkwardly; I guess you meant in the window shown by
describe-repeat-maps instead?

And finally, I think this is insufficient to document
describe-repeat-maps, because its output is not very
self-explanatory.  I actually have difficulty understanding what it
wants to tell me.  The heading line says

  A list of keymaps used by commands with the symbol property `repeat-map'

which isn't a user-level information.  This is followed by keymap
names and some bindings in each keymap.  What is the user supposed to
understand from that?  I think we lack some short introductory text
immediately after the heading.  Or maybe the manual should have some
more detailed explanation of what that command shows.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#61183; Package emacs. (Mon, 30 Jan 2023 18:14:02 GMT) Full text and rfc822 format available.

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

From: Juri Linkov <juri <at> linkov.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61183 <at> debbugs.gnu.org
Subject: Re: bug#61183: 29.0.60; Add describe-repeat-maps to the manual
Date: Mon, 30 Jan 2023 20:10:53 +0200
>> +navigate @code{next-error} matches, @kbd{C-x ] ] [ [} to navigate
>> +through pages, and other listed in @code{describe-repeat-maps}.
>
> "and other commands", I presume?

This is what I already tried, but noticed that it's talking about
key sequences.  But "other key sequences" looks awkward too.

> Also, saying that commands are "listed in" a function sounds
> awkwardly; I guess you meant in the window shown by
> describe-repeat-maps instead?

Maybe simply "listed by describe-repeat-maps"?

> And finally, I think this is insufficient to document
> describe-repeat-maps, because its output is not very
> self-explanatory.  I actually have difficulty understanding what it
> wants to tell me.  The heading line says
>
>   A list of keymaps used by commands with the symbol property `repeat-map'
>
> which isn't a user-level information.  This is followed by keymap
> names and some bindings in each keymap.  What is the user supposed to
> understand from that?  I think we lack some short introductory text
> immediately after the heading.  Or maybe the manual should have some
> more detailed explanation of what that command shows.

Its output is easy to understand for anyone who uses this feature
and just wants to check what commands are already supported.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#61183; Package emacs. (Mon, 30 Jan 2023 18:37:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Juri Linkov <juri <at> linkov.net>
Cc: 61183 <at> debbugs.gnu.org
Subject: Re: bug#61183: 29.0.60; Add describe-repeat-maps to the manual
Date: Mon, 30 Jan 2023 20:36:28 +0200
> From: Juri Linkov <juri <at> linkov.net>
> Cc: 61183 <at> debbugs.gnu.org
> Date: Mon, 30 Jan 2023 20:10:53 +0200
> 
> >> +navigate @code{next-error} matches, @kbd{C-x ] ] [ [} to navigate
> >> +through pages, and other listed in @code{describe-repeat-maps}.
> >
> > "and other commands", I presume?
> 
> This is what I already tried, but noticed that it's talking about
> key sequences.  But "other key sequences" looks awkward too.

"Other key sequences" sounds OK to me.

> > Also, saying that commands are "listed in" a function sounds
> > awkwardly; I guess you meant in the window shown by
> > describe-repeat-maps instead?
> 
> Maybe simply "listed by describe-repeat-maps"?

Also works.

> > And finally, I think this is insufficient to document
> > describe-repeat-maps, because its output is not very
> > self-explanatory.  I actually have difficulty understanding what it
> > wants to tell me.  The heading line says
> >
> >   A list of keymaps used by commands with the symbol property `repeat-map'
> >
> > which isn't a user-level information.  This is followed by keymap
> > names and some bindings in each keymap.  What is the user supposed to
> > understand from that?  I think we lack some short introductory text
> > immediately after the heading.  Or maybe the manual should have some
> > more detailed explanation of what that command shows.
> 
> Its output is easy to understand for anyone who uses this feature
> and just wants to check what commands are already supported.

That's not the correct criterion for judging documentation, definitely
not when the manual is concerned.  The manual should be clear enough
to explain the command's effect even to someone who reads about
repeated commands for the first time.

And even if you only consider experienced users, how can a user
understand that these commands support repeating?  Which part(s) of
that buffer say that in terns that are clear enough?  A naïve reader
of the buffer will just see a list of commands and their bindings,
preceded by a sentence whose intent is hard to understand without some
background in Emacs keymaps.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#61183; Package emacs. (Tue, 31 Jan 2023 09:46:02 GMT) Full text and rfc822 format available.

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

From: Robert Pluim <rpluim <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61183 <at> debbugs.gnu.org, Juri Linkov <juri <at> linkov.net>
Subject: Re: bug#61183: 29.0.60; Add describe-repeat-maps to the manual
Date: Tue, 31 Jan 2023 10:45:25 +0100
>>>>> On Mon, 30 Jan 2023 20:36:28 +0200, Eli Zaretskii <eliz <at> gnu.org> said:

    >> From: Juri Linkov <juri <at> linkov.net>
    >> Its output is easy to understand for anyone who uses this feature
    >> and just wants to check what commands are already supported.

    Eli> That's not the correct criterion for judging documentation, definitely
    Eli> not when the manual is concerned.  The manual should be clear enough
    Eli> to explain the command's effect even to someone who reads about
    Eli> repeated commands for the first time.

    Eli> And even if you only consider experienced users, how can a user
    Eli> understand that these commands support repeating?  Which part(s) of
    Eli> that buffer say that in terns that are clear enough?  A naïve reader
    Eli> of the buffer will just see a list of commands and their bindings,
    Eli> preceded by a sentence whose intent is hard to understand without some
    Eli> background in Emacs keymaps.


How about putting something like

If `repeat-mode' is enabled, these keymaps determine which single key 
can be used to repeat a command invoked via a full key sequence.

in the buffer produced by `descripe-repeat-maps'?

Robert
-- 




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#61183; Package emacs. (Tue, 31 Jan 2023 14:08:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: 61183 <at> debbugs.gnu.org, juri <at> linkov.net
Subject: Re: bug#61183: 29.0.60; Add describe-repeat-maps to the manual
Date: Tue, 31 Jan 2023 16:07:05 +0200
> From: Robert Pluim <rpluim <at> gmail.com>
> Cc: Juri Linkov <juri <at> linkov.net>,  61183 <at> debbugs.gnu.org
> Date: Tue, 31 Jan 2023 10:45:25 +0100
> 
>     Eli> And even if you only consider experienced users, how can a user
>     Eli> understand that these commands support repeating?  Which part(s) of
>     Eli> that buffer say that in terns that are clear enough?  A naïve reader
>     Eli> of the buffer will just see a list of commands and their bindings,
>     Eli> preceded by a sentence whose intent is hard to understand without some
>     Eli> background in Emacs keymaps.
> 
> 
> How about putting something like
> 
> If `repeat-mode' is enabled, these keymaps determine which single key 
> can be used to repeat a command invoked via a full key sequence.
> 
> in the buffer produced by `descripe-repeat-maps'?

This text is much better, thanks.  However, it only talks about the
keymaps, whereas the window we pop shows also some key bindings for
each keymap.  The explanatory text should say something about that as
well, I think.  Such an explanation would probably clarify why the
text says "single" in "single key", which currently looks "out of the
blue".




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#61183; Package emacs. (Wed, 01 Feb 2023 18:09:01 GMT) Full text and rfc822 format available.

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

From: Juri Linkov <juri <at> linkov.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61183 <at> debbugs.gnu.org
Subject: Re: bug#61183: 29.0.60; Add describe-repeat-maps to the manual
Date: Wed, 01 Feb 2023 20:06:08 +0200
>> >> +navigate @code{next-error} matches, @kbd{C-x ] ] [ [} to navigate
>> >> +through pages, and other listed in @code{describe-repeat-maps}.
>> >
>> > "and other commands", I presume?
>>
>> This is what I already tried, but noticed that it's talking about
>> key sequences.  But "other key sequences" looks awkward too.
>
> "Other key sequences" sounds OK to me.
>
>> > Also, saying that commands are "listed in" a function sounds
>> > awkwardly; I guess you meant in the window shown by
>> > describe-repeat-maps instead?
>>
>> Maybe simply "listed by describe-repeat-maps"?
>
> Also works.

Pushed.

>> Its output is easy to understand for anyone who uses this feature
>> and just wants to check what commands are already supported.
>
> That's not the correct criterion for judging documentation, definitely
> not when the manual is concerned.  The manual should be clear enough
> to explain the command's effect even to someone who reads about
> repeated commands for the first time.
>
> And even if you only consider experienced users, how can a user
> understand that these commands support repeating?  Which part(s) of
> that buffer say that in terns that are clear enough?  A naïve reader
> of the buffer will just see a list of commands and their bindings,
> preceded by a sentence whose intent is hard to understand without some
> background in Emacs keymaps.

Maybe this should be explained in the docstring of describe-repeat-maps.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#61183; Package emacs. (Wed, 01 Feb 2023 18:10:02 GMT) Full text and rfc822 format available.

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

From: Juri Linkov <juri <at> linkov.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Robert Pluim <rpluim <at> gmail.com>, 61183 <at> debbugs.gnu.org
Subject: Re: bug#61183: 29.0.60; Add describe-repeat-maps to the manual
Date: Wed, 01 Feb 2023 20:06:36 +0200
>> How about putting something like
>>
>> If `repeat-mode' is enabled, these keymaps determine which single key
>> can be used to repeat a command invoked via a full key sequence.
>>
>> in the buffer produced by `descripe-repeat-maps'?
>
> This text is much better, thanks.

Now added to the docstring.

>                                    However, it only talks about the
> keymaps, whereas the window we pop shows also some key bindings for
> each keymap.  The explanatory text should say something about that as
> well, I think.  Such an explanation would probably clarify why the
> text says "single" in "single key", which currently looks "out of the
> blue".




Reply sent to Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility. (Thu, 02 Feb 2023 13:38:02 GMT) Full text and rfc822 format available.

Notification sent to Juri Linkov <juri <at> linkov.net>:
bug acknowledged by developer. (Thu, 02 Feb 2023 13:38:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Juri Linkov <juri <at> linkov.net>
Cc: rpluim <at> gmail.com, 61183-done <at> debbugs.gnu.org
Subject: Re: bug#61183: 29.0.60; Add describe-repeat-maps to the manual
Date: Thu, 02 Feb 2023 15:37:42 +0200
> From: Juri Linkov <juri <at> linkov.net>
> Cc: Robert Pluim <rpluim <at> gmail.com>,  61183 <at> debbugs.gnu.org
> Date: Wed, 01 Feb 2023 20:06:36 +0200
> 
> >> How about putting something like
> >>
> >> If `repeat-mode' is enabled, these keymaps determine which single key
> >> can be used to repeat a command invoked via a full key sequence.
> >>
> >> in the buffer produced by `descripe-repeat-maps'?
> >
> > This text is much better, thanks.
> 
> Now added to the docstring.
> 
> >                                    However, it only talks about the
> > keymaps, whereas the window we pop shows also some key bindings for
> > each keymap.  The explanatory text should say something about that as
> > well, I think.  Such an explanation would probably clarify why the
> > text says "single" in "single key", which currently looks "out of the
> > blue".

Thanks, I've made some further improvements in this and related
documentation.

I think we can now close this bug.




bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Fri, 03 Mar 2023 12:24:09 GMT) Full text and rfc822 format available.

This bug report was last modified 1 year and 26 days ago.

Previous Next


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