bug#35261: 26.1; EBDB Documentation

[David Masterson]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> On 04/17/19 03:14 AM, David Masterson wrote:
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> On 04/15/19 20:56 PM, David Masterson wrote:
>>
>>>> On that, it seems that the documentation is still evolving in that
>>>> area. For instance, looking at the documentation of ebdb-field-*
>>>> variables says that they are obsolete as of 25.1 and the documentation
>>>> is relatively low, so the error above would be confusing in that you'd
>>>> wonder if you were looking at the right variable.
>>
>>> Unfortunately this doesn't have to do with EBDB, but rather with a weird
>>> interaction between the help system and EIEIO. Class names apparently
>>> once functioned as variables, but no longer do, and so Emacs complains
>>> when you try to treat one as a variable. You'll have better luck using
>>> help to look up the *function* definitions of the class names, not the
>>> variable definition.
>>
>> Ouch!  That's not logical and will need some explanation somewhere.  The
>> logical assumption would be that the function that is asking for input
>> is using some variable (structure) as a reference for what it expects as
>> input, so, when the error reports a name in the error, the first thought
>> would be that that is the structure to look at to get the clue as to
>> what it's looking for.  It's a little confusing (to say the least) for
>> the lay person to see functions and variables with the same name.
>>
>> Something to lay out a little more as a primer in the Info docs?
>
> Mmm, I'm not really inclined to spend a lot of time explaining the
> weirdnesses of Emacs help system in the EBDB manual, but maybe a pointer
> to the function docstrings of the class symbols would be okay.

Yeah, something to point you in the right direction.  Try not to make it
too 'lispy' for the newbies...

--
David