[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/ebdb b7da024 3/3: Add ebdb-open command, improve docs,
|
From: |
Eric Abrahamsen |
|
Subject: |
[elpa] externals/ebdb b7da024 3/3: Add ebdb-open command, improve docs, bump to 0.6.7 |
|
Date: |
Fri, 19 Apr 2019 20:00:59 -0400 (EDT) |
branch: externals/ebdb
commit b7da024746d650b4dc6eba48155c87f85448b12c
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>
Add ebdb-open command, improve docs, bump to 0.6.7
Thanks to David Masterson for suggestions.
* ebdb-com.el (ebdb-open): New command that just opens a new *EBDB*
buffer.
(ebdb-search-display): Provide more helpful hints if user has no
records.
* ebdb.org: Expand introductory section of manual.
---
ebdb-com.el | 13 +++-
ebdb.el | 2 +-
ebdb.info | 200 ++++++++++++++++++++++++++++++++++++------------------------
ebdb.org | 52 +++++++++++++---
ebdb.texi | 53 +++++++++++++---
5 files changed, 223 insertions(+), 97 deletions(-)
diff --git a/ebdb-com.el b/ebdb-com.el
index 8b0bbfc..39bb8f9 100644
--- a/ebdb-com.el
+++ b/ebdb-com.el
@@ -2081,6 +2081,14 @@ With prefix N, omit the next N records. If negative,
omit backwards."
;; Entry points to EBDB
+;;;###autoload
+(defun ebdb-open ()
+ "Open a buffer in `ebdb-mode'; do nothing else."
+ (interactive)
+ (unless ebdb-db-list
+ (ebdb-load))
+ (ebdb-display-records nil))
+
;; We need to have this first thing in the interactive declaration,
;; because if you check `this-command-keys' after the
;; `ebdb-search-read' interactive bit, it will return ^M.
@@ -2118,7 +2126,10 @@ optional formatter to use."
;; with.
(progn
(ebdb-display-records nil fmt)
- (message "EBDB database is empty"))
+ (message
+ (substitute-command-keys
+ "Database is empty, use\\<ebdb-mode-map>\
+ \\[ebdb-create-record] to create records")))
(message "No matching records")))))
;;;###autoload
diff --git a/ebdb.el b/ebdb.el
index 465340c..61dd417 100644
--- a/ebdb.el
+++ b/ebdb.el
@@ -2,7 +2,7 @@
;; Copyright (C) 2016-2018 Free Software Foundation, Inc.
-;; Version: 0.6.6
+;; Version: 0.6.7
;; Package-Requires: ((emacs "25.1") (cl-lib "0.5") (seq "2.15"))
;; Maintainer: Eric Abrahamsen <address@hidden>
diff --git a/ebdb.info b/ebdb.info
index f34506e..0c8c0ad 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -1,4 +1,4 @@
-This is ebdb.info, produced by makeinfo version 6.5 from ebdb.texi.
+This is ebdb.info, produced by makeinfo version 6.6 from ebdb.texi.
Copyright © 2016 Free Software Foundation, Inc.
@@ -48,6 +48,7 @@ EBDB Manual
Getting Started
+* Starting a New Database::
* Migration from BBDB::
* Migration from Org Contacts::
@@ -153,23 +154,56 @@ File: ebdb.info, Node: Getting Started, Next: The EBDB
Database, Prev: Top,
1 Getting Started
*****************
-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 *note 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 *note Creating Records::).
+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.
+
+ It’s easiest to install EBDB from the ELPA package repositories,
+though it’s also possible to clone the package from Github
+(https:github.com/girzel/ebdb) and put it on your load path. Questions
+and bug reports can be raised on the Github issues page, or on the Emacs
+bug tracker or mailing lists, provided you cc the maintainer.
+
+ 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 *note The EBDB Database::), which controls where
+EBDB stores its records.
+
+ EBDB comes with integration for a few other Emacs packages, including
+Org and a number of mail user agents; see the following sections below
+for details.
* Menu:
+* Starting a New Database::
* Migration from BBDB::
* Migration from Org Contacts::
-File: ebdb.info, Node: Migration from BBDB, Next: Migration from Org
Contacts, Up: Getting Started
+File: ebdb.info, Node: Starting a New Database, Next: Migration from BBDB,
Up: Getting Started
+
+1.1 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 ‘c’ to make new records
+(see *note Creating Records::). You can also hook EBDB into a mail-user
+agent (see *note MUA Interaction::) and allow it to create records
+automatically.
-1.1 Migration from BBDB
+ Otherwise, you’ll want to migrate your contact information from other
+contact management software as described in the sections below.
+Currently EBDB only knows about migrating from BBDB and Org Contacts.
+
+
+File: ebdb.info, Node: Migration from BBDB, Next: Migration from Org
Contacts, Prev: Starting a New Database, Up: Getting Started
+
+1.2 Migration from BBDB
=======================
* Menu:
@@ -180,7 +214,7 @@ File: ebdb.info, Node: Migration from BBDB, Next:
Migration from Org Contacts,
File: ebdb.info, Node: Record Migration, Next: Variables and Options, Up:
Migration from BBDB
-1.1.1 Record Migration
+1.2.1 Record Migration
----------------------
It’s possible to migrate records from a BBDB database. The ‘bbdb-file’
@@ -197,7 +231,7 @@ Migration Errors* buffer. Migration bug reports are very
welcome.
File: ebdb.info, Node: Variables and Options, Prev: Record Migration, Up:
Migration from BBDB
-1.1.2 Variables and Options
+1.2.2 Variables and Options
---------------------------
Many of the old BBDB customization options have been changed or removed
@@ -209,7 +243,7 @@ the “EBDB” group to see what’s available.
File: ebdb.info, Node: Migration from Org Contacts, Prev: Migration from
BBDB, Up: Getting Started
-1.2 Migration from Org Contacts
+1.3 Migration from Org Contacts
===============================
EBDB also provides limited support for migrating from Org Contacts:
@@ -1623,6 +1657,11 @@ see *note EIEIO: (eieio)Top. for information on defining
classes, and
*note Generic Functions: (elisp)Generic Functions. for information on
writing generic functions and methods.
+ Some information about EBDB’s various classes can had from Emacs’
+built-in help system: examining the function definition of a class
+symbol like ‘ebdb-field-anniversary’ will show a documentation string,
+and details of the class’s slot and method definitions.
+
The simplest customization involves changing the default classes used
for basic record and field types.
@@ -2266,8 +2305,8 @@ File: ebdb.info, Node: Index, Prev: Hacking EBDB, Up:
Top
(line 26)
* ebdb-dedicated-window: Customizing Record Display.
(line 19)
-* ebdb-default-address-class: Hacking EBDB. (line 38)
-* ebdb-default-mail-class: Hacking EBDB. (line 32)
+* ebdb-default-address-class: Hacking EBDB. (line 43)
+* ebdb-default-mail-class: Hacking EBDB. (line 37)
* ebdb-default-multiline-collapse: Customizing Record Display.
(line 63)
* ebdb-default-multiline-combine: Customizing Record Display.
@@ -2278,15 +2317,15 @@ File: ebdb.info, Node: Index, Prev: Hacking EBDB,
Up: Top
(line 6)
* ebdb-default-multiline-include: Customizing Record Display.
(line 48)
-* ebdb-default-name-class: Hacking EBDB. (line 26)
-* ebdb-default-notes-class: Hacking EBDB. (line 41)
+* ebdb-default-name-class: Hacking EBDB. (line 31)
+* ebdb-default-notes-class: Hacking EBDB. (line 46)
* ebdb-default-oneline-formatter: Customizing Record Display.
(line 6)
* ebdb-default-oneline-include: Customizing Record Display.
(line 73)
-* ebdb-default-phone-class: Hacking EBDB. (line 35)
+* ebdb-default-phone-class: Hacking EBDB. (line 40)
* ebdb-default-record-class: Creating Records. (line 10)
-* ebdb-default-record-class <1>: Hacking EBDB. (line 19)
+* ebdb-default-record-class <1>: Hacking EBDB. (line 24)
* ebdb-delete-field: Init and Delete Methods.
(line 15)
* ebdb-delete-field-or-record: The Basics of ebdb-mode.
@@ -2404,6 +2443,8 @@ File: ebdb.info, Node: Index, Prev: Hacking EBDB, Up:
Top
(line 11)
* ebdb-omit-records: The Basics of ebdb-mode.
(line 85)
+* ebdb-open: Starting a New Database.
+ (line 6)
* ebdb-org-agenda-popup: Org Integration. (line 32)
* ebdb-popup-window: Writing Integration For New MUAs.
(line 60)
@@ -2516,66 +2557,67 @@ File: ebdb.info, Node: Index, Prev: Hacking EBDB,
Up: Top
Tag Table:
Node: Top807
-Node: Getting Started2607
-Node: Migration from BBDB3262
-Node: Record Migration3473
-Node: Variables and Options4276
-Node: Migration from Org Contacts4763
-Node: The EBDB Database5523
-Node: Creating Records9511
-Node: Record classes10592
-Node: Record names10937
-Node: Record Fields11612
-Node: Inserting New Fields11856
-Node: Editing Existing Fields12652
-Node: Deleting Records and Fields13252
-Node: Field Types13648
-Node: Role fields15934
-Node: Tag field17622
-Node: Mail folder field18266
-Node: MUA Interaction18594
-Node: Loading MUA Code19147
-Node: Display and Updating19860
-Node: Pop-up Buffers20626
-Node: Auto-Updating Records22209
-Node: Noticing and Automatic Rules24609
-Node: Interactive Commands25942
-Node: EBDB and MUA summary buffers28417
-Node: Sender name display28935
-Node: Summary buffer marks30162
-Node: Mail Address Completion31341
-Node: A Note on Completion33850
-Node: Specific MUAs34473
-Node: Gnus34621
-Node: Posting Styles34843
-Node: EBDB Buffers36418
-Node: Searching37629
-Node: Changing Search Behavior39291
-Node: The Basics of ebdb-mode40538
-Node: Customizing Record Display44847
-Node: Marking49167
-Node: Exporting/Formatting49594
-Node: Completion50543
-Node: Snarfing51339
-Node: Internationalization53356
-Node: Diary Integration56057
-Node: Mail Aliases56922
-Node: vCard Support57636
-Node: Org Integration58135
-Node: Citing Records60033
-Node: Hacking EBDB60791
-Node: Field Classes63108
-Node: Init and Delete Methods66244
-Node: The Labeled Field Class67751
-Node: The Singleton Field Class68605
-Node: Actions69043
-Node: Custom Field Searching69715
-Node: Fast Lookups72582
-Node: Formatting in the EBDB Buffer74392
-Node: Writing Internationalization Libraries76468
-Node: Writing Integration For New MUAs80882
-Node: Article snarfing84330
-Node: Index85048
+Node: Getting Started2635
+Node: Starting a New Database3964
+Node: Migration from BBDB4788
+Node: Record Migration5031
+Node: Variables and Options5834
+Node: Migration from Org Contacts6321
+Node: The EBDB Database7081
+Node: Creating Records11069
+Node: Record classes12150
+Node: Record names12495
+Node: Record Fields13170
+Node: Inserting New Fields13414
+Node: Editing Existing Fields14210
+Node: Deleting Records and Fields14810
+Node: Field Types15206
+Node: Role fields17492
+Node: Tag field19180
+Node: Mail folder field19824
+Node: MUA Interaction20152
+Node: Loading MUA Code20705
+Node: Display and Updating21418
+Node: Pop-up Buffers22184
+Node: Auto-Updating Records23767
+Node: Noticing and Automatic Rules26167
+Node: Interactive Commands27500
+Node: EBDB and MUA summary buffers29975
+Node: Sender name display30493
+Node: Summary buffer marks31720
+Node: Mail Address Completion32899
+Node: A Note on Completion35408
+Node: Specific MUAs36031
+Node: Gnus36179
+Node: Posting Styles36401
+Node: EBDB Buffers37976
+Node: Searching39187
+Node: Changing Search Behavior40849
+Node: The Basics of ebdb-mode42096
+Node: Customizing Record Display46405
+Node: Marking50725
+Node: Exporting/Formatting51152
+Node: Completion52101
+Node: Snarfing52897
+Node: Internationalization54914
+Node: Diary Integration57615
+Node: Mail Aliases58480
+Node: vCard Support59194
+Node: Org Integration59693
+Node: Citing Records61591
+Node: Hacking EBDB62349
+Node: Field Classes64940
+Node: Init and Delete Methods68076
+Node: The Labeled Field Class69583
+Node: The Singleton Field Class70437
+Node: Actions70875
+Node: Custom Field Searching71547
+Node: Fast Lookups74414
+Node: Formatting in the EBDB Buffer76224
+Node: Writing Internationalization Libraries78300
+Node: Writing Integration For New MUAs82714
+Node: Article snarfing86162
+Node: Index86880
End Tag Table
diff --git a/ebdb.org b/ebdb.org
index ec0ff9f..5180089 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -5,7 +5,7 @@
#+TEXINFO_HEADER: @syncodeindex ky cp
#+AUTHOR: Eric Abrahamsen <address@hidden>
#+TITLE: EBDB Manual
-#+SUBTITLE: This manual is for version 0.3.2, updated 17 September, 2017
+#+SUBTITLE: This manual is for version 0.6.7, updated 19 April, 2019
#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: EBDB: (ebdb)
#+TEXINFO_DIR_DESC: Contact management package
@@ -32,13 +32,41 @@ is included in the section entitled “GNU Free Documentation
License.”
modify this GNU manual.”
#+END_QUOTE
* Getting Started
-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 [[id:9a02f8fb-01e2-4cd8-8166-608814a031f7][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 {{{buf(EBDB)}}} buffer where you can start to
-make new records (see [[id:692cde31-73be-4faf-b436-7eae8a5d02d1][Creating
Records]]).
+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.
+
+It's easiest to install EBDB from the ELPA package repositories,
+though it's also possible to clone the package from
[[https:github.com/girzel/ebdb][Github]] and put it
+on your load path. Questions and bug reports can be raised on the
+Github issues page, or on the Emacs bug tracker or mailing lists,
+provided you cc the maintainer.
+
+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 [[id:9a02f8fb-01e2-4cd8-8166-608814a031f7][The EBDB
Database]]), which controls where EBDB
+stores its records.
+
+EBDB comes with integration for a few other Emacs packages, including
+Org and a number of mail user agents; see the following sections below
+for details.
+
+** Starting a New Database
+#+FINDEX: ebdb-open
+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
[[id:692cde31-73be-4faf-b436-7eae8a5d02d1][Creating Records]]). You can also
+hook EBDB into a mail-user agent (see
[[id:6a16bc3a-dd20-48af-b532-d5a39da6ab55][MUA Interaction]]) and allow it to
+create records automatically.
+
+Otherwise, you'll want to migrate your contact information from other
+contact management software as described in the sections below.
+Currently EBDB only knows about migrating from BBDB and Org Contacts.
** Migration from BBDB
#+CINDEX: Migration from BBDB
*** Record Migration
@@ -381,6 +409,9 @@ The "mail folder" field is used to indicate which folder or
group
incoming mail from the contact should be filed into. Currently only
Gnus supports this; support in other MUAs is forthcoming.
* MUA Interaction
+:PROPERTIES:
+:ID: 6a16bc3a-dd20-48af-b532-d5a39da6ab55
+:END:
One of EBDB's most important features is the ability to create, update
and display records based on messages received or sent in your mail
user agent(s). In theory, EBDB can be integrated with any software
@@ -1519,6 +1550,11 @@ manual won't go into details about Emacs'
object-orientation support:
see [[info:eieio#Top][EIEIO]] for information on defining classes, and
[[info:elisp#Generic%20Functions][Generic Functions]]
for information on writing generic functions and methods.
+Some information about EBDB's various classes can had from Emacs'
+built-in help system: examining the function definition of a class
+symbol like ~ebdb-field-anniversary~ will show a documentation string,
+and details of the class's slot and method definitions.
+
The simplest customization involves changing the default classes used
for basic record and field types.
diff --git a/ebdb.texi b/ebdb.texi
index 8104981..68993f6 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -34,7 +34,7 @@ modify this GNU manual.”
@finalout
@titlepage
@title EBDB Manual
address@hidden This manual is for version 0.3.2, updated 17 September, 2017
address@hidden This manual is for version 0.6.7, updated 19 April, 2019
@page
@vskip 0pt plus 1filll
@insertcopying
@@ -71,6 +71,7 @@ modify this GNU manual.”
Getting Started
+* Starting a New Database::
* Migration from BBDB::
* Migration from Org Contacts::
@@ -175,19 +176,50 @@ Writing Integration For New MUAs
@node Getting Started
@chapter Getting Started
-Assuming you have no records you want to migrate from other contact
-management software, it is enough to call the top-level @code{ebdb}
-command. This will create a new database at the location specified by
address@hidden (see @ref{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 @ref{Creating Records}).
+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.
+
+It's easiest to install EBDB from the ELPA package repositories,
+though it's also possible to clone the package from
@uref{https:github.com/girzel/ebdb, Github} and put it
+on your load path. Questions and bug reports can be raised on the
+Github issues page, or on the Emacs bug tracker or mailing lists,
+provided you cc the maintainer.
+
+There are a large number of configuration options listed in this
+manual, but the only one you might want to tweak in advance is
address@hidden (see @ref{The EBDB Database}), which controls where EBDB
+stores its records.
+
+EBDB comes with integration for a few other Emacs packages, including
+Org and a number of mail user agents; see the following sections below
+for details.
@menu
+* Starting a New Database::
* Migration from BBDB::
* Migration from Org Contacts::
@end menu
address@hidden Starting a New Database
address@hidden Starting a New Database
+
address@hidden ebdb-open
+If you have no records you want to migrate from other contact
+management software, start by calling the command @code{ebdb-open}. This
+will open a new buffer in @code{ebdb-mode}, and prompt you to create a
+database, if one doesn't already exist. From there, you can use
address@hidden to make new records (see @ref{Creating Records}). You can also
+hook EBDB into a mail-user agent (see @ref{MUA Interaction}) and allow it to
+create records automatically.
+
+Otherwise, you'll want to migrate your contact information from other
+contact management software as described in the sections below.
+Currently EBDB only knows about migrating from BBDB and Org Contacts.
+
@node Migration from BBDB
@section Migration from BBDB
@@ -1759,6 +1791,11 @@ manual won't go into details about Emacs'
object-orientation support:
see @ref{Top,EIEIO,,eieio,} for information on defining classes, and
@ref{Generic Functions,Generic Functions,,elisp,}
for information on writing generic functions and methods.
+Some information about EBDB's various classes can had from Emacs'
+built-in help system: examining the function definition of a class
+symbol like @code{ebdb-field-anniversary} will show a documentation string,
+and details of the class's slot and method definitions.
+
The simplest customization involves changing the default classes used
for basic record and field types.