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: option doc strings and Customize tags Date: Mon, 27 Oct 2008 11:12:08 -0700 Message-ID: <005601c9385f$86a998c0$c2b22382@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1225131170 22522 80.91.229.12 (27 Oct 2008 18:12:50 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 27 Oct 2008 18:12:50 +0000 (UTC) To: Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 27 19:13:52 2008 connect(): Connection refused 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 1KuWax-0004jx-2s for ged-emacs-devel@m.gmane.org; Mon, 27 Oct 2008 19:13:39 +0100 Original-Received: from localhost ([127.0.0.1]:48948 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1KuWZq-0002Xi-R6 for ged-emacs-devel@m.gmane.org; Mon, 27 Oct 2008 14:12:30 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1KuWZe-0002Py-8n for emacs-devel@gnu.org; Mon, 27 Oct 2008 14:12:18 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1KuWZb-0002OT-Lj for emacs-devel@gnu.org; Mon, 27 Oct 2008 14:12:17 -0400 Original-Received: from [199.232.76.173] (port=60964 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1KuWZb-0002OG-Gy for emacs-devel@gnu.org; Mon, 27 Oct 2008 14:12:15 -0400 Original-Received: from agminet01.oracle.com ([141.146.126.228]:54095) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1KuWZa-0006W6-US for emacs-devel@gnu.org; Mon, 27 Oct 2008 14:12:15 -0400 Original-Received: from agmgw1.us.oracle.com (agmgw1.us.oracle.com [152.68.180.212]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id m9RIC782021486 for ; Mon, 27 Oct 2008 13:12:07 -0500 Original-Received: from acsmt703.oracle.com (acsmt703.oracle.com [141.146.40.81]) by agmgw1.us.oracle.com (Switch-3.2.0/Switch-3.2.0) with ESMTP id m9RIC7NK013891 for ; Mon, 27 Oct 2008 12:12:07 -0600 Original-Received: from dradamslap1 (/130.35.178.194) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 27 Oct 2008 18:12:07 +0000 X-Mailer: Microsoft Office Outlook 11 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 Thread-Index: Ack4X4Zaa6b4L83YRZKtKdel6Dk2OQ== X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-operating-system: by monty-python.gnu.org: GNU/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:105049 Archived-At: A doc string for a user option typically mentions the Lisp values for the option. It does not mention the tags that might be used for those values by Customize. This is as it should be, I think. However, this can result in confusion, and it complicates talking about options and their values. Users of Customize will naturally think in terms of the tags, not the Lisp values, which they do not see. The doc string is repeated in Customize, but there is nothing that makes the correpondence between particular tags and values. Since both the doc string and the Customize tags are destined for the end user, this non-correspondence is a (doc) problem that Emacs developers should perhaps address. Example - `tags-case-fold-search': Doc string: Whether tags operations should be case-sensitive. A value of t means case-insensitive, a value of nil means case-sensitive. Any other value means use the setting of `case-fold-search'. Value menu in Customize: * Case-sensitive * Case-insensitive * Use default A user would likely be able to figure out the correpondence in this case, but in other cases it might not be so simple. And even here, the item `Use default' is not very clear (what default?). Question: Can we come up with some way of helping users see the correspondence? For short Lisp values at least, perhaps the menu itself could include the value next to the tag: `Case-sensitive: nil'. Or (better) perhaps there could be some other way to show the possible Lisp values. I don't have a good idea for this, but I think it represents an opportunity for improvement. Any ideas? I dunno, maybe a `Show Lisp Values' button that displays the two sets of "values" temporarily side by side? nil Case-sensitive t Case-insensitive Use default But in the case of long values, that has the same problem as putting the info in the menu itself. Perhaps we could abbreviate long values (e.g. sexps and strings). And some convention would be needed to distinguish a value description such as `' from an actual value (e.g. string or symbol named `'). WDYT?