GNU bug report logs - #68929
[PATCH] Copy which-key from GNU ELPA into core

Previous Next

Full log

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 68929 <at> debbugs.gnu.org, justin <at> burkett.cc, monnier <at> iro.umontreal.ca
Subject: Re: bug#68929: [PATCH] Copy which-key from GNU ELPA into core
Date: Thu, 15 Feb 2024 10:29:03 +0200

> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Cc: Eli Zaretskii <eliz <at> gnu.org>, 68929 <at> debbugs.gnu.org, justin <at> burkett.cc,
>  monnier <at> iro.umontreal.ca, bug-gnu-emacs <at> gnu.org
> Date: Sun, 11 Feb 2024 21:32:44 +0000
> 
> > Eli Zaretskii <eliz <at> gnu.org> writes:
> >
> >> Will the section be very long?  How long?
> >>
> >> If it's not very long, I think the right place is in "Key Help",
> >> perhaps as a separate subsection below it.  Also, I think which-key
> >> should be briefly mentioned in "Display Custom", where echo-keystrokes
> >> is described.
> >>
> >> If the section about which-key you envision is supposed to be long and
> >> detailed, perhaps it would be better to have a separate manual with
> >> all that stuff, whereas the Emacs user manual should have only a short
> >> description of the main features, and a cross-reference to the
> >> separate manual.
> >
> > I would propose to make a new section short enough to belong in the main
> > Emacs manual, as which-key's "keymay discovery" perspective should be
> > easier to find.
> >
> > I can volunteer to write a draft and confer with Justin, the actual
> > author, for completeness.
> 
> Attached are a proposed patch for the Emacs manual, intentionally very
> short.
> Feedback welcome on any aspects.

LGTM, thanks.  Some minor comments below.

> * doc/emacs/display.texi (Display Custom):  brief mention
> * doc/emacs/help.texi (Key Help):  reference node above

The descriptions of the changes in these entries should be complete
sentences: begin with a capital letter and end with a period.

> --- a/doc/emacs/display.texi
> +++ b/doc/emacs/display.texi
> @@ -2215,7 +2215,8 @@ Display Custom
>  default), the multi-character key sequence echo shown according to
>  @code{echo-keystrokes} will include a short help text about keys which
>  will invoke @code{describe-prefix-bindings} (@pxref{Misc Help}) to show
> -the list of commands for the prefix you already typed.
> +the list of commands for the prefix you already typed.  For a related
> +help facility (@pxref{which-key}).

The parentheses here don't look right.  It is better to say

  For a related help facility, see @ref{which-key}.

> +@node which-key

It is better to use

  @anchor which-key

Then you don't need the @subsection at all.

> + @command{M-x which-key} is a global minor mode which helps in

@command is for shell commands.  Here you show something the user
types, so the right markup is @kbd.

Previous Next

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