bug#35261: 26.1; EBDB Documentation

[Eric Abrahamsen <eric@ericabrahamsen.net>]

On 04/15/19 20:56 PM, David Masterson wrote:
> 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.

Here's what the new version looks like:

* Getting Started
EBDB is a contact management package: it records information about
people and organizations, and integrates with other Emacs software
packages, mostly those concerned with sending and reading mail.  The
principle parts of EBDB are records, which represent people and
organizations; fields, representing detailed data about records; and
databases, which hold and persist records.

There are a large number of configuration options listed in this
manual, but the only one you might want to tweak in advance is
~ebdb-sources~ (see [The EBDB Database]), which controls where EBDB
stores its records.

** Starting a New Database
If you have no records you want to migrate from other contact
management software, start by calling the command ~ebdb-open~.  This
will open a new buffer in ~ebdb-mode~, and prompt you to create a
database, if one doesn't already exist.  From there, you can use
{{{kbd(c)}}} to make new records (see [Creating Records]).