From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: Docstring for define-key Date: Sat, 22 Feb 2003 12:53:48 -0500 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <20030221083232.8366.LEKTU@terra.es> <5xd6lloqfe.fsf@kfs2.cua.dk> <20030221111531.739D.LEKTU@terra.es> Reply-To: rms@gnu.org NNTP-Posting-Host: main.gmane.org X-Trace: main.gmane.org 1045936746 31399 80.91.224.249 (22 Feb 2003 17:59:06 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Sat, 22 Feb 2003 17:59:06 +0000 (UTC) Cc: storm@cua.dk Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 18mdvR-00089z-00 for ; Sat, 22 Feb 2003 18:59:01 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 18meA2-0004Ui-00 for ; Sat, 22 Feb 2003 19:14:06 +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 18mdvW-0001oM-00 for emacs-devel@quimby.gnus.org; Sat, 22 Feb 2003 12:59:06 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 18mduL-0000oQ-00 for emacs-devel@gnu.org; Sat, 22 Feb 2003 12:57:53 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 18mdrd-00008r-00 for emacs-devel@gnu.org; Sat, 22 Feb 2003 12:55:07 -0500 Original-Received: from fencepost.gnu.org ([199.232.76.164]) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18mdqO-0007kx-00 for emacs-devel@gnu.org; Sat, 22 Feb 2003 12:53:48 -0500 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.10) id 18mdqO-0006bu-00; Sat, 22 Feb 2003 12:53:48 -0500 Original-To: Juanma Barranquero , monnier+gnu/emacs@rum.cs.yale.edu In-reply-to: <20030221111531.739D.LEKTU@terra.es> (message from Juanma Barranquero on Fri, 21 Feb 2003 11:34:05 +0100) Original-cc: emacs-devel@gnu.org 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:11853 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:11853 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.