Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.

Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.

[Eli Zaretskii]

> @@ -111,7 +111,7 @@ Default nil means to write characters above \\177 in octal notation."
>  (defun edit-kbd-macro (keys &optional prefix finish-hook store-hook)
>    "Edit a keyboard macro.
>  At the prompt, type any key sequence which is bound to a keyboard macro.
> -Or, type `\\[kmacro-end-and-call-macro]' or RET to edit the last
> +Or, type `\\[kmacro-end-and-call-macro]' or \\`RET' to edit the last
>  keyboard macro, `\\[view-lossage]' to edit the last 300
>  keystrokes as a keyboard macro, or `\\[execute-extended-command]'
>  to edit a macro by its command name.
> @@ -374,7 +374,7 @@ or nil, use a compact 80-column format."
>  (defun edmacro-mode ()
>    "\\<edmacro-mode-map>Keyboard Macro Editing mode.  Press \
>  \\[edmacro-finish-edit] to save and exit.
> -To abort the edit, just kill this buffer with \\[kill-buffer] RET.
> +To abort the edit, just kill this buffer with \\[kill-buffer] \\`RET'.
>  
>  Press \\[edmacro-insert-key] to insert the name of any key by typing the key.

Stefan, I don't understand this change.  Is it no longer "kosher" to
use RET, TAB, SPC, etc. in our doc strings?  Why do we need to quote
these simple keys?

Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Stefan, I don't understand this change.  Is it no longer "kosher" to
> use RET, TAB, SPC, etc. in our doc strings?  Why do we need to quote
> these simple keys?

It's so they'll be fontified as keystrokes in the *Help* buffer.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Stefan Kangas <stefankangas@gmail.com>,  Stefan Kangas
>  <stefan@marxist.se>,  emacs-devel@gnu.org
> Date: Wed, 22 Jun 2022 16:26:45 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Stefan, I don't understand this change.  Is it no longer "kosher" to
> > use RET, TAB, SPC, etc. in our doc strings?  Why do we need to quote
> > these simple keys?
> 
> It's so they'll be fontified as keystrokes in the *Help* buffer.

I know, but that's not what I asked.

Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Stefan, I don't understand this change.  Is it no longer "kosher" to
> use RET, TAB, SPC, etc. in our doc strings?  Why do we need to quote
> these simple keys?

The reason for fontifying them is consistency, so that keybindings are
always displayed the same in *Help*.

AFAIU, such consistency is important for effective UX design.

Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 22 Jun 2022 22:17:45 +0200
> Cc: Emacs developers <emacs-devel@gnu.org>
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Stefan, I don't understand this change.  Is it no longer "kosher" to
> > use RET, TAB, SPC, etc. in our doc strings?  Why do we need to quote
> > these simple keys?
> 
> The reason for fontifying them is consistency, so that keybindings are
> always displayed the same in *Help*.
> 
> AFAIU, such consistency is important for effective UX design.

Again, that's not what I asked.  I asked whether _all_ references to
these keys in doc strings should be quoted.  If the answer is YES, I
guess that means we will soon see changes to that effect all over the
place in the existing code, and we should comment on patches which
don't do that to tell the contributors to do so.  Right?

Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Again, that's not what I asked.  I asked whether _all_ references to
> these keys in doc strings should be quoted.

If these are keybindings, then yes.  I think we have cases where RET
does not refer to a keybinding.  In such cases, it should not be
tagged.

> If the answer is YES, I
> guess that means we will soon see changes to that effect all over the
> place in the existing code, and we should comment on patches which
> don't do that to tell the contributors to do so.  Right?

I think we should ask contributors to do that, yes.  I'd encourage
everyone to tag keybindings as such with substitute-command-keys when
they run into them.

However, it would be nice if we thought of more clear conventions in
these common cases:

    1. M-x some-prompting-command RET
    2. M-x some-prompting-command some-user-input RET

Should there be a non-fontified space between the command name and RET
in (1) or should they have the same face? Should "some-user-input" in
(2) have the same face as a keybinding, or should we have a separate
face (for example: no face at all by convention) for replies to
prompts?