bug#2030: 23.0.60; doc string of dired-guess-shell-alist-user

[Drew Adams]

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.