option doc strings and Customize tags

[Drew Adams]

A doc string for a user option typically mentions the Lisp values for the
option. It does not mention the tags that might be used for those values by
Customize. This is as it should be, I think.

However, this can result in confusion, and it complicates talking about options
and their values. Users of Customize will naturally think in terms of the tags,
not the Lisp values, which they do not see. The doc string is repeated in
Customize, but there is nothing that makes the correpondence between particular
tags and values.

Since both the doc string and the Customize tags are destined for the end user,
this non-correspondence is a (doc) problem that Emacs developers should perhaps
address. Example - `tags-case-fold-search':

Doc string:

 Whether tags operations should be case-sensitive.
 A value of t means case-insensitive, a value of nil means case-sensitive.
 Any other value means use the setting of `case-fold-search'.

Value menu in Customize:

 * Case-sensitive
 * Case-insensitive
 * Use default

A user would likely be able to figure out the correpondence in this case, but in
other cases it might not be so simple. And even here, the item `Use default' is
not very clear (what default?).

Question: Can we come up with some way of helping users see the correspondence?

For short Lisp values at least, perhaps the menu itself could include the value
next to the tag: `Case-sensitive: nil'. Or (better) perhaps there could be some
other way to show the possible Lisp values.

I don't have a good idea for this, but I think it represents an opportunity for
improvement. Any ideas?

I dunno, maybe a `Show Lisp Values' button that displays the two sets of
"values" temporarily side by side?

 nil      Case-sensitive
 t        Case-insensitive
 <other>  Use default

But in the case of long values, that has the same problem as putting the info in
the menu itself. Perhaps we could abbreviate long values (e.g. sexps and
strings).

And some convention would be needed to distinguish a value description such as
`<other>' from an actual value (e.g. string or symbol named `<other>').

WDYT?