Eli Zaretskii <
eliz@gnu.org> writes:
>> * doc/lispref/customize.texi (Defining Customization Variables):
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> The name in parentheses should be the name of the node, not of the
> section.
Right, sorry.
>> +Re-evaluating a @code{defcustom} form of an already defined user
>> +option does not clear the reasonable values added by previous
>> +evaluations, or by calls to @code{custom-add-frequent-value}. This
>> +way, Lisp programs can add reasonable values for user options not yet
>> +defined.
>
> This doesn't emphasize the fact that you are talking about
> reevaluation after changing the option's values. Without that, this
> text doesn't drive the point home.
Then perhaps it makes sense to split the paragraph, and talk about that
when describing the :options keyword? I did that in this new patch.
> Also, I'd suggest to drop the "reasonable" part, as it gets in the way
> of understanding the important parts by distracting the reader to
> think about what "reasonable" means in this context.
Fair enough. Dropped it.
>> --- a/lisp/custom.el
>> +++ b/lisp/custom.el
>> @@ -578,9 +578,14 @@ custom-add-dependencies
>> (defun custom-add-option (symbol option)
>> "To the variable SYMBOL add OPTION.
>>
>> +Custom then presents OPTION to the user as a suggested member
>> +for the value of SYMBOL.
>> +
>> If SYMBOL's custom type is a hook, OPTION should be a hook member.
>> -If SYMBOL's custom type is an alist, OPTION specifies a symbol
>> -to offer to the user as a possible key in the alist.
>> +If SYMBOL's custom type is an alist, OPTION specifies a possible key
>> +in the alist.
>> +Similarly, if SYMBOL's custom type is a plist, OPTION specifies
>> +a possible name in the plist.
>> For other custom types, this has no effect."
>
> I don't think I understand what this tries to accomplish, or how it is
> relevant to the issue discussed here.
The docstring didn't mention what was the effect if SYMBOL was a plist,
so I thought I'd take the chance of improving the docstring for the
function that also affects the suggested values. But maybe that can be
left for another patch, so I dropped it in this new one.
Thanks for reviewing, I hope this patch is better.
0001-Improve-documentation-for-custom-options.patch