unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.
@ 2022-06-22 14:05 Eli Zaretskii
  2022-06-22 14:26 ` Lars Ingebrigtsen
  2022-06-22 20:17 ` Stefan Kangas
  0 siblings, 2 replies; 6+ messages in thread
From: Eli Zaretskii @ 2022-06-22 14:05 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: Stefan Kangas, emacs-devel

> @@ -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?



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.
  2022-06-22 14:05 master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes Eli Zaretskii
@ 2022-06-22 14:26 ` Lars Ingebrigtsen
  2022-06-22 15:57   ` Eli Zaretskii
  2022-06-22 20:17 ` Stefan Kangas
  1 sibling, 1 reply; 6+ messages in thread
From: Lars Ingebrigtsen @ 2022-06-22 14:26 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Stefan Kangas, Stefan Kangas, emacs-devel

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



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.
  2022-06-22 14:26 ` Lars Ingebrigtsen
@ 2022-06-22 15:57   ` Eli Zaretskii
  0 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2022-06-22 15:57 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: stefankangas, stefan, emacs-devel

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



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.
  2022-06-22 14:05 master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes Eli Zaretskii
  2022-06-22 14:26 ` Lars Ingebrigtsen
@ 2022-06-22 20:17 ` Stefan Kangas
  2022-06-23  5:43   ` Eli Zaretskii
  1 sibling, 1 reply; 6+ messages in thread
From: Stefan Kangas @ 2022-06-22 20:17 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Emacs developers

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.



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.
  2022-06-22 20:17 ` Stefan Kangas
@ 2022-06-23  5:43   ` Eli Zaretskii
  2022-06-23  9:15     ` Stefan Kangas
  0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2022-06-23  5:43 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: emacs-devel

> 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?



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes.
  2022-06-23  5:43   ` Eli Zaretskii
@ 2022-06-23  9:15     ` Stefan Kangas
  0 siblings, 0 replies; 6+ messages in thread
From: Stefan Kangas @ 2022-06-23  9:15 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Emacs developers

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?



^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2022-06-23  9:15 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-06-22 14:05 master 5b1109394c: ; * lisp/edmacro.el: Minor doc fixes Eli Zaretskii
2022-06-22 14:26 ` Lars Ingebrigtsen
2022-06-22 15:57   ` Eli Zaretskii
2022-06-22 20:17 ` Stefan Kangas
2022-06-23  5:43   ` Eli Zaretskii
2022-06-23  9:15     ` Stefan Kangas

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).