From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: completing-read-multiple and read-face-name are not in Elisp manual Date: Tue, 19 Jun 2007 11:48:45 -0700 Message-ID: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1182279013 22285 80.91.229.12 (19 Jun 2007 18:50:13 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 19 Jun 2007 18:50:13 +0000 (UTC) To: "Emacs-Devel" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jun 19 20:50:11 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1I0imG-0006Qp-0Y for ged-emacs-devel@m.gmane.org; Tue, 19 Jun 2007 20:50:10 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1I0im1-0004DB-GT for ged-emacs-devel@m.gmane.org; Tue, 19 Jun 2007 14:49:53 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1I0ily-0004Cm-Mo for emacs-devel@gnu.org; Tue, 19 Jun 2007 14:49:50 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1I0ilt-0004CV-7i for emacs-devel@gnu.org; Tue, 19 Jun 2007 14:49:50 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1I0ilt-0004CS-1O for emacs-devel@gnu.org; Tue, 19 Jun 2007 14:49:45 -0400 Original-Received: from agminet01.oracle.com ([141.146.126.228]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1I0ilh-0006xT-DQ for emacs-devel@gnu.org; Tue, 19 Jun 2007 14:49:43 -0400 Original-Received: from rgmgw3.us.oracle.com (rgmgw3.us.oracle.com [138.1.186.112]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id l5JIn81u026797 for ; Tue, 19 Jun 2007 13:49:08 -0500 Original-Received: from acsmt351.oracle.com (acsmt351.oracle.com [141.146.40.151]) by rgmgw3.us.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id l5JEZxce026557 for ; Tue, 19 Jun 2007 12:49:07 -0600 Original-Received: from dhcp-amer-whq-csvpn-gw3-141-144-80-227.vpn.oracle.com by acsmt350.oracle.com with ESMTP id 2968655121182278930; Tue, 19 Jun 2007 11:48:50 -0700 X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3138 X-Whitelist: TRUE X-Whitelist: TRUE X-Brightmail-Tracker: AAAAAQAAAAI= X-detected-kernel: Linux 2.4-2.6 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:73327 Archived-At: (Yes, I realize that not every function needs to be documented in the manual - please don't bother with such a general reminder.) I think `completing-read-multiple' and `read-face-name' should be documented. Is `completing-read-multiple' not in the manual because `crm.el' is somehow considered optional? `completing-read-multiple' is used in `read-face-name' (where there is also a `require' of crm). The doc string of `read-face-name' says nothing about the fact that you can input and complete multiple face names. And nothing indicates to a user, when `read-face-name' is called, that s?he can input and complete multiple names, separating them with a comma. (Sure, a programmer can mention that in the prompt, but s?he might not, especially since there is no info about this in the doc string.) The doc string of read-face-name mentions the optional MULTIPLE argument, but that is only for output, not input. I find nothing about this behavior described anywhere in the Emacs manual or the Elisp manual. How will users understand the UI? How will programmers understand how these functions work (without examining the code in detail)?