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: public APIs and private ones (Re: `C-h v' may offer too manysymbols) Date: Thu, 10 Mar 2011 21:41:09 -0800 Message-ID: References: <87y64mkdu3.fsf@lifelogs.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1299822166 27228 80.91.229.12 (11 Mar 2011 05:42:46 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 11 Mar 2011 05:42:46 +0000 (UTC) Cc: lekktu@gmail.com, tzz@lifelogs.com, emacs-devel@gnu.org To: "'Kenichi Handa'" , "'Stefan Monnier'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Mar 11 06:42:41 2011 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.69) (envelope-from ) id 1Pxv7X-0003QU-UR for ged-emacs-devel@m.gmane.org; Fri, 11 Mar 2011 06:42:40 +0100 Original-Received: from localhost ([127.0.0.1]:34283 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Pxv7X-0007gd-7v for ged-emacs-devel@m.gmane.org; Fri, 11 Mar 2011 00:42:39 -0500 Original-Received: from [140.186.70.92] (port=40938 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Pxv7N-0007gQ-FU for emacs-devel@gnu.org; Fri, 11 Mar 2011 00:42:30 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Pxv7M-0002yd-7G for emacs-devel@gnu.org; Fri, 11 Mar 2011 00:42:29 -0500 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]:50476) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Pxv7L-0002yD-W1 for emacs-devel@gnu.org; Fri, 11 Mar 2011 00:42:28 -0500 Original-Received: from rcsinet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id p2B5gOsF012055 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 11 Mar 2011 05:42:25 GMT Original-Received: from acsmt353.oracle.com (acsmt353.oracle.com [141.146.40.153]) by rcsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id p2B5gL9v031460; Fri, 11 Mar 2011 05:42:21 GMT Original-Received: from abhmt004.oracle.com by acsmt354.oracle.com with ESMTP id 1128794901299822072; Thu, 10 Mar 2011 21:41:12 -0800 Original-Received: from dradamslap1 (/10.159.37.232) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 10 Mar 2011 21:41:11 -0800 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: Acvfp815zEyLwL6YSX6NFsztwAtciQAAnoGA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 X-Source-IP: acsmt353.oracle.com [141.146.40.153] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090206.4D79B640.0018,ss=1,fgs=0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 148.87.113.121 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:137083 Archived-At: > shouldn't we have a way to distinguish functions/macros/ > variables for public API from those for internal (i.e. only > within a specific package) use only. I have no problem with that in principle. From my point of view, "internal" here would be something definable (e.g. declarable) by the coder. IOW, it has no intrinsic meaning; it can only be defined by someone, in some context, with some purpose. Its only value is relative to those things. It expresses the coder's intention that most users will probably not want or need to use the stuff designated "internal" most of the time. Nothing more than that. > For instance, as basic-save-buffer-1 is just a helper function > of basic-save-buffer, there's no need to list it by C-h f TAB. I sure disagree here. "No need" isn't something the coder can decide. "You probably aren't very interested in this" is different from "you don't need this". Personally, I want `C-h f' to include all functions as candidates. This is `describe-function', not `describe-user-function' or some such. I have no problem with someone adding a new command to do what you describe. I would prefer that it not be bound to `C-h f', but that's another matter (and I certainly wouldn't go to the barricades about it). Or a prefix arg might be acceptable for distinguishing the two. Then we would be arguing only over the default behavior (behavior with no prefix arg). But my personal preference, used in my own version of `C-h f', is for a prefix arg to mean use only _commands_ as completion candidates. Perhaps a distinction via different prefix-arg values would be appropriate: all functions, only commands, only "external" functions. > In addition, and this is more important, such a > distinguishment makes it easier to maintain a package. For > instance, when I improve the MIME handling of rmailmm.el, > the most difficult thing was to keep backward compatibility > of existing functions. It seems that most of them are > intended for internal use only. If that is clear, I could > have renamed or changed the behaviour of some of them. Again, "internal" means nothing (especially) for a language like Lisp (especially a Lisp that has no packages/modules), other than as an expression of a coder's intention. That's not nothing, of course. And there's nothing wrong with expressing such an intention - it can be helpful. But "internal" can (and should) never be more than that: expression of intended use by most users in most situations. People are users at different levels at different times or in different contexts. Something is language in one context and metalanguage in another context. Same with internal and external. One person's or one context's internal is another person's or another context's external. That does not mean that such terms are meaningless or useless; it just means that they are far from absolute. Sooner or later someone (and not only the maintainer) will want to use "internal" functions for something - possibly something "external" or unintended originally. Code manipulation (by code) is just one example.