option doc strings and Customize tags

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?

Re: option doc strings and Customize tags

[martin rudalics]

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

I'd put the Lisp values in parentheses as

     Case-sensitive (nil)
     Case-insensitive (t)
     Use default

martin

RE: option doc strings and Customize tags

[Drew Adams]

>  >  nil      Case-sensitive
>  >  t        Case-insensitive
>  >  <other>  Use default
> 
> I'd put the Lisp values in parentheses as
> 
>      Case-sensitive (nil)
>      Case-insensitive (t)
>      Use default

Sure, fine, whatever. It doesn't matter much what format we use. Except that
adding parens might confuse things for Lisp values that are lists: ((foo bar)).

A more general formatting problem is that the Lisp values might be quite long.
Some kind of abbreviation is probably called for. And we still need something to
indicate `other value'.

Re: option doc strings and Customize tags

[Lennart Borgman]

On Tue, Oct 28, 2008 at 8:28 PM, Drew Adams <drew.adams@oracle.com> wrote:
>>  >  nil      Case-sensitive
>>  >  t        Case-insensitive
>>  >  <other>  Use default
>>
>> I'd put the Lisp values in parentheses as
>>
>>      Case-sensitive (nil)
>>      Case-insensitive (t)
>>      Use default
>
> Sure, fine, whatever. It doesn't matter much what format we use. Except that
> adding parens might confuse things for Lisp values that are lists: ((foo bar)).
>
> A more general formatting problem is that the Lisp values might be quite long.
> Some kind of abbreviation is probably called for.

A link that is opened in *Help* and shows the value with an
explanation where it came from?

> And we still need something to
> indicate `other value'.

RE: option doc strings and Customize tags

[Drew Adams]

> >>  >  nil      Case-sensitive
> >>  >  t        Case-insensitive
> >>  >  <other>  Use default
> >>
> >> I'd put the Lisp values in parentheses as
> >>
> >>      Case-sensitive (nil)
> >>      Case-insensitive (t)
> >>      Use default
> >
> > Sure, fine, whatever. It doesn't matter much what format we 
> > use. Except that adding parens might confuse things for Lisp
> > values that are lists: ((foo bar)).
> >
> > A more general formatting problem is that the Lisp values 
> > might be quite long. Some kind of abbreviation is probably
> > called for.
> 
> A link that is opened in *Help* and shows the value with an
> explanation where it came from?

Possibly. But the point here is to show all of the possible values *together*.
You don't want to click a button/link and open *Help* for each possible value,
to see its Lisp value separately from the others.

A single display of all tags and their Lisp values (in *Help* or elsewhere) is
what's needed. See the original suggestion.

Re: option doc strings and Customize tags

[Lennart Borgman]

On Tue, Oct 28, 2008 at 8:49 PM, Drew Adams <drew.adams@oracle.com> wrote:
>> >>  >  nil      Case-sensitive
>> >>  >  t        Case-insensitive
>> >>  >  <other>  Use default
>> >>
>> >> I'd put the Lisp values in parentheses as
>> >>
>> >>      Case-sensitive (nil)
>> >>      Case-insensitive (t)
>> >>      Use default
>> >
>> > Sure, fine, whatever. It doesn't matter much what format we
>> > use. Except that adding parens might confuse things for Lisp
>> > values that are lists: ((foo bar)).
>> >
>> > A more general formatting problem is that the Lisp values
>> > might be quite long. Some kind of abbreviation is probably
>> > called for.
>>
>> A link that is opened in *Help* and shows the value with an
>> explanation where it came from?
>
> Possibly. But the point here is to show all of the possible values *together*.
> You don't want to click a button/link and open *Help* for each possible value,
> to see its Lisp value separately from the others.
>
> A single display of all tags and their Lisp values (in *Help* or elsewhere) is
> what's needed. See the original suggestion.

I meant that for the long values only. But the buffer that shows the
long value can show all the values together.

RE: option doc strings and Customize tags

[Drew Adams]

> >> >>  >  nil      Case-sensitive
> >> >>  >  t        Case-insensitive
> >> >>  >  <other>  Use default
> >> >>
> >> >> I'd put the Lisp values in parentheses as
> >> >>
> >> >>      Case-sensitive (nil)
> >> >>      Case-insensitive (t)
> >> >>      Use default
> >> >
> >> > Sure, fine, whatever. It doesn't matter much what format we
> >> > use. Except that adding parens might confuse things for Lisp
> >> > values that are lists: ((foo bar)).
> >> >
> >> > A more general formatting problem is that the Lisp values
> >> > might be quite long. Some kind of abbreviation is probably
> >> > called for.
> >>
> >> A link that is opened in *Help* and shows the value with an
> >> explanation where it came from?
> >
> > Possibly. But the point here is to show all of the possible 
> > values *together*. You don't want to click a button/link and
> > open *Help* for each possible value, to see its Lisp value
> > separately from the others.
> >
> > A single display of all tags and their Lisp values (in 
> > *Help* or elsewhere) is what's needed. See the original
> > suggestion.
> 
> I meant that for the long values only. But the buffer that shows the
> long value can show all the values together.

If it shows all of the values together, then there is no sense in showing it
"for the long values only". The point is to show all of the values, for
comparison and comprehension, whenever you try to look at any of them (even a
short one). For the need to see the values together, it's irrelevant whether a
value is long or short.

Perhaps you are saying that if all values are short enough then no separate
display is needed - they can be shown in the menu. But if even one value is long
(whatever "long" means), then a separate display is needed.

Re: option doc strings and Customize tags

[Lennart Borgman]

On Tue, Oct 28, 2008 at 9:25 PM, Drew Adams <drew.adams@oracle.com> wrote:
>> >> >>  >  nil      Case-sensitive
>> >> >>  >  t        Case-insensitive
>> >> >>  >  <other>  Use default
>> >> >>
>> >> >> I'd put the Lisp values in parentheses as
>> >> >>
>> >> >>      Case-sensitive (nil)
>> >> >>      Case-insensitive (t)
>> >> >>      Use default
>> >> >
>> >> > Sure, fine, whatever. It doesn't matter much what format we
>> >> > use. Except that adding parens might confuse things for Lisp
>> >> > values that are lists: ((foo bar)).
>> >> >
>> >> > A more general formatting problem is that the Lisp values
>> >> > might be quite long. Some kind of abbreviation is probably
>> >> > called for.
>> >>
>> >> A link that is opened in *Help* and shows the value with an
>> >> explanation where it came from?
>> >
>> > Possibly. But the point here is to show all of the possible
>> > values *together*. You don't want to click a button/link and
>> > open *Help* for each possible value, to see its Lisp value
>> > separately from the others.
>> >
>> > A single display of all tags and their Lisp values (in
>> > *Help* or elsewhere) is what's needed. See the original
>> > suggestion.
>>
>> I meant that for the long values only. But the buffer that shows the
>> long value can show all the values together.
>
> If it shows all of the values together, then there is no sense in showing it
> "for the long values only". The point is to show all of the values, for
> comparison and comprehension, whenever you try to look at any of them (even a
> short one). For the need to see the values together, it's irrelevant whether a
> value is long or short.
>
> Perhaps you are saying that if all values are short enough then no separate
> display is needed - they can be shown in the menu. But if even one value is long
> (whatever "long" means), then a separate display is needed.

What I tried to say is:

- In the initial display show all values together, but replace the
long values with a link.

- This link should lead to a second display (in *Help*) where also all
values are shown together. Here the long values should of course be
shown. There should also be a short explanation what this display is
about (and a link back, but that is nearly automatic if the first
display is in *Help* too).

RE: option doc strings and Customize tags

[Stephen J. Turnbull]

Drew Adams writes:

 > A more general formatting problem is that the Lisp values might be
 > quite long.

Maybe.  This is possibly a YAGNI, though.  What I'm thinking is that
normally long values will either be indirect (eg, the value of
variable whose name can be used instead of the value), or they will be
compounds in which case a compound widget will be used so that the
components can be changed.

Even if there are a small number, the "indirection through variable"
workaround might be more appropriate (DRY: you can use C-h v on the
variable name and get its value and docstring easily) and easier to
implement than more general formatting.

RE: option doc strings and Customize tags

[Drew Adams]

> normally long values will either be indirect (eg, the value of
> variable whose name can be used instead of the value), or they will be
> compounds in which case a compound widget will be used so that the
> components can be changed.

"Normally", no. Typically, yes.

But even variable and function names can be long enough to encumber a menu item
as an annotation. And then there are long string values (regexps, fonts),
sometimes multi-line. And long sexps (e.g. lambdas). And tags themselves can be
long.

A glance at existing defcustoms in the elisp dir shows that. Most values are
short, but some are not.

Take a look at option `align-rules-list', for example. Though compound, many of
its components are very long regexps or lambdas (e.g. over 300 chars). It's not
your average defcustom, but it's by no means abnormal either.

Nevertheless, adding short values to the menu items, next to the tags, is a good
start - certainly better than offering users no correspondence at all. Practice
will then show whether it proves satisfactory.

Come to think of it, the value-vs-tag confusion is really a problem only for
symbol-valued `const' values anyway, for the most part. So adding the value
annotations only for symbol `const' values (in a `choice') would probably not be
too bad a solution. Only the occasional long symbol name plus long tag name
would be problematic.

Re: option doc strings and Customize tags

[Stefan Monnier]

>> normally long values will either be indirect (eg, the value of
>> variable whose name can be used instead of the value), or they will be
>> compounds in which case a compound widget will be used so that the
>> components can be changed.

> "Normally", no. Typically, yes.

I think we should just add the value to the menu, together with some
sanity check: if the printed representation of the value is too long,
then shorten it by replacing the middle chars with "...", and let the
code provide an override for those few remaining cases where it's
not satisfactory.


        Stefan

RE: option doc strings and Customize tags

[Drew Adams]

> I think we should just add the value to the menu, together with some
> sanity check: if the printed representation of the value is too long,
> then shorten it by replacing the middle chars with "...", and let the
> code provide an override for those few remaining cases where it's
> not satisfactory.

That's the abbreviating I suggested. But I'd recommend eliding the terminal
chars, not the middle ones. In the case of a sexp, the normal elision should be
used (e.g. via `print-length') - such as is used in *Backtrace*, but more
abbreviated.

But don't you agree that we need really to provide the value only when it is a
symbol-valued `const' in a `choice'? I think those are about the only cases
where a doc string's reference to a value might lead to confusion wrt the
Customize tags.

If so, then there is no need to worry about sexps and strings and such. It is
only the occasional long symbol name that would need to be abbreviated (at its
end, not middle).

Re: option doc strings and Customize tags

[Stefan Monnier]

> But don't you agree that we need really to provide the value only when it is a
> symbol-valued `const' in a `choice'? I think those are about the only cases
> where a doc string's reference to a value might lead to confusion wrt the
> Customize tags.

You might be right, we could start with just that and then see if we
need more.


        Stefan

RE: option doc strings and Customize tags

[Stephen J. Turnbull]

Drew Adams writes:

 > That's the abbreviating I suggested. But I'd recommend eliding the terminal
 > chars, not the middle ones.

I think I'd want to see some data about that.  Specifically, I know
several places where there are very-long-prefixed-class-INSTANCE
families, and I'd want to know whether these are "rare".  I suspect
not, I think that's a pretty common practice in naming families of
manifest constants.

OTOH, Customize already generally strips group prefixes.  That might
be enough here, it may not often matter because abbreviation is rare.

Re: option doc strings and Customize tags

[Kevin Rodgers]

Lennart Borgman wrote:
> What I tried to say is:
> 
> - In the initial display show all values together, but replace the
> long values with a link.
> 
> - This link should lead to a second display (in *Help*) where also all
> values are shown together. Here the long values should of course be
> shown. There should also be a short explanation what this display is
> about (and a link back, but that is nearly automatic if the first
> display is in *Help* too).

Would it make sense to display long values in the same way as evaluation
results in the *scratch* buffer? i.e. with text properties that allow
the user to toggle between the abbreviated value and the complete value.

-- 
Kevin Rodgers
Denver, Colorado, USA

Re: option doc strings and Customize tags

[Lennart Borgman]

On Thu, Oct 30, 2008 at 6:01 AM, Kevin Rodgers
<kevin.d.rodgers@gmail.com> wrote:
> Lennart Borgman wrote:
>>
>> What I tried to say is:
>>
>> - In the initial display show all values together, but replace the
>> long values with a link.
>>
>> - This link should lead to a second display (in *Help*) where also all
>> values are shown together. Here the long values should of course be
>> shown. There should also be a short explanation what this display is
>> about (and a link back, but that is nearly automatic if the first
>> display is in *Help* too).
>
> Would it make sense to display long values in the same way as evaluation
> results in the *scratch* buffer? i.e. with text properties that allow
> the user to toggle between the abbreviated value and the complete value.

To me it looks like a good idea.