From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: storm@cua.dk (Kim F. Storm) Newsgroups: gmane.emacs.devel Subject: Re: Docstring for define-key Date: 21 Feb 2003 11:53:41 +0100 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <5xd6lloqfe.fsf@kfs2.cua.dk> References: <84isve7mhw.fsf@lucy.is.informatik.uni-duisburg.de> <20030221083232.8366.LEKTU@terra.es> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable X-Trace: main.gmane.org 1045821586 5237 80.91.224.249 (21 Feb 2003 09:59:46 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Fri, 21 Feb 2003 09:59:46 +0000 (UTC) Cc: emacs-devel@gnu.org Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 18m9y4-0001ML-00 for ; Fri, 21 Feb 2003 10:59:44 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 18mAC1-0003PL-00 for ; Fri, 21 Feb 2003 11:14:09 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18m9we-0003Pz-05 for emacs-devel@quimby.gnus.org; Fri, 21 Feb 2003 04:58:16 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 18m9vu-0002ng-00 for emacs-devel@gnu.org; Fri, 21 Feb 2003 04:57:30 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 18m9vk-0002gW-00 for emacs-devel@gnu.org; Fri, 21 Feb 2003 04:57:22 -0500 Original-Received: from mail.filanet.dk ([195.215.206.179]) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18m9tC-0000p1-00 for emacs-devel@gnu.org; Fri, 21 Feb 2003 04:54:42 -0500 Original-Received: from kfs2.cua.dk.cua.dk (kfs2.local.filanet.dk [192.168.1.182]) by mail.filanet.dk (Postfix) with SMTP id CC0E37C017; Fri, 21 Feb 2003 10:54:36 +0100 (CET) Original-To: Juanma Barranquero In-Reply-To: <20030221083232.8366.LEKTU@terra.es> Original-Lines: 45 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3.50 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Emacs development discussions. List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:11809 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:11809 Juanma Barranquero writes: > On Thu, 20 Feb 2003 20:58:19 +0100, kai.grossjohann@uni-duisburg.de (Kai = Gro=DFjohann) wrote: >=20 > > I changed it accordingly. >=20 > On the matter of define-key's docstring, the beginning: >=20 > "Args KEYMAP, KEY, DEF. Define key sequence KEY, in KEYMAP, as DEF. > KEYMAP is a keymap. >=20 > [...]" >=20 > is a bit redundant, isn't? What's wrong with: >=20 > "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=20 the wrong order. But another wording could be used to fulfill the convention: Define, in KEYMAP, key sequence KEY as DEF. --=20 Kim F. Storm http://www.cua.dk