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: RE: read-file-name-predicate Date: Wed, 7 Mar 2007 09:14:28 -0800 Message-ID: References: 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 1173287698 6194 80.91.229.12 (7 Mar 2007 17:14:58 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 7 Mar 2007 17:14:58 +0000 (UTC) To: Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Mar 07 18:14:51 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 1HOzj1-0007hb-5z for ged-emacs-devel@m.gmane.org; Wed, 07 Mar 2007 18:14:51 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HOzj7-0007oW-NT for ged-emacs-devel@m.gmane.org; Wed, 07 Mar 2007 12:14:57 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1HOziv-0007nv-0H for emacs-devel@gnu.org; Wed, 07 Mar 2007 12:14:45 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1HOzit-0007mE-Dy for emacs-devel@gnu.org; Wed, 07 Mar 2007 12:14:43 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HOzit-0007lw-10 for emacs-devel@gnu.org; Wed, 07 Mar 2007 12:14:43 -0500 Original-Received: from rgminet01.oracle.com ([148.87.113.118]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1HOzil-0004gi-BF for emacs-devel@gnu.org; Wed, 07 Mar 2007 12:14:35 -0500 Original-Received: from rgmgw3.us.oracle.com (rgmgw3.us.oracle.com [138.1.186.112]) by rgminet01.oracle.com (Switch-3.2.4/Switch-3.1.6) with ESMTP id l27HEWCA019124 for ; Wed, 7 Mar 2007 10:14:32 -0700 Original-Received: from rcsmt251.oracle.com (rcsmt251.oracle.com [148.87.90.196]) by rgmgw3.us.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id l27HCJlh000439 for ; Wed, 7 Mar 2007 10:14:32 -0700 Original-Received: from dhcp-4op11-4op12-west-130-35-178-179.us.oracle.com by rcsmt251.oracle.com with ESMTP id 2504142251173287668; Wed, 07 Mar 2007 10:14:28 -0700 X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-Reply-To: Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3028 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:67513 Archived-At: > > My point is that it is currently entre deux chaises. Either 1) > > it should be, as it is, accessible from Lisp, in which case it > > should be documented, or 2) it should be inaccessible from Lisp. > > (Yes, I do realize that not everything that is accessible from > > Lisp is documented.) > > There are internal functions written in Lisp and internal Lisp > variables. They are frequently not documented too well because it is > frequently hard to document them without explaining a lot of Emacs > internals. This is perfectly normal. > > I don't know if in this specific case the variable is a left-over from > something we don't need anymore; I hope Kim will answer that. But > your general point -- that Lisp variables should all be documented to > the degree that every Emacs user should understand -- is not valid (as > a generality). Eli, you are arguing against the wind again. That was *not* my "general point". I did *not* make that point at all, in fact. I never said anything about "all" Lisp variables needing to be documented. I explicitly said "Yes, I do realize that *not* everything that is accessible from Lisp is documented." I argued only for documenting *this* variable, not all Lisp variables. The argument I gave for documenting *this* variable is that it is useful for Lisp programmers. The current doc does not say what it is for or what it does. To use it, users will need to know that info. It's really very simple: just say that this is the predicate supplied to `read-file-name'. I also said nothing about "internal Lisp variables". My point about internal/external was to point out that this variable, whose doc says only that it is for use by a C-coded Lisp function, is not, in fact, only accessible or only useful for that built-in function. It is just as useful as the variable `minibuffer-completion-predicate', which is prominently documented, and which is also used by a built-in function. To me, these two variables are parallel. Is this clear enough: *IF*, as I hope, this is to remain a Lisp variable, and *IF*, as I claim, it is useful to users in the same way that `minibuffer-completion-predicate' is useful, *THEN* it should be documented similarly to `minibuffer-completion-predicate'. *IF* someone decides that this should be usable only by the built-in Lisp function `read-file-name', *THEN* perhaps it should not be a Lisp variable at all. A Lisp variable whose doc says, in effect, "There is no reason that I am a Lisp variable, I don't do anything anyway, and you must not use me" is silly.