From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs,gmane.emacs.pretest.bugs Subject: bug#2030: 23.0.60; doc string of dired-guess-shell-alist-user Date: Sat, 24 Jan 2009 11:09:08 -0800 Message-ID: <000c01c97e57$3c19ad20$0200a8c0@us.oracle.com> Reply-To: Drew Adams , 2030@emacsbugs.donarmstrong.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 1232825025 18603 80.91.229.12 (24 Jan 2009 19:23:45 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 24 Jan 2009 19:23:45 +0000 (UTC) To: Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jan 24 20:24:58 2009 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1LQo7m-0007dz-Cq for geb-bug-gnu-emacs@m.gmane.org; Sat, 24 Jan 2009 20:24:58 +0100 Original-Received: from localhost ([127.0.0.1]:32942 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1LQo6U-0006iI-JY for geb-bug-gnu-emacs@m.gmane.org; Sat, 24 Jan 2009 14:23:38 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1LQo6Q-0006he-5X for bug-gnu-emacs@gnu.org; Sat, 24 Jan 2009 14:23:34 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1LQo6N-0006hR-PV for bug-gnu-emacs@gnu.org; Sat, 24 Jan 2009 14:23:32 -0500 Original-Received: from [199.232.76.173] (port=39392 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1LQo6N-0006hO-KJ for bug-gnu-emacs@gnu.org; Sat, 24 Jan 2009 14:23:31 -0500 Original-Received: from rzlab.ucr.edu ([138.23.92.77]:54891) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1LQo6N-0000WX-4g for bug-gnu-emacs@gnu.org; Sat, 24 Jan 2009 14:23:31 -0500 Original-Received: from rzlab.ucr.edu (rzlab.ucr.edu [127.0.0.1]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n0OJNSGR016853; Sat, 24 Jan 2009 11:23:29 -0800 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.13.8/8.13.8/Submit) id n0OJF3ZC014515; Sat, 24 Jan 2009 11:15:03 -0800 X-Loop: owner@emacsbugs.donarmstrong.com Resent-From: "Drew Adams" Resent-To: bug-submit-list@donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Sat, 24 Jan 2009 19:15:03 +0000 Resent-Message-ID: Resent-Sender: owner@emacsbugs.donarmstrong.com X-Emacs-PR-Message: report 2030 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Original-Received: via spool by submit@emacsbugs.donarmstrong.com id=B.123282415113189 (code B ref -1); Sat, 24 Jan 2009 19:15:03 +0000 Original-Received: (at submit) by emacsbugs.donarmstrong.com; 24 Jan 2009 19:09:11 +0000 X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. Original-Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n0OJ980E013183 for ; Sat, 24 Jan 2009 11:09:09 -0800 Original-Received: from mx10.gnu.org ([199.232.76.166]:43815) by fencepost.gnu.org with esmtp (Exim 4.67) (envelope-from ) id 1LQnqu-0000eb-P9 for emacs-pretest-bug@gnu.org; Sat, 24 Jan 2009 14:07:33 -0500 Original-Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1LQnsP-0007ce-Fg for emacs-pretest-bug@gnu.org; Sat, 24 Jan 2009 14:09:06 -0500 Original-Received: from rcsinet13.oracle.com ([148.87.113.125]:47464 helo=rgminet13.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1LQnsP-0007cW-64 for emacs-pretest-bug@gnu.org; Sat, 24 Jan 2009 14:09:05 -0500 Original-Received: from acsinet13.oracle.com (acsinet13.oracle.com [141.146.126.235]) by rgminet13.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n0OJ9qZA001712 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Sat, 24 Jan 2009 19:09:53 GMT Original-Received: from acsmt702.oracle.com (acsmt702.oracle.com [141.146.40.80]) by acsinet13.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n0OJ8xxI009760 for ; Sat, 24 Jan 2009 19:09:00 GMT Original-Received: from dradamslap1 (/24.5.128.33) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 24 Jan 2009 11:08:58 -0800 X-Mailer: Microsoft Office Outlook 11 Thread-Index: Acl+Vzt5sorHn0ySSVa+OsQrXNsmzA== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 X-Source-IP: acsmt702.oracle.com [141.146.40.80] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090205.497B674C.00F7:SCFSTAT928724,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 3) Resent-Date: Sat, 24 Jan 2009 14:23:32 -0500 X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:24467 gmane.emacs.pretest.bugs:23750 Archived-At: The doc string should suggest that users use Customize. It should not use a complex `setq' example as its only illustration: (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")))) This example is in any case incorrect - "\\.bar\'" should be "\\.bar\\'". 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. Nothing is gained by showing anything other than the result of that evaluation, that is, a possible value for the option. It might also be better to write `(some-sexp)' or similar, instead of `condition', to emphasise that even that part is code to be evaluated. The use of uppercase for the command names is also problematic - those are constants (strings). This is an example, not a template. In sum: (1) the doc string is confusing in several respects; (2) it is incorrect; (3) it is unnecessarily complex; and (4) it favors Lisp instead of Customize for a user-option example.