bug#9700: 24.0.50; doc string of `key-description'

[Drew Adams]

> >  "Control characters turn into "C-foo" sequences, meta into "M-foo",
> >   spaces are put between sequence elements, etc."
> >  
> > Since Emacs 21 that needs to be changed to "<C-foo>" and "<M-foo>",
> > since "foo" is obviously the name of a function key (more than one
> > character in the name).
> 
> No, these are not referring to function keys.  I tweaked the docstring
> to make this clearer.

I have not seen your fix yet. b Bt clearly as they were written they did refer
to function keys (no spaces: `f o o').

As far as control and meta are concerned, it would be clear enough if you wrote
just "C-" and "M-".  Dunno if that's what you did.

However, it is not enough to mention that control goes to `C-', meta to `M-',
and spaces are used as separators - and then end with "etc."  That is far too
incomplete.

A more complete description should be given explicitly (including handling of
function keys with angle brackets).

Or (preferably) it should (after the "etc.") just do what the doc for `kbd'
does.  It can simply state that the return value is a value that would be
acceptable to `kbd'.  Or it can repeat what the `kbd' doc string says: "the
format used for saving keyboard macros (see `edmacro-mode')."

The point is that `key-description' needs to clearly let users know about the
format of the returned description, one way or another.  It is not acceptable to
punt with "etc.".