bug#35261: 26.1; EBDB Documentation

[David Masterson <dsmasterson@outlook.com>]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> On 04/15/19 03:50 AM, David Masterson wrote:
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> David Masterson <dsmasterson@outlook.com> writes:
>>
>>>> This is a documentation problem for EBDB.
>>
>> First, in the "Getting Started" section, there are the two subsections
>> on migration.  At first glance, I assumed (incorrectly) that those were
>> the ways to get started and missed the rest of what was said at the top
>> level.  Therefore, I might suggest that the top level "Getting Started"
>> section be an short intro to EBDB with (perhaps) references to key
>> variables for setup.  Then have three subsections (or more) where the
>> first in creating the database from scratch, second is migration from
>> BBDB, and third is migration from Org Contacts.
>
> That makes sense.
>
>> Second, the top-level should probably reference where to find the
>> internal details of the database structure and record structure(s).
>> This should also be in the subsections to some degree.  Perhaps the
>> top-level should simply reference the details in the sub-levels.
>
> Ditto.
>
>> Third, the creation process should probably have an example script to
>> show the user what to expect.  In particular, I get an error when I try
>> to create my first record in EBDB using 'c'.  I'm not sure if it is a
>> problem with not having setup a database variable, record variable,
>> record structure variable, or what.  I'm just beginning to experiment
>> with EBDB, but I'm familiar with the concepts.  Emacs/EBDB and its
>> extensive variables can make it difficult to determine where to start to
>> configure things if the Info page doesn't lead through it.
>>
>> Fourth, having 'c' tell you that "you have no records" is not to helpful
>> in that what you need is how to setup to create records.
>
> 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.

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

--
David