From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#2030: 23.0.60; doc string of dired-guess-shell-alist-user Date: Mon, 11 Jul 2011 08:19:42 -0700 Message-ID: References: <000c01c97e57$3c19ad20$0200a8c0@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: dough.gmane.org 1310399587 23388 80.91.229.12 (11 Jul 2011 15:53:07 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 11 Jul 2011 15:53:07 +0000 (UTC) Cc: 2030@debbugs.gnu.org To: "'Lars Magne Ingebrigtsen'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jul 11 17:53:03 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QgIn6-0003hM-S1 for geb-bug-gnu-emacs@m.gmane.org; Mon, 11 Jul 2011 17:53:01 +0200 Original-Received: from localhost ([::1]:53921 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QgIn5-00078R-Ep for geb-bug-gnu-emacs@m.gmane.org; Mon, 11 Jul 2011 11:52:59 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:53586) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QgIHJ-00070D-JI for bug-gnu-emacs@gnu.org; Mon, 11 Jul 2011 11:20:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QgIHG-0002x7-Qh for bug-gnu-emacs@gnu.org; Mon, 11 Jul 2011 11:20:09 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:54312) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QgIHG-0002wu-GO for bug-gnu-emacs@gnu.org; Mon, 11 Jul 2011 11:20:06 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1QgIHF-00068v-LX; Mon, 11 Jul 2011 11:20:05 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 11 Jul 2011 15:20:05 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 2030 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: fixed Original-Received: via spool by 2030-submit@debbugs.gnu.org id=B2030.131039759923570 (code B ref 2030); Mon, 11 Jul 2011 15:20:05 +0000 Original-Received: (at 2030) by debbugs.gnu.org; 11 Jul 2011 15:19:59 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QgIH9-000687-Ad for submit@debbugs.gnu.org; Mon, 11 Jul 2011 11:19:59 -0400 Original-Received: from acsinet15.oracle.com ([141.146.126.227]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QgIH7-00067m-3q for 2030@debbugs.gnu.org; Mon, 11 Jul 2011 11:19:57 -0400 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p6BFJnY1017204 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 11 Jul 2011 15:19:50 GMT Original-Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p6BFJmgO018307 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 11 Jul 2011 15:19:48 GMT Original-Received: from abhmt115.oracle.com (abhmt115.oracle.com [141.146.116.67]) by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p6BFJhoN003177; Mon, 11 Jul 2011 10:19:43 -0500 Original-Received: from dradamslap1 (/130.35.178.194) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 11 Jul 2011 08:19:42 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: Acw/0pJ5hUU5KIuWQeeFlaAB/IRwzwACVzZQ X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090202.4E1B1497.0014:SCFMA922111,ss=1,re=-4.000,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Mon, 11 Jul 2011 11:20:05 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:48589 Archived-At: Lars, you marked this bug `fixed', but it seems that it was hardly addressed (partly addressed). Please take another look at it. > > The doc string should suggest that users use Customize. It > > should not use a complex `setq' example as its only illustration: Note: _only_. > > (setq dired-guess-shell-alist-user > > (list (list "\\.foo\\'" "FOO-COMMAND");; fixed rule > > ;; possibly more rules ... > > (list "\\.bar\'";; rule with condition test > > '(if condition > > "BAR-COMMAND-1" > > "BAR-COMMAND-2")))) > > I think complicated variables are best served with non-Customize > examples. It's OK to have a code example, if that helps make things clear. And yes, it's not obvious how to _show_ Customize in the doc. But that's not what I suggested. The "doc string should suggest that users use Customize." That's the point. It is one thing to say that _showing_ Customize in the doc is not easy and probably not worth it. It is another thing that the doc _only_ suggest to users to use `setq'. And even for a code example it would be better to use `customize-save-variable' instead of `setq'. We should generally encourage this practice, since for many user options it makes a difference: If VARIABLE has a `custom-set' property, that is used for setting VARIABLE, otherwise `set-default' is used. If VARIABLE has a `variable-interactive' property, that is used as if it were the arg to `interactive' (which see) to interactively read the value. If VARIABLE has a `custom-type' property, it must be a widget and the `:prompt-value' property of that widget will be used for reading the value. > I've rewritten it to use a quote instead of all the `list' operations, > which should make it clearer. That's fine, but it does not respond to the bug report at all - it's something else. Please suggest to users that they use Customize. It's about the users, not our ease in writing the doc and its examples. I agree that it is not easy or worthwhile to show an illustration of Customize here. But we should nevertheless suggest using Customize first, and show a code example only second, if important, as a way to code things by hand. > > If it's felt that an example of a _value_ for this option is needed, > > then it's OK to show that directly: > > > > (("\\.foo\\'" "foo-command") ; unconditional rule > > ("\\.bar\\'" ; conditional rule > > (if (some-sexp) "bar-command-1" "bar-command-2"))) > > > > But there is absolutely no reason to show setting the value using > > `setq', especially since the expression evaluated by `setq' is 100% > > constant. > > I disagree. A complete `setq' is convenient to cut and paste. That's not something we necessarily want to encourage. Customize is much to be preferred when it is appropriate. It is safer, does type-checking, etc. It's not because some of us find the Customize UI to be ugly that we should not encourage its use. What's important for the illustration is what a value looks like. I recommend that we (a) remove `setq', (2) not bother with `customize-save-variable', but (3) show the example _value_, as I wrote initially.