Docstring for define-key

Docstring for define-key

[Kai Großjohann]

The docstring for define-key says:

    If KEYMAP is a sparse keymap, the pair binding KEY to DEF is added at
    the front of KEYMAP.

When reading this, one could think that executing the same define-key
statement multiple times makes the KEYMAP grow.  However, this is not
the case.  Glancing at the code, I see that it seems to alter the old
binding, if one is already present.  So one possibility to change it
is like this:

    If KEYMAP is a sparse keymap with a binding for KEY, the existing
    binding is altered.  If there is no binding for KEY, the new pair
    binding KEY to DEF is added at the front of KEYMAP.

The wording is not very good, I think.

Suggestions?  Opinions?

Kudos to David Kastrup for bringing this up.
-- 
A turnip curses Elvis

Re: Docstring for define-key

[Kevin Rodgers]

Kai Großjohann wrote:

> When reading this, one could think that executing the same define-key
> statement multiple times makes the KEYMAP grow.  However, this is not
> the case.  Glancing at the code, I see that it seems to alter the old
> binding, if one is already present.  So one possibility to change it
> is like this:
> 
>     If KEYMAP is a sparse keymap with a binding for KEY, the existing
>     binding is altered.  If there is no binding for KEY, the new pair
>     binding KEY to DEF is added at the front of KEYMAP.
> 
> The wording is not very good, I think.

I think it's fine.  My only suggestion is to replace "altered" with "modified"

or "destructively modified".

-- 
<a href="mailto:&lt;kevin.rodgers&#64;ihs.com&gt;">Kevin Rodgers</a>

Re: Docstring for define-key

[Richard Stallman]

      So one possibility to change it
    is like this:

	If KEYMAP is a sparse keymap with a binding for KEY, the existing
	binding is altered.  If there is no binding for KEY, the new pair
	binding KEY to DEF is added at the front of KEYMAP.

    The wording is not very good, I think.


It looks good.

Re: Docstring for define-key

[Kai Großjohann]

Richard Stallman <rms@gnu.org> writes:

> It looks good.

I changed it accordingly.
-- 
A preposition is not a good thing to end a sentence with.

Re: Docstring for define-key

[Juanma Barranquero]

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.

[...]"


                                                           /L/e/k/t/u

Re: Docstring for define-key

[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

Re: Docstring for define-key

[Juanma Barranquero]

On 21 Feb 2003 11:53:41 +0100, storm@cua.dk (Kim F. Storm) wrote:

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

I didn't know that (although now that I know it, it's very logical :)

Thanks.

> But another wording could be used to fulfill the convention:
> 
> Define, in KEYMAP, key sequence KEY as DEF.

And it would look less ugly.


                                                           /L/e/k/t/u

Re: Docstring for define-key

[Richard Stallman]

    But another wording could be used to fulfill the convention:

    Define, in KEYMAP, key sequence KEY as DEF.

I think these words would be clearer:

    But another wording could be used to fulfill the convention:

    Define, in keymap KEYMAP, key sequence KEY with definition DEF.

It is a good practice to say explicitly what kind of value each arg
has even if its name states the type, because the name does
not always state the type.

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

    I doubt that was the reason.  More likely the redundant text was
    put there before `C-h f' started to automatically add the
    (define-key KEYMAP KEY DEF) usage.

I would expect it was a combination of both reasons.

I will add this to the Documentation Tips node in the Lisp ref manual.

@item
The first line should mention all the important arguments of the
function, and should mention them in the order that they are written
in a function call.  If the function has many arguments, then it is
not feasible to mention them all in the first line; then the first
line should mention the first few arguments, including the most
important arguments.

Re: Docstring for define-key

[Stefan Monnier]

> The first line should mention all the important arguments of the
> function, and should mention them in the order that they are written
> in a function call.

Why "in the order" ?
What's the advantage ?


	Stefan

Re: Docstring for define-key

[Richard Stallman]

    > The first line should mention all the important arguments of the
    > function, and should mention them in the order that they are written
    > in a function call.

    Why "in the order" ?

To ease the work of the programmer reading it.
To have to reorder the args for the code is extra work
and a source of mistakes.

Re: Docstring for define-key

[Stefan Monnier]

> 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.

I doubt that was the reason.  More likely the redundant text was
put there before `C-h f' started to automatically add the
(define-key KEYMAP KEY DEF) usage.

I don't think it's important at all whether arguments are listed in the
"proper" order or not.  It's much more important that the text be
clear, concise, precise, simple.


	Stefan

Re: Docstring for define-key

[Kai Großjohann]

storm@cua.dk (Kim F. Storm) writes:

> But another wording could be used to fulfill the convention:
>
> Define, in KEYMAP, key sequence KEY as DEF.

Right.  Done.

Now the second line looks really strange: KEYMAP is a keymap.  I
would never have guessed...
-- 
A preposition is not a good thing to end a sentence with.