GNU bug report logs - #2030
23.0.60; doc string of dired-guess-shell-alist-user

Previous Next

Full log

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.60; doc string of dired-guess-shell-alist-user
Date: Sat, 24 Jan 2009 11:09:08 -0800

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.
 

 

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.