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: Sun, 14 Apr 2019 22:07:46 -0700 Message-ID: <87a7gronz1.fsf@ericabrahamsen.net> References: <87r2a5nyn1.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="177587"; 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 Mon Apr 15 07:08: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 1hFtqo-000k3y-LG for geb-bug-gnu-emacs@m.gmane.org; Mon, 15 Apr 2019 07:08:14 +0200 Original-Received: from localhost ([127.0.0.1]:44769 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hFtqn-0004kA-JQ for geb-bug-gnu-emacs@m.gmane.org; Mon, 15 Apr 2019 01:08:13 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:33864) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hFtqe-0004id-4F for bug-gnu-emacs@gnu.org; Mon, 15 Apr 2019 01:08:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hFtqc-0006vG-VA for bug-gnu-emacs@gnu.org; Mon, 15 Apr 2019 01:08:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:48231) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hFtqc-0006v3-CT for bug-gnu-emacs@gnu.org; Mon, 15 Apr 2019 01:08:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hFtqc-0006Um-3G for bug-gnu-emacs@gnu.org; Mon, 15 Apr 2019 01:08: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: Mon, 15 Apr 2019 05:08: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.155530487724958 (code B ref 35261); Mon, 15 Apr 2019 05:08:02 +0000 Original-Received: (at 35261) by debbugs.gnu.org; 15 Apr 2019 05:07:57 +0000 Original-Received: from localhost ([127.0.0.1]:33542 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hFtqX-0006UU-FV for submit@debbugs.gnu.org; Mon, 15 Apr 2019 01:07:57 -0400 Original-Received: from ericabrahamsen.net ([52.70.2.18]:53062 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hFtqU-0006UI-6d for 35261@debbugs.gnu.org; Mon, 15 Apr 2019 01:07:55 -0400 Original-Received: from localhost (97-126-87-168.tukw.qwest.net [97.126.87.168]) (Authenticated sender: eric@ericabrahamsen.net) by mail.ericabrahamsen.net (Postfix) with ESMTPSA id 25E78FA05C; Mon, 15 Apr 2019 05:07:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ericabrahamsen.net; s=mail; t=1555304868; bh=9a6F+eM/nattGxJAYYXOoDtgYVZKssTso+m17ENBG9A=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=K7vbRp3a9yfGRTsr0rxZdfJo5zPpxsEvGOG8JX5pWlyOgisE+VPd4g72DhONFT8IH QYAVyQbE5DuEqsJ1SQlKk9QMDNV3tDEn1DvrV/g51ddZo22ajj6aW3TgCtLhgaJ0vE qxhjy7AZ8DGwUPogRNmJWaoGBB4g9TCbvknk7Wnk= In-Reply-To: (David Masterson's message of "Mon, 15 Apr 2019 03:50:56 +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:157651 Archived-At: On 04/15/19 03:50 AM, David Masterson wrote: > Eric Abrahamsen writes: > >> David Masterson writes: > >>> This is a documentation problem for EBDB. >>> >>> The documentation lacks clarity on how to setup EBDB for the first time >>> in the case where you are *not* converting from BBDB or Org Contacts. >>> More information is needed on how to create an EBDB database for the >>> first time, how to setup the first record(s) that you put into the >>> database, and (perhaps) an example session. As it is, the documentation >>> is too esoteric for someone unfamiliar with EBDB (or BBDB) concepts to >>> make heads or tails of it and get their feet wet. >> >> Thanks for this report. Here's what the docs have now: >> >> Assuming you have no records you want to migrate from other contact >> management software, it is enough to call the top-level ~ebdb~ command. >> This will create a new database at the location specified by >> ~ebdb-sources~ (see [The EBDB Database]), prompt you for a search >> string, fail to find anything (because you don't have any records yet), >> and finally open a EBDB buffer where you can start to make new records >> (see [Creating Records]). >> >> This is correct, though admittedly terse! I suppose I could break this >> out more specifically: you should set `ebdb-sources' in advance. Then >> you can create your new database either by calling the `ebdb' command, >> or by associating EBDB with a mail user agent, and letting that agent >> create records for you. >> >> Or perhaps, if you have no records, the `ebdb' command could simply open >> an *EBDB* buffer and then tell you, "you have no records, use 'c' to >> create one"? >> >> WDYT? > > 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'). '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. > Fifth, there is no EBDB mailing list to ask questions on?? I don't think new mailing lists are made for specific packages very often any more. In the case of EBDB, you can open an issue on the github page, email me directly, or do what you've done here, which is just fine (so long as you cc me). There's been some talk in the past about having the bug reporter prompt for specific packages to report bugs against, but that hasn't gone anywhere yet. Yours, Eric