Re: Docstring for define-key

[storm@cua.dk (Kim F. Storm)]

Juanma Barranquero <lektu@terra.es> writes:

> On Thu, 20 Feb 2003 20:58:19 +0100, kai.grossjohann@uni-duisburg.de (Kai Großjohann) wrote:
> 
> > I changed it accordingly.
> 
> On the matter of define-key's docstring, the beginning:
> 
> "Args KEYMAP, KEY, DEF.  Define key sequence KEY, in KEYMAP, as DEF.
> KEYMAP is a keymap.
> 
> [...]"
> 
> is a bit redundant, isn't? What's wrong with:
> 
> "Define key sequence KEY, in keymap KEYMAP, as DEF.

The convention is that the first line of the doc string should mention
the (non-optional) arguments in the actual sequence.

Since define-key args are KEYMAP KEY DEF, it's written like that.

However, if I enter C-h f define-key RET, the output looks like this:

'--------------------
|define-key is a built-in function.
|(define-key KEYMAP KEY DEF)
|
|Args KEYMAP, KEY, DEF.  Define key sequence KEY, in KEYMAP, as DEF.
|KEYMAP is a keymap.
|
|KEY is a string or a vector of symbols and characters meaning a
|...
`-------------------

i.e. in that context, the arglist is printed right above the first line,
so it is indeed superfluous -- even if the arguments are mentioned in 
the wrong order.

But another wording could be used to fulfill the convention:

Define, in KEYMAP, key sequence KEY as DEF.

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