From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Juri Linkov Newsgroups: gmane.emacs.devel Subject: Re: Argument names in Elisp Reference vs docstrings Date: Fri, 16 Sep 2005 01:03:02 +0300 Organization: JURTA Message-ID: <87acieyoo9.fsf@jurta.org> References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1126823814 12693 80.91.229.2 (15 Sep 2005 22:36:54 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 15 Sep 2005 22:36:54 +0000 (UTC) Cc: lekktu@gmail.com, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Sep 16 00:36:52 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1EG2LK-0002vI-V4 for ged-emacs-devel@m.gmane.org; Fri, 16 Sep 2005 00:36:35 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EG2LK-0003P5-9T for ged-emacs-devel@m.gmane.org; Thu, 15 Sep 2005 18:36:34 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1EG2Er-00023G-K0 for emacs-devel@gnu.org; Thu, 15 Sep 2005 18:29:54 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1EG2Ec-0001v6-Pm for emacs-devel@gnu.org; Thu, 15 Sep 2005 18:29:43 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EG2Eb-0001d0-Uf for emacs-devel@gnu.org; Thu, 15 Sep 2005 18:29:38 -0400 Original-Received: from [194.126.101.111] (helo=mail.neti.ee) by monty-python.gnu.org with esmtp (Exim 4.34) id 1EG21m-0008FY-IB; Thu, 15 Sep 2005 18:16:22 -0400 Original-Received: from mail.neti.ee (80-235-39-25-dsl.mus.estpak.ee [80.235.39.25]) by Relayhost1.neti.ee (Postfix) with ESMTP id A82F516B3; Fri, 16 Sep 2005 01:16:32 +0300 (EEST) Original-To: rms@gnu.org In-Reply-To: (Richard M. Stallman's message of "Wed, 14 Sep 2005 10:08:04 -0400") User-Agent: Gnus/5.110004 (No Gnus v0.4) Emacs/22.0.50 (gnu/linux) X-Virus-Scanned: by amavisd-new-2.2.1 (20041222) (Debian) at neti.ee X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:42970 Archived-At: > It is consistency between argument names in docstrings vs argument > names in the Emacs Lisp Reference a goal? > > Yes, more or less. It is not necessary to fix all such discrepancies, > but in many cases fixing them would be a step forward. When doing so, > it is important to standardize on the better name, not the worse one. While looking recently at minibuffer reading functions, I noticed that not only argument names in the Emacs Lisp Reference and docstrings of each function don't match, but even similar arguments have different names in related functions. It is misleading when documentation refers to a similar argument of another function, but it has a different name. Below is a list of arguments with similar names of minibuffer functions collected from docstrings and descriptions in the Emacs Lisp Reference: prompt, prompt-string initial, initial-contents, initial-input history, hist def, defalt, default, default-value, default-filename, default-dirname inherit-input-method require-match, mustmatch, must-match, existing collection, table, alist nospace, hide-spaces directory, dir I propose to standardize on the following arguments names: prompt initial history defaults inherit-im must-match collection no-space directory Most of these names are shorter than current names, but still intelligible. Since `default' is a keyword in C, `defaults' is a good replacement. `inherit-im' is twice shorter than `inherit-input-method' and the `IM' abbreviation is already mentioned in the Emacs manual. -- Juri Linkov http://www.jurta.org/emacs/