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

["Drew Adams" <drew.adams@oracle.com>]

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.