bug#35261: 26.1; EBDB Documentation

[Eric Abrahamsen]

On 04/15/19 20:56 PM, David Masterson wrote:
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:

[...]

>> This doesn't seem right: it's the `ebdb' command that tells you the
>> database is empty (and that message should include a mention of 'c').
>
> Actually, the first thing that the 'ebdb' seems to do is ask for a
> search string which is a little surprising on an empty database. I can
> see that people might want a quick command to find something in their
> database, but you shouldn't overload the 'ebdb' command that way. Have
> one command (ebdb) to startup EBDB and another command to start it up
> and find a record. Or, perhaps, two separate commands which people
> could always script together.

Okay, it would make sense to have an `ebdb-start' command that just
opens an *EBDB* buffer.

>> 'c' prompts for the creation of a record. Do you remember what sort of
>> error you got during record creation? There shouldn't be anything you
>> have to do in advance, except maybe confirm that you want to create a
>> new database at the default location.
>
> Good point. I kind of messed up that statement. The error I got was an
> error that basically is that I was putting in data for a field that was
> improper for the field. In this case, it was looking for an *email*
> address and I was assuming that any old text string would do. The error
> did not give the clue that it was specifically looking for a string that
> was formatted for "name@machine.com". So, there should be a clue in the
> documentation on how to read the error -- basically that the error is
> pointing out that the input doesn't fit the defined structure and (most
> importantly) how to find out what the defined structure is. 

Sure, I can add this as well. Actually I'm on the fence about requiring
a "@" in mail fields at all, as it's possible someone might want to note
a machine-local address for someone. I can't decide. But there are a few
other fields (like the url field) that also do a bit of validation, and
it would be good to explain that.

> 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.

Eric