From: David Masterson <dsmasterson@outlook.com>
To: Eric Abrahamsen <eric@ericabrahamsen.net>
Cc: "35261@debbugs.gnu.org" <35261@debbugs.gnu.org>
Subject: bug#35261: 26.1; EBDB Documentation
Date: Mon, 15 Apr 2019 20:56:06 +0000 [thread overview]
Message-ID: <BYAPR07MB5734BFCA4C6BA5993BACEC15A52B0@BYAPR07MB5734.namprd07.prod.outlook.com> (raw)
In-Reply-To: <87a7gronz1.fsf@ericabrahamsen.net> (Eric Abrahamsen's message of "Sun, 14 Apr 2019 22:07:46 -0700")
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
next prev parent reply other threads:[~2019-04-15 20:56 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 [this message]
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
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=BYAPR07MB5734BFCA4C6BA5993BACEC15A52B0@BYAPR07MB5734.namprd07.prod.outlook.com \
--to=dsmasterson@outlook.com \
--cc=35261@debbugs.gnu.org \
--cc=eric@ericabrahamsen.net \
/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.