[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#2030: 23.0.60; doc string of dired-guess-shell-alist-user
From: |
Drew Adams |
Subject: |
bug#2030: 23.0.60; doc string of dired-guess-shell-alist-user |
Date: |
Mon, 11 Jul 2011 08:19:42 -0700 |
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.