From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eric Abrahamsen Newsgroups: gmane.emacs.bugs Subject: bug#35261: 26.1; EBDB Documentation Date: Tue, 16 Apr 2019 14:10:26 -0700 Message-ID: <87r2a1k665.fsf@ericabrahamsen.net> References: <87r2a5nyn1.fsf@ericabrahamsen.net> <87a7gronz1.fsf@ericabrahamsen.net> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="204778"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: "35261@debbugs.gnu.org" <35261@debbugs.gnu.org> To: David Masterson Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Apr 16 23:11:16 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hGVMJ-000r82-Jm for geb-bug-gnu-emacs@m.gmane.org; Tue, 16 Apr 2019 23:11:16 +0200 Original-Received: from localhost ([127.0.0.1]:42896 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hGVMI-0007uD-Jz for geb-bug-gnu-emacs@m.gmane.org; Tue, 16 Apr 2019 17:11:14 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:58788) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hGVMA-0007u1-Rp for bug-gnu-emacs@gnu.org; Tue, 16 Apr 2019 17:11:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hGVM7-0003mS-0w for bug-gnu-emacs@gnu.org; Tue, 16 Apr 2019 17:11:06 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52957) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hGVM6-0003mC-OA for bug-gnu-emacs@gnu.org; Tue, 16 Apr 2019 17:11:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hGVM6-0005Mb-G3 for bug-gnu-emacs@gnu.org; Tue, 16 Apr 2019 17:11:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eric Abrahamsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 16 Apr 2019 21:11:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 35261 X-GNU-PR-Package: emacs Original-Received: via spool by 35261-submit@debbugs.gnu.org id=B35261.155544903720569 (code B ref 35261); Tue, 16 Apr 2019 21:11:02 +0000 Original-Received: (at 35261) by debbugs.gnu.org; 16 Apr 2019 21:10:37 +0000 Original-Received: from localhost ([127.0.0.1]:38263 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hGVLg-0005Le-LP for submit@debbugs.gnu.org; Tue, 16 Apr 2019 17:10:37 -0400 Original-Received: from ericabrahamsen.net ([52.70.2.18]:51538 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hGVLe-0005LR-Nx for 35261@debbugs.gnu.org; Tue, 16 Apr 2019 17:10:35 -0400 Original-Received: from localhost (unknown [207.109.85.82]) (Authenticated sender: eric@ericabrahamsen.net) by mail.ericabrahamsen.net (Postfix) with ESMTPSA id 65807FA028; Tue, 16 Apr 2019 21:10:28 +0000 (UTC) In-Reply-To: (David Masterson's message of "Mon, 15 Apr 2019 20:56:06 +0000") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:157740 Archived-At: On 04/15/19 20:56 PM, David Masterson wrote: > Eric Abrahamsen writes: > >> On 04/15/19 03:50 AM, David Masterson wrote: >>> Eric Abrahamsen writes: >>> >>>> David Masterson 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]).