drew.adams@oracle.com: bug in read-kbd-macro

drew.adams@oracle.com: bug in read-kbd-macro

[Richard Stallman]

Would someone please DTRT and ack?

------- Start of forwarded message -------
From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-pretest-bug@gnu.org>
Date: Sun, 24 Sep 2006 00:47:27 -0700
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
In-Reply-To: <EIENLHALHGIMHGDOLMIMIEIPCLAA.drew.adams@oracle.com>
Subject: RE: single-key-description no good for Japanese and Chinese chars
X-Spam-Status: No, score=0.0 required=5.0 tests=none autolearn=failed 
	version=3.0.4

I ran across this issue/question. I don't know know if it is a bug or not.
If not, perhaps someone has a suggestion of how to deal with it.

I have strings that name keys in keymaps (from map-keymap). Some are prefix
keys. Examples: "C-x", "modeline", "f1".

I use `read-kbd-macro' with the string name as first arg and t as the
second, NEED-VECTOR arg. Example: "C-x" gives [24].

If the binding of the key is a keymap, so the key is a prefix key, then I
concatenate the current prefix-key name (e.g. [] for global) with the key
name: (vconcat prefix key). Example, when using map-keymap over the
global-map, the prefix is [] and, for key [24] this gives [24].

This works fine for prefix keys that are not names, but it does not work for
named prefix keys, such as `mode-line' and `f1'. The reason is that
(read-kbd-macro "mode-line" t) does not return [mode-line]; it returns the
equivalent of "mode-line", that is, a vector of characters: [109 111 100 101
45 108 105 110 101].

When I try to look up accessible-keymaps of that prefix, I obviously get
none. That is, whereas (accessible-keymaps (current-global-map) [mode-line])
would work, the call generated is instead (accessible-keymaps
(current-global-map) "mode-line"), or, more exactly, (accessible-keymaps
(current-global-map) [109 111 100 101 45 108 105 110 101]), which fails.

The first question is whether this is a bug: should (read-kbd-macro
"mode-line" t) return [mode-line]?

If not, I guess I'll need some other way to convert names to vector keys for
the prefix keys. Suggestions? If I knew that a given prefix-key name was a
"named" prefix key (as opposed to a control key name, for instance), then
instead of using `read-kbd-macro' I would use just (vector (intern key)).
That is, I'd use `read-kbd-macro' for "C-x" but (vector (intern
"mode-line")). Anyone know how to make such a distinction?

To complicate things, I see that (read-kbd-macro "<mode-line>"), with or
without the second arg, returns [mode-line]. However, I use key names
without angle brackets (because they are much more readable), and, again, I
don't know how to distinguish the named keys, to add back the angle brackets
internally, just for `read-kbd-macro'.

I thought also of trying to use `kbd' on the key name, hoping that might
help, but (kbd "mode-line") also gives "mode-line". I wonder too if that
might be a bug.

Yes, if I use angle-bracketed key names (strings), then the problem does not
arise, but I really don't want to do that, as it is a zillion times less
readable. Here is a sample of the *Completions* buffer in each style, to
show what I mean:

Without angle brackets:

C-M-S-backspace  =  copy-to-register
C-M-S-delete  =  append-to-register
C-M-S-f1  =  rename-buffer         C-M-S-insert  =  insert-file
C-M-backspace  =  backward-kill-sexp
C-M-delete  =  kill-sexp           C-M-down  =  enlarge-frame
C-M-down-mouse-1  =  mouse-drag-secondary
C-M-drag-mouse-1  =  mouse-set-secondary
C-M-end  =  end-of-defun           C-M-f1  =  font-lock-fontify-buffer
C-M-home  =  beginning-of-defun    C-M-insert  =  lisp-complete-symbol
C-M-left  =  shrink-frame-horizontally

With angle brackets:

<C-M-S-backspace>  =  copy-to-register
<C-M-S-delete>  =  append-to-register
<C-M-S-f1>  =  rename-buffer       <C-M-S-insert>  =  insert-file
<C-M-backspace>  =  backward-kill-sexp
<C-M-delete>  =  kill-sexp         <C-M-down-mouse-1>  =
mouse-drag-secondary
<C-M-down>  =  enlarge-frame       <C-M-drag-mouse-1>  =
mouse-set-secondary
<C-M-end>  =  end-of-defun         <C-M-f1>  =  font-lock-fontify-buffer
<C-M-home>  =  beginning-of-defun  <C-M-insert>  =  lisp-complete-symbol
<C-M-left>  =  shrink-frame-horizontally

The effect is even worse when other keys that don't have angle brackets are
in the list. For example, C-d has no angle brackets, but <C-left> does.
Users don't think of these as being very different, but a simple sort of
*Completions* puts them very far apart. You can see from the snippets above
that the order is changed even among the same set of keys that take angle
brackets, because ">" is sorted after "-": `C-M-down' appears after
`C-M-down-mouse-1' when angle brackets are present.

Thx for any suggestions.

[BTW, the doc string of `read-kbd-macro' is a bit confusing, but the manual
is clear. The doc string names the args START &optional END, but it then
speaks of the possibility of a "single string argument" and a "second
argument NEED-VECTOR" for Lisp calls. This is correct, but it could perhaps
be worded better.]





_______________________________________________
emacs-pretest-bug mailing list
emacs-pretest-bug@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug
------- End of forwarded message -------

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Chong Yidong]

> From: "Drew Adams" <drew.adams@oracle.com>
>
> The first question is whether this is a bug: should (read-kbd-macro
> "mode-line" t) return [mode-line]?

I don't think so; as the lispref documentation for read-kbd-macro
says, it is roughly an inverse of `key-description', and

 M-: (key-description [mode-line]) RET

  ==> "<mode-line>"

> To complicate things, I see that (read-kbd-macro "<mode-line>"), with or
> without the second arg, returns [mode-line].

This is correct.

I think we should close this bug.

RE: drew.adams@oracle.com: bug in read-kbd-macro

[Drew Adams]

    > The first question is whether this is a bug: should (read-kbd-macro
    > "mode-line" t) return [mode-line]?

    I don't think so; as the lispref documentation for read-kbd-macro
    says, it is roughly an inverse of `key-description', and

     M-: (key-description [mode-line]) RET ==> "<mode-line>"

    > To complicate things, I see that (read-kbd-macro "<mode-line>"),
    > with or without the second arg, returns [mode-line].

    This is correct.

Yes, I already said that that part was correct. The problem is for
unbracketed descriptions, as I indicated.

    I think we should close this bug.

I disagree, on two counts -

1. There was also a suggestion in the bug report to improve the doc string
of `read-kbd-macro'. The description of the arguments in the two cases of
interactive and Lisp use is confusing. This is independent of the rest of
the bug report.

2. The bug reported is not about the behavior when angle brackets are
included. There is no bug in that case, as I stated, so there is no sense
citing that case as evidence that there is no bug. The bug is about the
behavior when angle brackets are not used in the key description. Key
descriptions need not have angle brackets, and `read-kbd-macro' should
handle that case also.

(And, yes, read-kbd-macro should be an inverse of key-description.)

Angle-bracket notation is, at least in some contexts, highly UNreadable. I
gave two examples showing why angle brackets can be unhelpful. One was
simply the different treatment of `C-d' and `<C-left>', which users don't
think of as being significantly different types of critter (Occam's razor).
A UI that refers to them both without angle brackets is more readable in
many contexts. The other example concerned the sort order of key names,
which is thrown off by `>', so, for instance, `<C-M-down-mouse-1>' appears
before, not after, `<C-M-down>' alphabetically.

The larger point is that applications should be able to use either external
key-description notation (with or without <>) easily - the Lisp functions
that produce and consume such descriptions shouldn't make it hard to use
either notation.

It's very good that we have a `no-angle' option to `single-key-description'.
What's needed, I think, is a `no-angle' option for `key-description' and
`read-kbd-macro' also, so users can control the external key representation
format to be used (bracketed or not). Then, we would have the following
(only the * are new):

*1. (key-description [mode-line] 'no-angles) => "mode-line"
 2. (single-key-description 'mode-line 'no-angles) => "mode-line"
*3. (read-kbd-macro "mode-line" t 'no-angles) => [mode-line]

 4. (key-description [mode-line]) => "<mode-line>"
 5. (single-key-description 'mode-line) => "<mode-line>"
 6. (read-kbd-macro "<mode-line>" t) => [mode-line]

We already have everything except #1 and #3. In Emacs 20, we already had the
result of #1, but for #4, so #1 must be feasible to implement.

---

BTW, some other problems with key notation -

1. The Emacs manual does not use the notation <next>; it uses <NEXT>. Is
this the right thing? The Lisp functions that provide key descriptions
produce <next>, not <NEXT>.

2. The Emacs manual's treatment of <NEXT>, <F10>, etc. is on a par with its
treatment of <CTRL>, <META>, <ALT>, and <SHIFT>, which I don't think are
possible outputs of the key-description functions, not being complete keys.

I wonder what the manual convention is, and whether it needs to fit what the
key-description functions return. Shouldn't we distinguish things such as
<META> from things such as <next>?

3. I personally think `next' and `f10' are clearer than <NEXT> and <F10>,
and they are more consistent with, say, `C-x' and `b'. The only possible
confusion is between a multiple-key sequence such as `f 10' or `f 1 0'
(assuming `f' and `f 1' are prefix keys) and a key sequence such as `f10',
and I think we already have the convention of using spaces to distinguish
these.

Do we have any key names that contain spaces, so that angle-bracket notation
would actually add something important? I don't know of any. If we did,
then, yes, `<foo bar> 5' is unambiguous, whereas `foo bar 5' could be
ambiguous. In that case alone, we might use brackets.

4. If we do change the manual convention along the lines I suggest, we might
want to reconsider things like <SPC> (which would become `SPC' by my
suggestion) and <RET>. Is there any good reason for these to be uppercase?
How about just `spc' and `ret' (and `tab' etc.)?

5. I note too that `describe-key' shows SPC, RET, and DEL, not <SPC>, <RET>,
and <DEL>, in *Help*. And keystroke echoing shows ESC, not <ESC>. These
usages are thus also inconsistent with what is in the Emacs manual (<SPC>,
<RET>, and <DEL>).

6. The manual writes `M-<RET>', not <M-RET> - 1) quotes are used, in
addition to angle brackets; and 2) the angle brackets don't surround the
modifier. As someone else recently pointed out, the angle-bracket notation
used by the key-description functions puts the modifier inside the brackets
(e.g. <S-tab>). So, here is another inconsistency between the manual and the
description functions. (I imagine that the quotes were added because of the
presence of the modifier.)

I tend to agree with the other writer, BTW, that S-<tab> is more readable
than <S-tab>, but we should at least be consistent. Again, to me, the most
readable is `S-tab' (or S-tab, in some contexts); the angle brackets add
nothing but noise, wherever they are placed.

7. Is it correct that the manual uses `M-<PAGEUP>' and not `M-<PRIOR>' (or
<M-prior>)? This also seems to be a source of confusion.


Summary:

1. Key-description producing and consuming functions should be able to use
both syntaxes: with and without angle brackets.

2. It would be good for the UI, the manual, and the output from the
key-description functions to all be on the same page wrt key notation.

3. IMO, `keyname' is almost always clearer than <keyname>, <KEYNAME>, and
`<KEYNAME>'.  I'd like to see us use that in both the UI and the manual.
Similarly, `M-keyname' is clearer than `M-<keyname>' and <M-keyname>.


[To be explicit: I'm not proposing any such changes before the release. But
some of the bugs (e.g. doc string of `read-kbd-macro') could perhaps be
fixed before then.]

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> Angle-bracket notation is, at least in some contexts, highly UNreadable.

I don't think this is serious enough to warrant working on, so close
to release.

RE: drew.adams@oracle.com: bug in read-kbd-macro

[Drew Adams]

    > Angle-bracket notation is, at least in some contexts, highly
    > UNreadable.

    I don't think this is serious enough to warrant working on, so close
    to release.

Please read what I wrote - for example, this:

  [To be explicit: I'm not proposing any such changes before the
  release. But some of the bugs (e.g. doc string of `read-kbd-macro')
  could perhaps be fixed before then.]

What's the use of my adding an explicit note (and even pointing out that I'm
adding an explicit note, to avoid misinterpretation), if you don't read what
I write? There's no sense replying hastily to something you haven't read.

As Kim noted, a release need not try to be bug-free, and it won't be
bug-free even it tries. These are, IMO, bugs, but they need not be fixed
before the release.

Apparently, you and I are in violent agreement, for once - at least about a
part you seem not to have read ;-).

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Johan Bockgård]

"Drew Adams" <drew.adams@oracle.com> writes:

> 1. The Emacs manual does not use the notation <next>; it uses
> <NEXT>. Is this the right thing? The Lisp functions that provide key
> descriptions produce <next>, not <NEXT>.

The manual is written in English, not Lisp. Here's how it looks in the
printed version (look ma, no angle brackets):

http://www.dd.chalmers.se/~bojohan/emacs/img/keys.png

(The Texinfo manual says that this notation refers to "a name for a
key on a keyboard".)

-- 
Johan Bockgård

RE: drew.adams@oracle.com: bug in read-kbd-macro

[Drew Adams]

    > 1. The Emacs manual does not use the notation <next>; it uses
    > <NEXT>. Is this the right thing? The Lisp functions that provide key
    > descriptions produce <next>, not <NEXT>.
    
    The manual is written in English, not Lisp. Here's how it looks in the
    printed version (look ma, no angle brackets):    
    http://www.dd.chalmers.se/~bojohan/emacs/img/keys.png    
    (The Texinfo manual says that this notation refers to "a name for a
    key on a keyboard".)
    
1. It's useful to have the UI notation (everywhere) and the manual notation be the same, in general. It is a hindrance to have them different.

2. It's useful to have the same notation for both online and printed manual, in general.

3. It's useful to use the same notation convention for all key sequences. It misleads to write `a' and `]' one way and `prior' another way (<PRIOR>).

4. `prior' is much more readable than the kind of notation shown in your screenshot. Frankly, that looks like someone's first half-day playing with PowerPoint or Word, a hangover from font binging. After a few pages dense with key and key-sequence descriptions, that begins to nauseate. 

5. I pointed out additional inconsistencies.

6. <S-tab>, `S-<tab>', S-<tab>, `S-TAB', and S-TAB are _not_ names of keys on a keyboard. They are descriptions of key _sequences_.

7. CTRL, META, ALT, and so on, might be names of keys on many keyboards, but they are not names of key sequences. A different notation for these keyboard keys is OK. When used in the context of key sequences, the notation `C-' and `M-' is preferable (yes, the relation between META and `M-' is not obvious, and the same is true for CTRL and `C-').

8. This has nothing to do with Lisp vs English. We are talking about English communication here - in both UI and manual. I mentioned those Lisp functions because they are what a programmer uses to extend the UI (e.g. help, messages). So, it is that notation that users see in the UI as it is extended by user libraries. The point about Lisp is that the notation that programmers display to users should be the same as the notation shown to users elsewhere in the UI and in the manual.

[Again, I'm not proposing correcting this before the release.]

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 26 Sep 2006 08:02:07 -0700
> 
> 1. It's useful to have the UI notation (everywhere) and the manual notation be the same, in general. It is a hindrance to have them different.

The manual notation for a certain key should be the same, anything
else is a bug that should be reported and fixed.  For example, the
`next' key should be spelled as @key{NEXT} everywhere in the manual's
text, and produce "<NEXT>" in the Info format.

> 2. It's useful to have the same notation for both online and printed manual, in general.

Given how @key is typeset in the printed version, this is clearly
impossible, except in the graphics session of Emacs, and then only if
we hide the text of the Info file and show some image in its stead.
Given our quite negative experience with hiding parts of the Info
text, I'd say it's unwise to go that way in this case.

> 3. It's useful to use the same notation convention for all key sequences. It misleads to write `a' and `]' one way and `prior' another way (<PRIOR>).

There's a method to this, which should probably be explained better in
the Texinfo manual than it is now: <PRIOR> (produced by @key) is used
to distinguish it from the sequence of letters P, R, I, O, R.  That
is, @key is for those cases where you mean a single key labeled with a
name, and where, were you to say `PRIOR', the reader could have
confused that to think she should type the above sequence of
characters one after the other, instead of pressing a single key.

> 4. `prior' is much more readable than the kind of notation shown in
> your screenshot.

I disagree.  FWIW, I never heard anyone complaining about how Texinfo
typesets @key.  YMMV, of course.

> Frankly, that looks like someone's first half-day playing with PowerPoint or Word, a hangover from font binging. After a few pages dense with key and key-sequence descriptions, that begins to nauseate. 

A wild exaggeration, IMHO.  This has been like that for ages.  Of
course, if you wish to submit a change to texinfo.tex to make it look
prettier, please do.

> 6. <S-tab>, `S-<tab>', S-<tab>, `S-TAB', and S-TAB are _not_ names of keys on a keyboard. They are descriptions of key _sequences_.

I think they should be written as @code{S-@key{TAB}} and appear as
`S-<TAB>', and the other variants are in error.

> 7. CTRL, META, ALT, and so on, might be names of keys on many keyboards, but they are not names of key sequences.

They are the names of keys.  When the manual talks about them as
separate keys, it should use @key, yielding <CTRL>, <META>, etc.  When
it describes them as modifiers of other keys, they should be in @code
or @samp and appear as C-, M-, etc.  I believe anything else is again
an error in the manual that should fixed.

RE: drew.adams@oracle.com: bug in read-kbd-macro

[Drew Adams]

    > 1. It's useful to have the UI notation (everywhere) and the
    manual notation be the same, in general. It is a hindrance to
    have them different.
    
    The manual notation for a certain key should be the same,
    anything else is a bug that should be reported and fixed.
    For example, the `next' key should be spelled as @key{NEXT}
    everywhere in the manual's text, and produce "<NEXT>" in the
    Info format.

The UI notation is not the same as the manual notation. That was
what this point (#1) is about: UI != manual.  You, I think, are
speaking of consistency within the manual.  My point was that the
manual writes `S-<TAB>' (including the quotes) but the UI writes
<S-tab>.  That is the inconsistency pointed out in #1.

This is not the end of the world, of course, but why not use the
same notation everywhere?  What would we lose by being consistent
in that way?  If both notations are unambiguous and clear, then
let's pick just one and stick to it everywhere.  Occam would like
us to.

[FWIW - I suspect the reason the manual notation is different
from the UI might be because someone opted for key images in the
printed manual (see #2), and those images already stood for the
angle-bracket notation of keys (e.g. <TAB>), so there was no way
to add modifiers, other than to put them "outside" the angle
brackets implicit in the printed image.  

That is, once you've replaced <TAB> with an image, adding `S-' to
that can only produce S-image, which translates to S-<TAB>, not
<S-tab>, for the online manual (and someone decided to add quotes
for extra beauty: `S-<TAB>').  Putting the modifier in the image
itself would presumably have violated the idea that the image
stood for a keyboard key - <S-tab> is not a keyboard key.

If I'm right about this, it means that the decision to use a
different notation in print (images) vs on line (angle brackets)
ended up also producing a notation difference between the manual
(both online and print) and the UI.  Dommage.]
    
    > 2. It's useful to have the same notation for both online
    and printed manual, in general.
    
    Given how @key is typeset in the printed version, this is
    clearly impossible, except in the graphics session of Emacs,
    and then only if we hide the text of the Info file and show
    some image in its stead.

No; it is possible.  Just do the opposite: bring the printed
version into line with the online version, even the non-graphic
(i.e. console) version, by using `next' for both.  Or, if you
don't like my suggestion to use quotes instead of angle brackets,
use <next> (or even <NEXT>, but without the image stuff) for
both.

The point is to use the same thing for both, and if one of them
is too fancy for the other medium, then that is obviously not the
one to try to use for both ;-).

    Given our quite negative experience with hiding parts of the
    Info text, I'd say it's unwise to go that way in this case.

Yes, no need to go there. This is not that complicated.

To be clear, point #2 is not very important, as long as the
printed manual explains its special typographical convention and
explicitly introduces the standard notation (that is, the
notation used for the UI).  IOW, it's OK to use a special
notation in the printed manual, but the real thing for users to
learn is the standard notation, the one they will encounter when
using Emacs.

I personally don't think we gain anything by using a special
typographical convention in the printed manual (especially one as
ugly as what we have now), but I want to be clear that if we do,
then we should at least point that out and present the standard
(that is, the UI) notation explicitly: <S-tab>, not `S-<TAB>'.
(Perhaps we do already; I didn't check.)
    
    > 3. It's useful to use the same notation convention for all
    key sequences. It misleads to write `a' and `]' one way and
    `prior' another way (<PRIOR>).
    
    There's a method to this, which should probably be explained
    better in the Texinfo manual than it is now: <PRIOR>
    (produced by @key) is used to distinguish it from the
    sequence of letters P, R, I, O, R.  That is, @key is for
    those cases where you mean a single key labeled with a name,
    and where, were you to say `PRIOR', the reader could have
    confused that to think she should type the above sequence of
    characters one after the other, instead of pressing a single
    key.

I explained (in the part that you omitted) that separation by
spaces (e.g. `p r i o r' vs `prior') is an alternative convention
for a key sequence, which disambiguates the two just as well, and
it is also used in the manual (and in the UI) today.

We write `C-x 4 f', not `C-x4f'.  We certainly don't write
<C-x><4><f>, and that is the proof that the angle-bracket
convention is not _needed_.  You can still argue that you want it
for some reason, but it is not needed.

So, we have two different conventions now for separating keys
within a sequence, and only one is needed.  Since we don't (thank
goodness!) write <C-x><4><f>, the single convention to adopt
would be space separation: `C-x 4 f' and `p r i o r' (vs
`prior').  Occam wants us to have only one convention; I want
that convention to be space separation.

The only case where confusion could arise with the
space-separation convention is when a space is used as part of
the key sequence, and that is easily dealt with by using the
description of the space key, `SPC': e.g. `p r i SPC o r'.  That
is not even a special case, but it's worth pointing out.
    
    > 4. `prior' is much more readable than the kind of notation
    shown in your screenshot.
    
    I disagree.  FWIW, I never heard anyone complaining about how
    Texinfo typesets @key.  YMMV, of course.

Ah, the ol' "I never heard anyone complain" argument...  Well, it
was a long time coming, but you finally got your first suggestion
to change this.  Hallelujah!  Rejoice!
    
    > Frankly, that looks like someone's first half-day playing
    with PowerPoint or Word, a hangover from font binging. After
    a few pages dense with key and key-sequence descriptions,
    that begins to nauseate.
    
    A wild exaggeration, IMHO.

Sorry you think so.  Do you perhaps also like the raised buttons
that pollute Customize?  Was I the first to complain about those
too?  Headache, in addition to nausea, for those.

Anyway, people often disagree about which appearance is more
appealing or easier on the eye.  (Some people write entire emails
in UPPERCASE.)  There are perhaps UI experiments that have tested
this kind of thing, but I don't know of any specifically.  Guess
we'll just have to recognize that we don't have the same
taste/preference in this regard ;-).

    This has been like that for ages.  

Right.  And you never heard anyone complain...

    Of course, if you wish to submit a change to texinfo.tex to
    make it look prettier, please do.

I'm not capable of that, I don't have the time, and I'm not sure
RMS would accept my contribution without papers from my employer.
I've made a suggestion about the notation.  If people like the
suggestion, then someone else can change texinfo.tex to realize
it.

Anyway, the point is moot I guess, as Richard has apparently
already decided - he agrees with you.
    
    > 6. <S-tab>, `S-<tab>', S-<tab>, `S-TAB', and S-TAB are
    _not_ names of keys on a keyboard. They are descriptions of
    key _sequences_.
    
    I think they should be written as @code{S-@key{TAB}} and
    appear as `S-<TAB>', and the other variants are in error.

And in the UI?

Anyway, #6 was a response to the quote from the Texinfo manual
stating that the notation in the screenshot refers to "a name for
a key on a keyboard".  <TAB> is the name of a keyboard key, but
`S-<TAB>' is not - it describes a key sequence.  Key-sequence
notation is not just a chaining of keyboard key names - we don't
typically write <SHIFT><TAB> for this key sequence.

My gripe is not really with using angle brackets to describe
keyboard keys; it is with using them in key-sequence notation or
to refer to logical keys, such as <mode-line>.  If you want to
keep <PRIOR> as a name for the keyboard key only, that's OK by
me, though I don't think it's necessary.  I'd prefer to refer to
such keys always by their key-sequence notation, which is <prior>
in the UI, and which I propose should be just `prior'.  I don't
think we'll ever need to write about the <PRIOR> keyboard key, as
opposed to the <prior> logical key in a key sequence, so I really
don't care much about what keyboard-key notation we use.

There are, anyway, very few keyboard keys that we would ever
_need_ to refer to by name, to distinguish them from the
key-sequence notation for the same key.  Those are the modifier
keys.  All other keyboard keys - and plenty of non-keyboard keys
that also have multiple-letter names - can just use their
key-sequence notation for the key as well.  We can always use
<prior> (or, as I prefer, `prior') for both key and key sequence;
we can always use <mode-line> (or `mode-line').

It is different, however, for modifier keys.  It is only for
modifier keys that we might need to distinguish the key from its
use in a key sequence - and that is the point of point #7 (see
next).
    
    > 7. CTRL, META, ALT, and so on, might be names of keys on
    many keyboards, but they are not names of key sequences.
    
    They are the names of keys.  When the manual talks about them
    as separate keys, it should use @key, yielding <CTRL>,
    <META>, etc.  When it describes them as modifiers of other
    keys, they should be in @code or @samp and appear as C-, M-,
    etc.  I believe anything else is again an error in the manual
    that should fixed.

Sounds reasonable to me, and I think that is already consistently
the case.

I agree, and that was, in fact, my point: this is true only for
modifier keys.  I singled out those keys here to point out that
they are different critters from keys such as `prior' (or
<PRIOR>), which can be (or can be part of) key sequences using
the same notation.

`prior' as a key is like `mode-line' (or <MODE-LINE> (manual) or
<mode-line> (UI)) as a key; it is not like <CTRL> as a key.  We
can have a key sequence `mode-line down-mouse-1' (or
`<mode-line><down-mouse-1>'), and we can have a key sequence
`C-down-mouse-1' (or `C-<down-mouse-1>' (manual) or
<C-down-mouse-1> (UI)), but we cannot have a key sequence
<CTRL><down-mouse-1>.  You might prefer to say that we could, but
it is not part of our notational convention.  We don't, in any
case.

You will also have noticed that the idea that the notation in the
screenshot refers to "a name for a key on a _keyboard_" cannot
even be applied to logical, non-keyboard keys such as
<mode-line> or <down-mouse-1>.

To the extent that we have a separate notation for keyboard keys,
as opposed to key sequences, I propose that we limit it to the
modifier keys.  At all other times, we can use the key-sequence
notation.

And the key-sequence notation to use is that of the UI:
<mode-line>, not <MODE-LINE>; <S-tab>, not `S-<TAB>'.

And the angle-bracket convention should be dropped - only the
space-separator convention should be used: `mode-line', not
<mode-line>, and `mode-line down-mouse-1', not
<mode-line><down-mouse-1>.

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <bojohan+news@dd.chalmers.se>, <emacs-devel@gnu.org>,
>         <karl@freefriends.org>
> Date: Tue, 26 Sep 2006 17:18:37 -0700
> 
> The UI notation is not the same as the manual notation.

What is ``the UI notation''?

> You, I think, are speaking of consistency within the manual.

Yes.

>     > 2. It's useful to have the same notation for both online
>     and printed manual, in general.
>     
>     Given how @key is typeset in the printed version, this is
>     clearly impossible, except in the graphics session of Emacs,
>     and then only if we hide the text of the Info file and show
>     some image in its stead.
> 
> No; it is possible.  Just do the opposite: bring the printed
> version into line with the online version, even the non-graphic
> (i.e. console) version, by using `next' for both.

I think this is silly.  The printed version is more powerful than a
plain text version, and there's no need to go to the lowest common
denominator just for consistency's sake.  It's good enough that the
two are sufficiently similar.

Btw, @var causes its argument to be typeset in italics in the printed
version, but in the Info version it produces UPPERCASE.  Would you
suggest to typeset it in upper-case in the printed manual as well, for
consistency's sake?  It's absurd, I think.

> I explained (in the part that you omitted) that separation by
> spaces (e.g. `p r i o r' vs `prior') is an alternative convention
> for a key sequence, which disambiguates the two just as well

The problem is not how to show sequence of keys, the problem is how to
prevent the user from erroneously interpreting "Type `FOO'" as meaning
that she should type those literal characters.  It's about possible
reader's confusion, not about our notation.

RE: drew.adams@oracle.com: bug in read-kbd-macro

[Drew Adams]

    > The UI notation is not the same as the manual notation.
    
    What is ``the UI notation''?

What you see in messages and *Help*.  What `describe-key',
`key-description', and other, similar, Lisp functions produce.
The key-sequence notation used by Emacs everywhere, except in the
manual.

I explained this; see my previous messages in the thread.  I gave
multiple examples of both UI and manual notations, labeling them
as such.
    
    >     > 2. It's useful to have the same notation for both online
    >     and printed manual, in general.
    >     
    >     Given how @key is typeset in the printed version, this is
    >     clearly impossible, except in the graphics session of Emacs,
    >     and then only if we hide the text of the Info file and show
    >     some image in its stead.
    > 
    > No; it is possible.  Just do the opposite: bring the printed
    > version into line with the online version, even the non-graphic
    > (i.e. console) version, by using `next' for both.
    
    I think this is silly.  The printed version is more powerful
    than a plain text version, 

If it were, that would certainly not be because of those key
images.  The doc that corresponds more exactly to what the user
sees in the application is the "more powerful" doc, because it
gives the user more power, from better understanding.  The manual
should use the same notation as the UI, unless there is a good
reason not to.  Got a good reason?  "It's more powerful" is not a
reason; it's just a marketing claim, unless some extra power is
identified.

    and there's no need to go to the lowest common denominator
    just for consistency's sake.  It's good enough that the two
    are sufficiently similar.
    
    Btw, @var causes its argument to be typeset in italics in the
    printed version, but in the Info version it produces
    UPPERCASE.  Would you suggest to typeset it in upper-case in
    the printed manual as well, for consistency's sake?  It's
    absurd, I think.

This discussion is about key-sequence descriptions and key
descriptions.  We can start another thread to discuss typesetting
@var, if you like, but I might have nothing special to say about
that; I haven't really thought about it.

My point was not that there cannot be typographical differences
between print manual and online manuals.  I explicitly said that
there can be, and I explicitly stated that it's good, _"in
general"_ , for them to use the same notation (you quoted it,
above).  What I mean by that is other things being equal.  To
justify different notations, something should be gained, not
lost.

I don't have an opinion whether something is gained by using
italic in the printed manual.  Italic could of course be used in
the online manual also, so there needs also to be an argument for
something being gained by using non-italic uppercase in the
online manual.  Again, this is off topic.

[BTW, I do find the new use of italic in variables/parameters of
*Help* descriptions (e.g. `describe-function') somewhat _less_
readable than the previous use of non-italic uppercase, but that
would be yet a third discussion (off topic).  (To be clear, I'm
not arguing now for or against using italic for that.)  I'll no
doubt get used to that change.]

I'm much less concerned about notation differences between online
and print manuals than I am between the key-sequence notation
used in the UI (messages, *Help*) and in the manuals.  We should
teach the notation used in the UI, because that's what people see
when they use Emacs.  I don't see a need for, or anything gained
by, introducing a different notation for the manuals (especially
one that is different in each form of the manual).  While I can
imagine someone arguing that italic or uppercase is more readable
in print or on line, I have a hard time imagining someone arguing
that the difference between the various key-sequence notations is
for readability.

What's wrong with <S-tab> (UI)?  What's better about `S-<TAB>'
(manual)?  If the latter is better, then why don't we use it in
the UI too?  In fact, I said, in a different thread recently,
that I too slightly preferred S-<tab> to <S-tab>.  That was in
response to someone pointing out, correctly, that the modifier is
not part of the key - the angle brackets having been presented in
the manual as signifying keyboard keys (which they don't, in
cases like <mode-line>).

While I think that S-<tab> is marginally clearer and more correct
than <S-tab>, the real point is that the manual should use
whatever Emacs (that is, the UI) uses, because the manual is
there to describe Emacs.  If you prefer to look at that the other
way 'round, then that's OK too: the UI should use whatever the
manual uses.  If `S-<TAB>' is better, then it is the UI that
should change to use that.  My argument, however, was that
`S-tab' is the way to go, for both UI and manuals.

It's best not to have several different notations, _unless_ they
convey some advantages.  I don't see any advantage, and I do see
disadvantages (already mentioned).
    
    > I explained (in the part that you omitted) that separation
    > by spaces (e.g. `p r i o r' vs `prior') is an alternative
    > convention for a key sequence, which disambiguates the two
    > just as well
    
    The problem is not how to show sequence of keys, the problem
    is how to prevent the user from erroneously interpreting
    "Type `FOO'" as meaning that she should type those literal
    characters.  It's about possible reader's confusion, not
    about our notation.

I disagree that the discussion is not about key-sequence
notation.  That is _all_ I have been talking about, and I'm the
one who started the thread.

Presenting how to type something (how to effect a key sequence)
is entirely different.  That introduces a possible fourth
discussion (off topic).  Again, I don't have anything special to
say about that, not having really thought about it.

In any case, I don't see what the "problem" is in that regard.
There are lots of ways to unambiguously tell readers to effect a
key sequence (type keys, perform mouse actions).  However, a
key-sequence notation `p r i' is not the same as an instruction
to type `p', then `r', then `i'.  A key sequence `S-tab' is not
the same as an instruction to press and hold the `SHIFT' key
while hitting the `TAB' key.  A key sequence `mode-line
down-mouse-1' is not the same as an instruction to press
`mouse-1' over the mode line.

An instruction to input a key sequence is not the same as a
key-sequence description (notation), even if a key-sequence
description can often give users an idea how to effect that key
sequence.  Given an understanding of the notation, it can often
be enough to say "hit `C-b'" or "use `C-x f'".  That's one of the
reasons for having a key-sequence notation, of course: to help
compose instructions for effecting key sequences.

In this regard, the space-separation notation (again, already
used in the manual and the UI, for sequences such as `C-x 4 f')
is every bit as unambiguous and clear as the angle-bracket
notation.  Saying "use `mode-line down-mouse-1'" is just as clear
as saying "use <mode-line><down-mouse-1>".  Saying "type `f o o'"
is clear and unambiguous, given the convention that spaces
separate and `SPC' represents the space key in key-sequence
notation.  And, again, nothing prevents us from not using
key-sequence notation to provide instructions: "type `f', `o',
`o'".  Users will never erroneously interpret "type `foo', as you
fear, because we would never write that in the manual; we would,
and do, write "type `f o o'".

This is nothing new.  The only thing new would be to use _only_
the space-separation notation, and abandon the angle-bracket
notation as a case of multiplying things (notations)
unnecessarily - Occam's razor.  Extra, unnecessary stuff is
wasteful and a source of confusion.  What is so special about
<f10> that it needs to be in angle brackets, while `f' and `C-x 4
f' do not?

If users can understand `C-x 4 f' when they see it in the UI, and
they do, then I don't see any problem with using this
space-separation notation for all key sequences.  There really is
no need for two different key-sequence notations.

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <bojohan+news@dd.chalmers.se>, <emacs-devel@gnu.org>,
>         <karl@freefriends.org>
> Date: Tue, 26 Sep 2006 23:22:34 -0700
> 
> I explained this; see my previous messages in the thread.

Sorry, I cannot always afford to read everything, especially if the
messages are very long.

I responded to your later version because it seemed to tell that the
manual is internally inconsistent.  I don't care about the slight
difference between what Emacs displays for the names of the keys and
what the manual shows.

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Miles Bader]

Eli Zaretskii <eliz@gnu.org> writes:
> Sorry, I cannot always afford to read everything, especially if the
> messages are very long.

Amen.

Drew, you should really think about trying to be less verbose,
especially on minor issues like this.

-Miles

-- 
`Life is a boundless sea of bitterness'

Re: drew.adams@oracle.com: bug in read-kbd-macro

[David Kastrup]

Miles Bader <miles@gnu.org> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>> Sorry, I cannot always afford to read everything, especially if the
>> messages are very long.
>
> Amen.
>
> Drew, you should really think about trying to be less verbose,
> especially on minor issues like this.

I'd have used "bellicose".  One of the problems is that people just
skip those long discussions, and it does not help if the replies keep
repeating points all over.  This annoys all people involved including
Drew, because he fails to understand why people end up neither
countering nor supporting his points.

In an ideal world, one makes one's point one time, people form an
opinion once everything has been said once, come to a decision and act
on it.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Kim F. Storm]

David Kastrup <dak@gnu.org> writes:

> Miles Bader <miles@gnu.org> writes:
>
>> Eli Zaretskii <eliz@gnu.org> writes:
>>> Sorry, I cannot always afford to read everything, especially if the
>>> messages are very long.
>>
>> Amen.
>>
>> Drew, you should really think about trying to be less verbose,
>> especially on minor issues like this.
>
> I'd have used "bellicose".  One of the problems is that people just
> skip those long discussions, and it does not help if the replies keep
> repeating points all over.  This annoys all people involved including
> Drew, because he fails to understand why people end up neither
> countering nor supporting his points.
>
> In an ideal world, one makes one's point one time, people form an
> opinion once everything has been said once, come to a decision and act
> on it.

I told Drew a long time ago that I would most likely skip his lengthy
messages -- not due to lack of interest or because I considered them
unimportant -- but simply because I don't have time and energy to do so.

Writing "a lot" is not a guarantee that your will "get your message across".

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Richard Stallman]

    2. The bug reported is not about the behavior when angle brackets are
    included. There is no bug in that case, as I stated, so there is no sense
    citing that case as evidence that there is no bug. The bug is about the
    behavior when angle brackets are not used in the key description. Key
    descriptions need not have angle brackets

Key descriptions that are meant to be read back in reliably
do need to have angle brackets.

    Angle-bracket notation is, at least in some contexts, highly UNreadable.

I think that is a bit of an exaggeration, but even if we grant it,
the fact is that angle-bracket notation is what we use for
output to be "readable" by read-kbd-macro.

I will not consider a change in this now, and probably not ever;
please let's drop the issue.

Re: drew.adams@oracle.com: bug in read-kbd-macro

[Richard Stallman]

    I don't think so; as the lispref documentation for read-kbd-macro
    says, it is roughly an inverse of `key-description', and

     M-: (key-description [mode-line]) RET

      ==> "<mode-line>"

Thanks for resolving this.