From: Richard Stallman <rms@gnu.org>
Cc: storm@cua.dk
Subject: Re: Docstring for define-key
Date: Sat, 22 Feb 2003 12:53:48 -0500 [thread overview]
Message-ID: <E18mdqO-0006bu-00@fencepost.gnu.org> (raw)
In-Reply-To: <20030221111531.739D.LEKTU@terra.es> (message from Juanma Barranquero on Fri, 21 Feb 2003 11:34:05 +0100)
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.
next prev parent reply other threads:[~2003-02-22 17:53 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2003-02-19 16:31 Docstring for define-key Kai Großjohann
2003-02-19 22:18 ` Kevin Rodgers
2003-02-20 18:21 ` Richard Stallman
2003-02-20 19:58 ` Kai Großjohann
2003-02-21 7:39 ` Juanma Barranquero
2003-02-21 10:53 ` Kim F. Storm
2003-02-21 10:34 ` Juanma Barranquero
2003-02-22 17:53 ` Richard Stallman [this message]
2003-02-22 20:40 ` Stefan Monnier
2003-02-24 16:37 ` Richard Stallman
2003-02-21 14:36 ` Stefan Monnier
2003-02-21 16:38 ` Kai Großjohann
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=E18mdqO-0006bu-00@fencepost.gnu.org \
--to=rms@gnu.org \
--cc=storm@cua.dk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.