From: Eli Zaretskii <eliz@gnu.org>
To: Drew Adams <drew.adams@oracle.com>
Cc: 17362-done@debbugs.gnu.org
Subject: bug#17362: 24.4.50; inconsistent key notation: `ESC' vs `<ESC>'
Date: Tue, 29 Apr 2014 18:17:28 +0300 [thread overview]
Message-ID: <83fvkwmagn.fsf@gnu.org> (raw)
In-Reply-To: <b73bc016-5fd5-4af5-879c-18c14a989a14@default>
> Date: Mon, 28 Apr 2014 08:25:46 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 17362@debbugs.gnu.org
>
> > > Emacs manual: contrast node `Menu Bar' with node `Quitting'. The former
> > > writes `ESC ESC ESC'; the latter writes `<ESC> <ESC> <ESC>'.
> > >
> > > IMO, the former is preferable. (Note that (kbd "ESC") and (kbd "<ESC>")
> > > both act the same, however.)
> >
> > I'd also prefer "ESC" over "<ESC>" but then other strings like
> > "<TAB>", "<SPC>", "<RET>" or "<DEL>" should also be changed
> > accordingly.
>
> Yes, FWIW, IMO they should be. But this bug will be fixed if things are
> made consistent either way.
I made it consistent in the way described below.
> Oh, and BTW there are also inconsistencies for those others, including in
> nodes: `CUA Bindings', `Misc File Ops', `File Conveniences', `Filesets',
> `Speedbar', `Bidirectional Editing', `Other C Commands', `Image Dired',
> `Printing Package', `MS-DOS Printing', `Help Mode', `Rectangles', `Special
> Isearch', `Regexp Search', `Keyboard Macro Step-Edit', `Marks vs Flags',
> `Counting Days', `General Calendar', `HTML Mode', `Windows Keyboard'.
Did this as well.
> [A related bug?: `<DELETE>' in nodes `Hungry Delete', `MS-DOS Keyboard',
> and `Glossary'. Is `<delete>' what is meant here? Likewise, you can
> find occurrences of `<BACKSPACE>' instead of `<backspace>'.]
And this.
Most of the places where I found a need to change the manual, I
decided that using @key (which produces "<FOO>" in Info) was TRT. I
know that Drew and Dani don't like this, but this is how Texinfo
manuals in general and the Emacs manual in particular are written
since day one.
My changes are committed as emacs-24 branch revisions 117028 and
117032.
For the record, here are the guidelines I used to fix this stuff
consistently (if there's a good place to document that, please point
it out):
. Use @key whenever keyboard input references a key whose label or
name is longer than 1 characters, like "TAB" or "Delete". This is
to avoid confusion between pressing a single key and literally
typing "T A B" (3 keys) or "D e l e t e" (6 keys).
. In all other cases, keyboard input typed by the user should be in
@kbd. When a key sequence includes both kinds of input, use @kbd
on the outside and @key inside, as in @kbd{M-x foo @key{RET}}.
(It is harmless to say @kbd{@key{RET}}, but in that case @kbd is
redundant, as it doesn't have any useful effect.
. Key names inside @key should be capitalized as follows:
- If a key has a label, its name should follow the usual
capitalization of the label, as in @key{Alt} or @key{PageUp}.
- If a key does not have a label, its name should be in all caps,
as in @key{TAB} or @key{META}.
- There are 2 exceptions to the last 2 rules, both for historical
reasons:
* @key{BACKSPACE}, although many keyboards have a "Backspace"
label on it.
* @key{ESC}, which is labeled "Esc".
. When the text talks about control characters, such as ^L or ^J,
do _not_ use @key (as in @key{Ctrl-L}), to avoid confusing them
with keystrokes. Instead, use @samp.
next prev parent reply other threads:[~2014-04-29 15:17 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-04-28 14:29 bug#17362: 24.4.50; inconsistent key notation: `ESC' vs `<ESC>' Drew Adams
2014-04-28 14:49 ` Dani Moncayo
2014-04-28 15:25 ` Drew Adams
2014-04-29 15:17 ` Eli Zaretskii [this message]
2014-04-28 15:29 ` Eli Zaretskii
[not found] <<47b1a857-a5d6-4e5a-b8f6-f96f9e201c89@default>
[not found] ` <<CAH8Pv0i8RqY8JpPEurRycUwRp_C1_UZ5NN5MXwW3uQ74kYeQDQ@mail.gmail.com>
[not found] ` <<83fvkxo4kc.fsf@gnu.org>
2014-04-28 15:39 ` Drew Adams
2014-04-28 16:15 ` Eli Zaretskii
[not found] ` <<b73bc016-5fd5-4af5-879c-18c14a989a14@default>
[not found] ` <<83fvkwmagn.fsf@gnu.org>
2014-04-29 15:40 ` Drew Adams
2014-04-29 16:19 ` Eli Zaretskii
[not found] ` <<4294927c-08b3-4c65-83e4-1582e8d0d859@default>
[not found] ` <<838uqom7lm.fsf@gnu.org>
2014-04-29 17:27 ` Drew Adams
2014-04-29 17:51 ` Eli Zaretskii
2014-04-29 21:55 ` Josh
2014-04-29 23:00 ` Drew Adams
2014-04-30 2:55 ` Eli Zaretskii
[not found] ` <<f2425601-bc55-4f33-ba22-5a2045fdf78a@default>
[not found] ` <<8361lsm3b6.fsf@gnu.org>
2014-04-29 18:12 ` Drew Adams
2014-04-29 18:34 ` Eli Zaretskii
[not found] <<e9c40932-a5e6-4e19-ac69-5b656438a555@default>
[not found] ` <<83bnvlo2fh.fsf@gnu.org>
2014-04-28 16:20 ` Drew Adams
[not found] <<c30f764a-5327-47f4-8bf6-ef6ad993518d@default>
[not found] ` <<834n1cm1bx.fsf@gnu.org>
2014-04-29 19:09 ` Drew Adams
2014-04-29 19:20 ` Eli Zaretskii
2014-04-29 19:24 ` Eli Zaretskii
[not found] <<d035db75-bf2f-4a7e-bca3-684f76f17742@default>
[not found] ` <<8338gwlz7v.fsf@gnu.org>
2014-04-29 19:38 ` Drew Adams
2014-04-30 2:51 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83fvkwmagn.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=17362-done@debbugs.gnu.org \
--cc=drew.adams@oracle.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.