From: Eric Abrahamsen <eric@ericabrahamsen.net>
To: David Masterson <dsmasterson@outlook.com>
Cc: "35261@debbugs.gnu.org" <35261@debbugs.gnu.org>
Subject: bug#35261: 26.1; EBDB Documentation
Date: Tue, 16 Apr 2019 14:10:26 -0700 [thread overview]
Message-ID: <87r2a1k665.fsf@ericabrahamsen.net> (raw)
In-Reply-To: <BYAPR07MB5734BFCA4C6BA5993BACEC15A52B0@BYAPR07MB5734.namprd07.prod.outlook.com> (David Masterson's message of "Mon, 15 Apr 2019 20:56:06 +0000")
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]).
next prev parent reply other threads:[~2019-04-16 21:10 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-04-13 21:26 bug#35261: 26.1; EBDB Documentation David Masterson
2019-04-14 1:50 ` Eric Abrahamsen
2019-04-15 3:50 ` David Masterson
2019-04-15 5:07 ` Eric Abrahamsen
2019-04-15 20:56 ` David Masterson
2019-04-16 18:54 ` Eric Abrahamsen
2019-04-17 3:14 ` David Masterson
2019-04-18 19:51 ` Eric Abrahamsen
2019-04-19 22:22 ` David Masterson
2019-04-16 21:10 ` Eric Abrahamsen [this message]
2019-04-17 3:41 ` David Masterson
2019-04-18 20:33 ` Eric Abrahamsen
2019-04-19 22:31 ` David Masterson
2019-04-20 0:00 ` Eric Abrahamsen
2019-04-21 2:08 ` David Masterson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87r2a1k665.fsf@ericabrahamsen.net \
--to=eric@ericabrahamsen.net \
--cc=35261@debbugs.gnu.org \
--cc=dsmasterson@outlook.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.