bug#18092: 24.4.50; doc string of `define-prefix-command'

[Lars Ingebrigtsen]

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

> Things are actually worse than that.
>
> The notion of "prefix command" is not introduced or explained anywhere.
> It is not in either the Emacs manual or the Elisp manual. 
>
> `define-prefix-command' has been around for a long time, but it is a
> poorly chosen name.  The symbol is NOT defined as a command or even
> as a function (it is fboundp but not functionp or commandp).
> This name is misleading and confusing.
>
> The Elisp manual speaks better of `define-prefix-command', by saying
> that it "prepares SYMBOL for use as a prefix key's binding" - nothing
> about "prefix command".  Such wording should be used also for the doc
> string.

True.  I've now added a sentence mimicing the info text.

> It would even be good to rename the function (keeping
> `define-prefix-command' as a deprecated alias).  Maybe something like
> `prepare-symbol-for-prefix-key'.
>
> The doc should also make clear that the value it puts in the function
> cell is a new, empty keymap.  Thus, if you do
> (define-prefix-command 'foo), and then you define keys in that keymap,
> and then you do (define-prefix-command 'foo) again, the keys you
> bound earlier are lost (since a new map is now used for foo).

It says:

A new sparse keymap is stored as COMMAND's function definition and its
value.

I think that's pretty unambiguous. 

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no