bug#20135: 25.0.50; Emacs manual typos for key bindings

[Drew Adams]

One question is what is the conventional way to write a modifier
followed by a (possibly pseudo) function key in the doc (manuals, doc
strings).

Do we write `<S-up>' or `S-<up>'?  Or do we use both conventions, and if
so, are they interchangeable (same meaning)?

`kbd' accepts both: (kbd "<S-up>") and (kbd "S-<up>"), and the effect
when binding such keys seems to be the same.

Another question is about whether, aside from special cases (which are
already called out, AFAIK), function-key names should be written using
uppercase.  For example, is `<S-RIGHT>" correct, or should it be
`<S-right>" (or `S-<right>')?

In the manual, it seems that the more common syntax is `S-<...>', not
`<S-...>'.  However, in doc strings the opposite seems to be true (?).

As for the possible typos I came across in the Emacs manual:

1. Node `View Mode': <S-<SPC>>.  Presumably should be S-<SPC>.

2. Node `Org Mode': <S-TAB>.  Should be S-<TAB>, I'm guessing - or
   possibly S-<tab>, depending on which key is meant.

3. Node `Setting Mark': S-<RIGHT>.  Should be S-<right>, I think.

4. Node `Indentation Commands': S-<LEFT>, S-<RIGHT>.  Should be
   S-<left>, S-<right>.  (Also: <LEFT> and <RIGHT> should be <left> and
   <right>.)

5. Node `Setting Mark': S-<RIGHT>.  Should be S-<right>.

6. Node `User Input': M-<LEFT> should be M-<left>.

7. Node `Moving Point': C-<RIGHT>, M-<RIGHT>, C-<LEFT>, M-<LEFT> should
   be C-<left>, M-<left>, C-<right>, M-<right>.

8. Node `Minibuffer History': <M-n> should presumably be M-n.
   (Also, <UP> and <DOWN> should be <up> and <down>.

9. Node `Basic Indent': <C-j> should be just C-j.

10. Node `Custom C Indent': <C-M-q> should be just C-M-q.

11. Node `Term Mode: <C-c> should be just C-c.

12. There is also inconsistency in whether such keys are enclosed in
   quotes.  Node `Rmail Scrolling' has both notations mixed even in the
   same sentence (e.g., <SPC>, but `S-<SPC>'):

    Since the most common thing to do while reading a message is to
    scroll through it by screenfuls, Rmail makes <SPC> and <DEL> (or
    `S-<SPC>') do the same as `C-v' (`scroll-up-command') and `M-v'
    (`scroll-down-command') respectively.

   Likewise, node `Help Mode': (<TAB> vs `S-<TAB'), and possibly others.

13. I wonder too about the function keys being written with uppercase:
   <F9> instead of <f9>.  In *Help* buffers (e.g. from `C-h k') they are
   written using lowercase.

If some of these look right to you then please try searching for the
corrections I proposed, which I think are much more commonly employed.
For example, if you think that <UP> is correct, then search also for
<up>.  You will find, I think, that what I proposed is used more
consistently.

But there does seem to be a general disconnect between what is shown in
*Help* by the help commands and what is shown in the manual by Info.
Help uses <S-foo> whereas the manual uses S-<foo>.

To me, we should use the same notation for both, and I would vote for
the manual to fit what help uses.  That is, I would suggest that we
(consistently) use what `key-description' returns.

So we would use `<S-right>', for example, not `S-<right>'.

 (key-description (kbd "<S-right>")) ; => <S-right>
 (key-description (kbd "S-<right>")) ; => <S-right>

And `S-<RIGHT>', not `<S-RIGHT>'.  But presumably <RIGHT> is a different
function key from <right>, and the former should never be used to
represent the latter.

 (key-description (kbd "<S-RIGHT>")) ; => <S-RIGHT>
 (key-description (kbd "S-<RIGHT>")) ; => <S-RIGHT>



In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'