bug#61183: 29.0.60; Add describe-repeat-maps to the manual

bug#61183: 29.0.60; Add describe-repeat-maps to the manual

[Juri Linkov]

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.
```

bug#61183: 29.0.60; Add describe-repeat-maps to the manual

[Eli Zaretskii]

> From: Juri Linkov <juri@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.

bug#61183: 29.0.60; Add describe-repeat-maps to the manual

[Juri Linkov]

>> +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.

bug#61183: 29.0.60; Add describe-repeat-maps to the manual

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: 61183@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.

bug#61183: 29.0.60; Add describe-repeat-maps to the manual

[Robert Pluim]

>>>>> On Mon, 30 Jan 2023 20:36:28 +0200, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Juri Linkov <juri@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
-- 

bug#61183: 29.0.60; Add describe-repeat-maps to the manual

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Juri Linkov <juri@linkov.net>,  61183@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".

bug#61183: 29.0.60; Add describe-repeat-maps to the manual

[Juri Linkov]

>> >> +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.

bug#61183: 29.0.60; Add describe-repeat-maps to the manual

[Juri Linkov]

>> 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".

bug#61183: 29.0.60; Add describe-repeat-maps to the manual

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: Robert Pluim <rpluim@gmail.com>,  61183@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.