Re: [Bug-AUCTeX] font-latex-user-keyword-classes doc

[David Kastrup]

Ralf Angeli <address@hidden> writes:

> * Johan Bockgård (2007-10-01) writes:
>
>> David Kastrup <address@hidden> writes:
>>
>>> The DOC string refers to the customize display rather than the actual
>>> values to set this variable to.  That makes it useless as programming
>>> documentation for the variable.  Please use the actual values in the
>>> description while keeping the customize tags: it is obvious which of
>>> the described behaviors they refer to.
>>
>> *Cough* font-latex-user-keyword-classes *cough* (ditto for the
>> variable's description in the manual) ;)
>
> That was a deliberate choice.  The variable is to be used as a
> user-level facility and should be edited through the Customize
> interface because it is quite complicated.

But the DOC strings are also programmer documentation, not just user
level documentation.

> The description already has to cover a lot.  If the low-level
> structures are explained as well, Joe User would likely run off
> scared to death.

Hm? Just explaining the available semantics by referring to the actual
values is not actually doing anything different.  While I agree that
one can use such a customize-only explanation in the manual, I think
that the DOC string for a variable should help with understanding the
code, not just the customization.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum