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.