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: doc of defining minor modes Date: Fri, 19 May 2006 08:59:43 -0700 Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1148054604 27906 80.91.229.2 (19 May 2006 16:03:24 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 19 May 2006 16:03:24 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri May 19 18:03:22 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1Fh7R9-0007uL-Bo for ged-emacs-devel@m.gmane.org; Fri, 19 May 2006 18:02:48 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Fh7R8-0002sQ-Sg for ged-emacs-devel@m.gmane.org; Fri, 19 May 2006 12:02:46 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Fh7ON-0001nN-Cu for emacs-devel@gnu.org; Fri, 19 May 2006 11:59:55 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Fh7OM-0001mw-F5 for emacs-devel@gnu.org; Fri, 19 May 2006 11:59:54 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Fh7OM-0001mr-9H for emacs-devel@gnu.org; Fri, 19 May 2006 11:59:54 -0400 Original-Received: from [141.146.126.228] (helo=agminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.52) id 1Fh7Rh-00050l-7j for emacs-devel@gnu.org; Fri, 19 May 2006 12:03:21 -0400 Original-Received: from rgmsgw300.us.oracle.com (rgmsgw300.us.oracle.com [138.1.186.49]) by agminet01.oracle.com (Switch-3.1.7/Switch-3.1.7) with ESMTP id k4JFxoQX029228 for ; Fri, 19 May 2006 10:59:50 -0500 Original-Received: from dradamslap (dhcp-amer-csvpn-gw1-141-144-66-197.vpn.oracle.com [141.144.66.197]) by rgmsgw300.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with SMTP id k4JFxngd030950 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO) for ; Fri, 19 May 2006 09:59:50 -0600 Original-To: "Emacs-Devel" X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-Reply-To: X-MIMEOLE: Produced By Microsoft MimeOLE V6.00.2800.1807 Importance: Normal X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE 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:54815 Archived-At: I wrote this about the doc changes needed for this: OK, I hear the argument as being that a user could be disoriented if a mode is turned on without his/her being aware of it. That makes sense. It is also not clearly expressed in the documentation. As I said, if "you want people to understand and respect [this recommendation], then it should be clarified and justified (explain why) in the doc." I do not think the doc is clear on this at all. The doc should explicitly say that loading a minor mode should not have any user-visible effect, and explain why. The why should mention that it might disorient users (or something to that effect). In particular, it should not speak in terms of "harm" and "pain". No such harm or pain was finally pointed out, so let's not be alarmist about this. It's enough to say that a user might be disoriented to suddenly find that a mode was turned on. And the doc should indicate how that might happen (e.g. Customize loading a library...), so people understand it. The doc should explicitly say that, because of this, :init-value should not be used or should be used only with value nil, except for the corner case described. And that corner case should be described better. Thx. It's not obvious to readers of the doc why we provide an :init-value possibility and yet we warn people not to use it (except in a rare case). There needs to be a good explanation of this uncommon coupling. The explanation needs to indicate how the problem that the admonition hopes to prevent could arise, that is, _how_ a library might get loaded without being loaded directly by the user. That is not obvious. I still have a question regarding that: I think I understand what was said here about Customize, menu access, and byte-compiling having a possible side effect of loading a library in some circumstances. But doesn't that apply only to certain kinds of libraries, which are not the common one-off, standalone, external libraries? Consider a (typical) external library that is not required by any other library. It is not part of Emacs itself; nothing in it is preloaded. Are you saying that there is some way that browsing Customize or using a menu or byte-compiling some file would cause that library to be loaded? Is there some way for it to be loaded without the user explicitly loading it? If so, this should be explained, because it is really not obvious. I do not see how Emacs would even know of the existence of such a library until it is loaded. I would think that for such a library only the user can load it, so there is no way the minor mode could be turned on behind the user's back. I want to understand this better (and doc readers will too), if the problem mentioned can indeed happen in this case also. Many external libraries are standalone like this, so this is not an atypical case. If it is correct that such libraries don't present a problem, then this distinction should be made in the doc. For in that case the admonition would be irrelevant and overkill for many libraries. In that case, let's mention that _if_ a library is required by another that is loaded or _if_ a library's customizeable features are somehow available to Customize before it is loaded or _if_ a library's command is in a menu before it is loaded ... _then_ there is the possibility that the library will be loaded other than by the user directly. And in that case, the user could be disoriented. So, in that case, use only :init-value nil.