[elpa] externals/ebdb 84b348e 311/350: Basic finished version of manual

[Eric Abrahamsen]

branch: externals/ebdb
commit 84b348e2307b08572e864bc4c526e9d00c87fc6e
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>

    Basic finished version of manual
    
    Fixes #8
    
    * ebdb.org: Mainly added more stuff about EBDB buffers and ebdb-mode.
    * ebdb.texi:
    * ebdb.info: Produce new manual.
    * ebdb-com.el (ebdb-info): This command can now be used correctly.
---
 ebdb-com.el |   4 +-
 ebdb.info   | 509 ++++++++++++++++++++++++++++++++++++++++++++++--------------
 ebdb.org    | 149 ++++++++++++++++--
 ebdb.texi   | 292 ++++++++++++++++++++++++++++++++--
 4 files changed, 810 insertions(+), 144 deletions(-)

diff --git a/ebdb-com.el b/ebdb-com.el
index da54005..2ff9689 100644
--- a/ebdb-com.el
+++ b/ebdb-com.el
@@ -2766,9 +2766,7 @@ With prefix argument ARG, prompt for which mail address 
to use."
 ;;;###autoload
 (defun ebdb-info ()
   (interactive)
-  (message "The manual is not yet complete, please see ebdb.org")
-;  (info (format "(%s)Top" (or ebdb-info-file "ebdb")))
-  )
+  (info (format "(%s)Top" (or ebdb-info-file "ebdb"))))
 
 ;;;###autoload
 (defun ebdb-help ()
diff --git a/ebdb.info b/ebdb.info
index 7da1454..b9af231 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -30,12 +30,15 @@ EBDB Manual
 * Creating Records::
 * Record Fields::
 * MUA Interaction::
-* *EBDB* Buffers::
+* EBDB Buffers::
+* Completion::
 * Snarfing::
 * Internationalization::
 * Diary Integration::
 * Mail Aliases::
 * vCard Support::
+* Org Integration::
+* Citing Records::
 * Hacking EBDB::
 * Index::
 
@@ -87,9 +90,10 @@ EBDB and MUA summary buffers
 * Sender name display::
 * Summary buffer marks::
 
-*EBDB* Buffers
+EBDB Buffers
 
 * Searching::
+* The Basics of ebdb-mode::
 * Marking::
 * Exporting/Formatting::
 
@@ -102,6 +106,9 @@ Searching
 
 
 
+
+
+
 Hacking EBDB
 
 * Field Classes::
@@ -227,7 +234,9 @@ file, it’s safer to use the customization interface to do 
so from the
 also possible for a single record to live in more than one database,
 though this functionality is experimental.  When a record is loaded from
 more than one database, the two copies are compared using the
-“timestamp” field, and the older copy is discarded.
+“timestamp” field, and the older copy is discarded.  In an *EBDB*
+buffer, the following keys can be used to manipulate databases and their
+records.
 
 ‘d m’     (‘ebdb-move-record record to-db’)
 
@@ -404,7 +413,7 @@ of labels (for instance, anniversary fields may be labeled 
“birthday”,
    Loading secondary libraries may make more field types available.
 
 
-File: ebdb.info,  Node: MUA Interaction,  Next: *EBDB* Buffers,  Prev: Record 
Fields,  Up: Top
+File: ebdb.info,  Node: MUA Interaction,  Next: EBDB Buffers,  Prev: Record 
Fields,  Up: Top
 
 5 MUA Interaction
 *****************
@@ -427,17 +436,18 @@ File: ebdb.info,  Node: Loading MUA Code,  Next: Display 
and Updating,  Up: MUA
 5.1 Loading MUA Code
 ====================
 
-:ORDERED: t MUA code is activated simply by loading the relevant
-library.  Keep in mind that mail-reading clients and mail-sending
-clients are considered separate MUAs.  For instance, if you use the Gnus
-package for reading mail, and Message for sending it, you’ll want two
-require statements:
+MUA code is activated simply by loading the relevant library.  Keep in
+mind that mail-reading clients and mail-sending clients are considered
+separate MUAs.  For instance, if you use the Gnus package for reading
+mail, and Message for sending it, you’ll want two require statements:
 
      (require 'ebdb-gnus)
      (require 'ebdb-message)
 
    There are other packages that provide other MUA integration: these
-are likewise activated simply by requiring the relevant library.
+are likewise activated simply by requiring the relevant library, named
+“ebdb-<MUA>”.  MUAs supported by EBDB include gnus, message, mh-e, mu4e,
+rmail, and VM.
 
 
 File: ebdb.info,  Node: Display and Updating,  Next: EBDB and MUA summary 
buffers,  Prev: Loading MUA Code,  Up: MUA Interaction
@@ -735,15 +745,12 @@ string provided by Gnus or VM, and adding the 
EBDB-specific format code:
      record.  Defaults to “e”.
 
 
-File: ebdb.info,  Node: *EBDB* Buffers,  Next: Snarfing,  Prev: MUA 
Interaction,  Up: Top
+File: ebdb.info,  Node: EBDB Buffers,  Next: Completion,  Prev: MUA 
Interaction,  Up: Top
 
-6 *EBDB* Buffers
-****************
+6 EBDB Buffers
+**************
 
-EBDB buffers inherit from special-mode, and so the usual special-mode
-keybindings apply.
-
-   EBDB can create several separate buffers for displaying contacts.
+EBDB can create several separate buffers for displaying contacts.
 Typically, each MUA creates its own buffer, with names like *EBDB-Gnus*,
 etc.  Users can also create their own buffers that won’t be interfered
 with by MUA pop-up action.  Calling the ‘ebdb’ command directly will
@@ -770,11 +777,12 @@ existing EBDB buffers.
 * Menu:
 
 * Searching::
+* The Basics of ebdb-mode::
 * Marking::
 * Exporting/Formatting::
 
 
-File: ebdb.info,  Node: Searching,  Next: Marking,  Up: *EBDB* Buffers
+File: ebdb.info,  Node: Searching,  Next: The Basics of ebdb-mode,  Up: EBDB 
Buffers
 
 6.1 Searching
 =============
@@ -817,6 +825,12 @@ use “/ n”, “| n”, or “+ n”.  Search keys that work this 
way are:
 
    • “/ d”: Search duplicate records
 
+   Searches can be inverted:
+
+‘!’     (‘ebdb-search-invert’)
+
+     Invert the results of the next search.
+
    Each user-created *EBDB* buffer keeps track of search history in that
 buffer.  To pop back to previous searches, use:
 
@@ -860,9 +874,135 @@ process happens /after/ the transform functions have run, 
so there is a
 possibility for unexpected search behavior.
 
 
-File: ebdb.info,  Node: Marking,  Next: Exporting/Formatting,  Prev: 
Searching,  Up: *EBDB* Buffers
+File: ebdb.info,  Node: The Basics of ebdb-mode,  Next: Marking,  Prev: 
Searching,  Up: EBDB Buffers
+
+6.2 The Basics of ebdb-mode
+===========================
+
+EBDB buffers inherit from special-mode, and so the usual special-mode
+keybindings apply.
+
+‘n’     (‘ebdb-next-record’)
+
+     Move point to the next record.
+
+‘p’     (‘ebdb-prev-record’)
+
+     Move point to the previous record.
+
+‘N’     (‘ebdb-next-field’)
+
+     Move point to the next field.
+
+‘P’     (‘ebdb-prev-field’)
+
+     Move point to the previous field.
+
+‘c’     (‘ebdb-create-record’)
+
+     Create a new person record in the primary database.
+
+‘C’     (‘ebdb-create-record-extended’)
+
+     Prompt for database and record class, then create a new record.
+
+‘i’     (‘ebdb-insert-field’)
+
+     Insert a new field into the record under point, or the marked
+     records.
+
+‘e’     (‘ebdb-edit-field’)
+
+     Edit the field under point.
+
+‘E’     (‘ebdb-edit-field-customize’)
+
+     Use the extended customize interface to edit the field under point.
+
+‘;’     (‘ebdb-edit-foo’)
+
+     Either insert/edit the record’s notes field or, with a prefix arg,
+     prompt for an existing field and edit it.
+
+‘C-k’     (‘ebdb-delete-field-or-record’)
+
+     With point on a record field, offer to delete that field.  With
+     point on a record header, offer to delete the whole record.
+
+‘RET’     (‘ebdb-record-action’)
+
+     Run an “action” on the field under point.  If multiple actions are
+     provided, you’ll be prompted to choose one.  Not all fields provide
+     actions.  “RET” on a mail field will compose a message to that mail
+     address
+
+‘m’     (‘ebdb-mail’)
+
+     Begin composing a message to the record under point.  With a prefix
+     arg, prompt for the mail address to use; otherwise use the record’s
+     primary address.
+
+‘t’     (‘ebdb-toggle-records-format’)
 
-6.2 Marking
+     Toggle between a multi-line and one-line display.
+
+‘T’     (‘ebdb-display-records-completely’)
+
+     Display all of a record’s fields.
+
+‘r’     (‘ebdb-reformat-records’)
+
+     Redisplay the record under point.
+
+‘o’     (‘ebdb-omit-records’)
+
+     Remove the record under point (or marked records) from the buffer
+     (does not delete the records).
+
+‘w f’     (‘ebdb-copy-fields-as-kill’)
+
+     Copy the string value of the field under point to the kill ring.
+
+‘w r’     (‘ebdb-copy-records-as-kill’)
+
+     Copy a string representation of the whole record under point to the
+     kill ring.
+
+‘w m’     (‘ebdb-copy-mail-as-kill’)
+
+     Copy a name-plus-mail string citation for the record under point to
+     the kill ring.  These strings look like “John Q Public
+     <address@hidden>”.  By default this will use the record’s primary
+     address; supply a prefix arg to be prompted for which address to
+     use.
+
+‘g’     (‘revert-buffer’)
+
+     Redisplay all visible records.
+
+‘?’     (‘ebdb-help’)
+
+     Show a very brief help message.
+
+‘h’     (‘ebdb-info’)
+
+     Open this manual.
+
+‘s’     (‘ebdb-save’)
+
+     Save all databases.
+
+‘q’     (‘quit-window’)
+
+     Delete the *EBDB* window.
+
+   *note Creating Records:: and *note Record Fields:: for more on record
+creation and field manipulation.
+
+
+File: ebdb.info,  Node: Marking,  Next: Exporting/Formatting,  Prev: The 
Basics of ebdb-mode,  Up: EBDB Buffers
+
+6.3 Marking
 ===========
 
 Records can be marked and acted on in bulk.  The “#” key will toggle the
@@ -871,9 +1011,9 @@ records in the buffer, and “C-#” will unmark all records 
in the buffer.
 Many editing commands can act on multiple marked records.
 
 
-File: ebdb.info,  Node: Exporting/Formatting,  Prev: Marking,  Up: *EBDB* 
Buffers
+File: ebdb.info,  Node: Exporting/Formatting,  Prev: Marking,  Up: EBDB Buffers
 
-6.3 Exporting/Formatting
+6.4 Exporting/Formatting
 ========================
 
 It is possible to export (referred to as “formatting”) records in
@@ -898,9 +1038,34 @@ is unsupported: the only options are version 3.0 and 4.0.
    It’s possible to write new formatters, documentation is forthcoming.
 
 
-File: ebdb.info,  Node: Snarfing,  Next: Internationalization,  Prev: *EBDB* 
Buffers,  Up: Top
+File: ebdb.info,  Node: Completion,  Next: Snarfing,  Prev: EBDB Buffers,  Up: 
Top
+
+7 Completion
+************
+
+There are many Emacs completion frameworks out there, and EBDB comes
+with support for helm, counsel, and company.  See the relevant
+libraries; they provide the commands ‘helm-ebdb’, ‘counsel-ebdb’, and
+‘company-ebdb’, respectively.  Counsel and company are made to be hooked
+into Emacs’ existing completion frameworks; the helm command must be
+called explicitly.
+
+   Another library, ‘ebdb-complete’, uses an ephemeral pop-up *EBDB*
+buffer for record completion.  The command ‘ebdb-complete’ provides an
+interactive entry point, or you can enable it for “TAB” in
+‘message-mode’ by calling ‘ebdb-complete-enable’.
+
+   Several native EBDB commands involve selecting a record, or multiple
+records.  At present, the completion interface for these commands is a
+bit random: several of the commands simply use ‘completing-read’
+directly, which isn’t right.  At some point, all EBDB commands that ask
+the user to select a record will become aware of the currently-loaded
+completion frameworks.
 
-7 Snarfing
+
+File: ebdb.info,  Node: Snarfing,  Next: Internationalization,  Prev: 
Completion,  Up: Top
+
+8 Snarfing
 **********
 
 “Snarfing” refers to scanning free-form text and extracting information
@@ -947,12 +1112,12 @@ article headers.
 
 File: ebdb.info,  Node: Internationalization,  Next: Diary Integration,  Prev: 
Snarfing,  Up: Top
 
-8 Internationalization
+9 Internationalization
 **********************
 
 EBDB comes with an internationalization framework that can provide
 country- and region-specific behavior for certain fields.  This
-functionality is initialized by loading the ‘ebdb-i10n’ library.  This
+functionality is initialized by loading the ‘ebdb-i18n’ library.  This
 library does nothing by itself, it simply provides hooks for other
 country-specific libraries, which must be loaded separately.
 
@@ -968,7 +1133,7 @@ welcome, though less enthusiastically, are requests for 
new libraries.
    Internationalization libraries do not modify the database in any way,
 and can be safely unloaded.  They simply alter the way EBDB reads,
 parses and displays field values, and can also store extra information
-(eg. for searching purposes) in a record’s cache.  Loading this library
+(eg.g for searching purposes) in a record’s cache.  Loading this library
 can (depending on country libraries’ behavior) increase database load
 times, though it should not significantly affect search or display
 performance.
@@ -976,8 +1141,8 @@ performance.
 
 File: ebdb.info,  Node: Diary Integration,  Next: Mail Aliases,  Prev: 
Internationalization,  Up: Top
 
-9 Diary Integration
-*******************
+10 Diary Integration
+********************
 
 Some EBDB fields hold dates or anniversaries (most notably the
 ‘ebdb-field-anniversary’ field).  It’s possible to integrate this
@@ -1000,7 +1165,7 @@ are forthcoming.
 
 File: ebdb.info,  Node: Mail Aliases,  Next: vCard Support,  Prev: Diary 
Integration,  Up: Top
 
-10 Mail Aliases
+11 Mail Aliases
 ***************
 
 You can give records a mail alias with the “mail alias” field, available
@@ -1015,9 +1180,9 @@ the “A” key in a *EBDB* buffer.  This limitation will be 
removed in the
 future.
 
 
-File: ebdb.info,  Node: vCard Support,  Next: Hacking EBDB,  Prev: Mail 
Aliases,  Up: Top
+File: ebdb.info,  Node: vCard Support,  Next: Org Integration,  Prev: Mail 
Aliases,  Up: Top
 
-11 vCard Support
+12 vCard Support
 ****************
 
 EBDB has rudimentary support for exporting to vCard format; this
@@ -1029,9 +1194,58 @@ formatting EBDB records (see *note 
Exporting/Formatting::).
 eventually, support for CardDav servers.
 
 
-File: ebdb.info,  Node: Hacking EBDB,  Next: Index,  Prev: vCard Support,  Up: 
Top
+File: ebdb.info,  Node: Org Integration,  Next: Citing Records,  Prev: vCard 
Support,  Up: Top
+
+13 Org Integration
+******************
+
+EBDB has standard support for Org functionality: creating links to EBDB
+records works as expected with “C-c l”, and following a link will open
+an *EBDB* buffer and display the linked record.
+
+   Typically, links are created using the record’s UUID field – these
+links are fast and accurate – but it’s also possible to create links
+that initiate an EBDB search, and return multiple records.  EBDB links
+are of the format “ebdb:<field type>/<search string>”.  The “field type”
+is typically the name of an EBDB field class (for instance,
+“ebdb-field-anniversary”), and opening a link of this sort results in a
+search of all records for which <search string> matches the string value
+of that particular field type.  For convenience, a few field type
+shorthands are recognized: in addition to “uuid”, there is “mail”,
+“phone”, “address”, “notes” and “tags” (see below).  For instance, to
+create a link to all records with a 206 phone area code, use
+“<phone/206>”, and to create a link to all records who work at Google,
+use “<mail/google.com>”.
+
+   The ‘ebdb-org’ library also contains the ‘ebdb-org-field-tags’ field
+class, allowing users to tag their contacts with existing Org tags.
+Completion is offered as expected.  The field doesn’t do much else, at
+present, but in the future there will be options for popping up an
+*EBDB* buffer alongside an Org agenda buffer, etc.
+
+
+File: ebdb.info,  Node: Citing Records,  Next: Hacking EBDB,  Prev: Org 
Integration,  Up: Top
+
+14 Citing Records
+*****************
+
+Often one wants to share contact information into other channels: for
+instance, pasting a contact’s name and mail address in a message you’re
+sending to someone else.  EBDB refers to this as “citing”, and provides
+a general interface to this through:
+
+ -- Command: ebdb-cite-records
+
+     This command is not bound in any mode, but can be called
+     interactively.  It prompts for a record, then inserts a citation
+     for the record into the current buffer.  In most text-mode buffers,
+     the citation looks like “Some Name <address@hidden>”.  In Org
+     buffers, it is a link with a “mailto:” prefix.
+
+
+File: ebdb.info,  Node: Hacking EBDB,  Next: Index,  Prev: Citing Records,  
Up: Top
 
-12 Hacking EBDB
+15 Hacking EBDB
 ***************
 
 EBDB is designed to be highly extensible.  In addition to the usual
@@ -1097,7 +1311,7 @@ existing objects.  This may be addressed in the future.
 
 File: ebdb.info,  Node: Field Classes,  Up: Hacking EBDB
 
-12.1 Field Classes
+15.1 Field Classes
 ==================
 
 It’s fairly easy to create your own custom field classes in EBDB. All
@@ -1167,7 +1381,7 @@ default values for the new object.
 
 File: ebdb.info,  Node: Init and Delete Methods,  Next: The Labeled Field 
Class,  Up: Field Classes
 
-12.1.1 Init and Delete Methods
+15.1.1 Init and Delete Methods
 ------------------------------
 
 It’s also very common to define ‘ebdb-init-field’ and
@@ -1207,7 +1421,7 @@ which is non-nil when the record is being unloaded, 
rather than deleted.
 
 File: ebdb.info,  Node: The Labeled Field Class,  Next: Actions,  Prev: Init 
and Delete Methods,  Up: Field Classes
 
-12.1.2 The Labeled Field Class
+15.1.2 The Labeled Field Class
 ------------------------------
 
 Many field classes maintain their own list of labels: ie, anniversary
@@ -1226,7 +1440,7 @@ used to hold labels, and pointing to it in the 
class-allocated
 
 File: ebdb.info,  Node: Actions,  Next: Custom Field Searching,  Prev: The 
Labeled Field Class,  Up: Field Classes
 
-12.1.3 Actions
+15.1.3 Actions
 --------------
 
 All field classes have a class-allocated slot called “actions”.  The
@@ -1242,7 +1456,7 @@ and the field instance under point.
 
 File: ebdb.info,  Node: Custom Field Searching,  Next: Formatting in the EBDB 
Buffer,  Prev: Actions,  Up: Field Classes
 
-12.1.4 Custom Field Searching
+15.1.4 Custom Field Searching
 -----------------------------
 
 In most cases, searching the EBDB database is a matter of prompting for
@@ -1278,7 +1492,7 @@ instance, and then other-search-criteria will be passed 
to the
 
 File: ebdb.info,  Node: Formatting in the EBDB Buffer,  Prev: Custom Field 
Searching,  Up: Field Classes
 
-12.1.5 Formatting in the EBDB Buffer
+15.1.5 Formatting in the EBDB Buffer
 ------------------------------------
 
 Most fields will be displayed in the *EBDB* buffer simply using
@@ -1326,86 +1540,155 @@ Index
 [index]
 * Menu:
 
-* Creating a database:                   The EBDB Database.    (line 11)
-* Creating records:                      Creating Records.     (line  6)
+* Creating a database:                   The EBDB Database.   (line  11)
+* Creating records:                      Creating Records.    (line   6)
 * Deleting records and fields:           Deleting records and fields.
-                                                               (line  6)
-* Diary integration:                     Diary Integration.    (line  6)
-* ebdb-clone-buffer:                     *EBDB* Buffers.       (line 22)
-* ebdb-copy-record record to-db:         The EBDB Database.    (line 65)
-* ebdb-customize-database db:            The EBDB Database.    (line 51)
-* ebdb-disable-database db:              The EBDB Database.    (line 76)
-* ebdb-format-all-records:               Exporting/Formatting. (line 20)
-* ebdb-format-to-tmp-buffer:             Exporting/Formatting. (line 14)
-* ebdb-move-record record to-db:         The EBDB Database.    (line 61)
-* ebdb-mua-display-all-recipients:       Interactive Commands. (line 63)
-* ebdb-mua-display-all-records:          Interactive Commands. (line 18)
-* ebdb-mua-display-recipients:           Interactive Commands. (line 59)
-* ebdb-mua-display-sender:               Interactive Commands. (line 55)
-* ebdb-mua-edit-sender-notes:            Interactive Commands. (line 23)
-* ebdb-mua-in-ebdb-buffer:               Interactive Commands. (line 28)
-* ebdb-mua-snarf-article:                Interactive Commands. (line 36)
-* ebdb-mua-snarf-article <1>:            Snarfing.             (line 42)
-* ebdb-mua-update-records:               Interactive Commands. (line 12)
-* ebdb-mua-yank-cc:                      Interactive Commands. (line 46)
-* ebdb-reload-database db:               The EBDB Database.    (line 71)
-* ebdb-rename-buffer:                    *EBDB* Buffers.       (line 27)
-* ebdb-search-pop:                       Searching.            (line 47)
-* ebdb-snarf &optional string start end recs: Snarfing.        (line 15)
+                                                              (line   6)
+* Diary integration:                     Diary Integration.   (line   6)
+* ebdb-cite-records:                     Citing Records.      (line  11)
+* ebdb-clone-buffer:                     EBDB Buffers.        (line  19)
+* ebdb-copy-fields-as-kill:              The Basics of ebdb-mode.
+                                                              (line  86)
+* ebdb-copy-mail-as-kill:                The Basics of ebdb-mode.
+                                                              (line  95)
+* ebdb-copy-record record to-db:         The EBDB Database.   (line  67)
+* ebdb-copy-records-as-kill:             The Basics of ebdb-mode.
+                                                              (line  90)
+* ebdb-create-record:                    The Basics of ebdb-mode.
+                                                              (line  25)
+* ebdb-create-record-extended:           The Basics of ebdb-mode.
+                                                              (line  29)
+* ebdb-customize-database db:            The EBDB Database.   (line  51)
+* ebdb-delete-field-or-record:           The Basics of ebdb-mode.
+                                                              (line  51)
+* ebdb-disable-database db:              The EBDB Database.   (line  78)
+* ebdb-display-records-completely:       The Basics of ebdb-mode.
+                                                              (line  73)
+* ebdb-edit-field:                       The Basics of ebdb-mode.
+                                                              (line  38)
+* ebdb-edit-field-customize:             The Basics of ebdb-mode.
+                                                              (line  42)
+* ebdb-edit-foo:                         The Basics of ebdb-mode.
+                                                              (line  46)
+* ebdb-format-all-records:               Exporting/Formatting.
+                                                              (line  20)
+* ebdb-format-to-tmp-buffer:             Exporting/Formatting.
+                                                              (line  14)
+* ebdb-help:                             The Basics of ebdb-mode.
+                                                              (line 107)
+* ebdb-info:                             The Basics of ebdb-mode.
+                                                              (line 111)
+* ebdb-insert-field:                     The Basics of ebdb-mode.
+                                                              (line  33)
+* ebdb-mail:                             The Basics of ebdb-mode.
+                                                              (line  63)
+* ebdb-move-record record to-db:         The EBDB Database.   (line  63)
+* ebdb-mua-display-all-recipients:       Interactive Commands.
+                                                              (line  63)
+* ebdb-mua-display-all-records:          Interactive Commands.
+                                                              (line  18)
+* ebdb-mua-display-recipients:           Interactive Commands.
+                                                              (line  59)
+* ebdb-mua-display-sender:               Interactive Commands.
+                                                              (line  55)
+* ebdb-mua-edit-sender-notes:            Interactive Commands.
+                                                              (line  23)
+* ebdb-mua-in-ebdb-buffer:               Interactive Commands.
+                                                              (line  28)
+* ebdb-mua-snarf-article:                Interactive Commands.
+                                                              (line  36)
+* ebdb-mua-snarf-article <1>:            Snarfing.            (line  42)
+* ebdb-mua-update-records:               Interactive Commands.
+                                                              (line  12)
+* ebdb-mua-yank-cc:                      Interactive Commands.
+                                                              (line  46)
+* ebdb-next-field:                       The Basics of ebdb-mode.
+                                                              (line  17)
+* ebdb-next-record:                      The Basics of ebdb-mode.
+                                                              (line   9)
+* ebdb-omit-records:                     The Basics of ebdb-mode.
+                                                              (line  81)
+* ebdb-prev-field:                       The Basics of ebdb-mode.
+                                                              (line  21)
+* ebdb-prev-record:                      The Basics of ebdb-mode.
+                                                              (line  13)
+* ebdb-record-action:                    The Basics of ebdb-mode.
+                                                              (line  56)
+* ebdb-reformat-records:                 The Basics of ebdb-mode.
+                                                              (line  77)
+* ebdb-reload-database db:               The EBDB Database.   (line  73)
+* ebdb-rename-buffer:                    EBDB Buffers.        (line  24)
+* ebdb-save:                             The Basics of ebdb-mode.
+                                                              (line 115)
+* ebdb-search-invert:                    Searching.           (line  46)
+* ebdb-search-pop:                       Searching.           (line  53)
+* ebdb-snarf &optional string start end recs: Snarfing.       (line  15)
+* ebdb-toggle-records-format:            The Basics of ebdb-mode.
+                                                              (line  69)
 * Editing fields:                        Editing existing fields.
-                                                               (line  6)
-* Inserting new fields:                  Inserting new fields. (line  6)
-* Internationalization:                  Internationalization. (line  6)
-* Mail aliases:                          Mail Aliases.         (line  6)
-* Migrating from BBDB:                   Migration from BBDB.  (line  6)
-* Searching the EBDB:                    Searching.            (line  6)
-* Snarfing text:                         Snarfing.             (line  6)
+                                                              (line   6)
+* Inserting new fields:                  Inserting new fields.
+                                                              (line   6)
+* Internationalization:                  Internationalization.
+                                                              (line   6)
+* Mail aliases:                          Mail Aliases.        (line   6)
+* Migrating from BBDB:                   Migration from BBDB. (line   6)
+* quit-window:                           The Basics of ebdb-mode.
+                                                              (line 119)
+* revert-buffer:                         The Basics of ebdb-mode.
+                                                              (line 103)
+* Searching the EBDB:                    Searching.           (line   6)
+* Snarfing text:                         Snarfing.            (line   6)
 
 
 
 Tag Table:
 Node: Top806
-Node: Getting Started2070
-Node: Migration from BBDB2692
-Node: Record Migration2867
-Node: Variables and Options3404
-Node: The EBDB Database3890
-Node: Creating Records6950
-Node: Record classes7997
-Node: Record names8263
-Node: Record Fields8938
-Node: Inserting new fields9182
-Node: Editing existing fields9978
-Node: Deleting records and fields10578
-Node: Field types10974
-Node: MUA Interaction12793
-Node: Loading MUA Code13319
-Node: Display and Updating13946
-Node: Pop-up Buffers14715
-Node: Auto-Updating Records15580
-Node: Noticing and Automatic Rules17965
-Node: Interactive Commands19308
-Node: EBDB and MUA summary buffers21797
-Node: Sender name display22283
-Node: Summary buffer marks23571
-Node: *EBDB* Buffers24766
-Node: Searching26028
-Node: Changing Search Behavior27609
-Node: Marking28859
-Node: Exporting/Formatting29275
-Node: Snarfing30236
-Node: Internationalization32144
-Node: Diary Integration33569
-Node: Mail Aliases34433
-Node: vCard Support35142
-Node: Hacking EBDB35638
-Node: Field Classes37887
-Node: Init and Delete Methods40777
-Node: The Labeled Field Class42333
-Node: Actions43169
-Node: Custom Field Searching43834
-Node: Formatting in the EBDB Buffer45622
-Node: Index47621
+Node: Getting Started2151
+Node: Migration from BBDB2773
+Node: Record Migration2948
+Node: Variables and Options3485
+Node: The EBDB Database3971
+Node: Creating Records7127
+Node: Record classes8174
+Node: Record names8440
+Node: Record Fields9115
+Node: Inserting new fields9359
+Node: Editing existing fields10155
+Node: Deleting records and fields10755
+Node: Field types11151
+Node: MUA Interaction12970
+Node: Loading MUA Code13494
+Node: Display and Updating14207
+Node: Pop-up Buffers14976
+Node: Auto-Updating Records15841
+Node: Noticing and Automatic Rules18226
+Node: Interactive Commands19569
+Node: EBDB and MUA summary buffers22058
+Node: Sender name display22544
+Node: Summary buffer marks23832
+Node: EBDB Buffers25027
+Node: Searching26220
+Node: Changing Search Behavior27930
+Node: The Basics of ebdb-mode29180
+Node: Marking32544
+Node: Exporting/Formatting32972
+Node: Completion33931
+Node: Snarfing35072
+Node: Internationalization36976
+Node: Diary Integration38402
+Node: Mail Aliases39268
+Node: vCard Support39977
+Node: Org Integration40476
+Node: Citing Records42050
+Node: Hacking EBDB42809
+Node: Field Classes45059
+Node: Init and Delete Methods47949
+Node: The Labeled Field Class49505
+Node: Actions50341
+Node: Custom Field Searching51006
+Node: Formatting in the EBDB Buffer52794
+Node: Index54793
 
 End Tag Table
 
diff --git a/ebdb.org b/ebdb.org
index c918ce9..ed40cec 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -2,15 +2,13 @@
 #+TEXINFO_HEADER: @syncodeindex pg cp
 #+AUTHOR: Eric Abrahamsen <address@hidden>
 #+TITLE: EBDB Manual
-#+SUBTITLE: This manual is for version 0.2, updated 28 July, 2017
+#+SUBTITLE: This manual is for version 0.2, updated 29 July, 2017
 #+TEXINFO_DIR_CATEGORY: Emacs
 #+TEXINFO_DIR_TITLE: EBDB: (ebdb)
 #+TEXINFO_DIR_DESC: Contact management package
 #+TEXINFO_DEFFN: t
 #+OPTIONS: *:nil num:t toc:2 h:4 num:3
 #+MACRO: buf \ast{}$1\ast{}
-#+MACRO: version 0.2
-#+MACRO: updated last updated
 
 * Copying
 :PROPERTIES:
@@ -122,7 +120,8 @@ Records can be moved or copied from one database to 
another. It's also
 possible for a single record to live in more than one database, though
 this functionality is experimental. When a record is loaded from more
 than one database, the two copies are compared using the "timestamp"
-field, and the older copy is discarded.
+field, and the older copy is discarded.  In an {{{buf(EBDB)}}} buffer,
+the following keys can be used to manipulate databases and their records.
 
 - Key: d m, ebdb-move-record record to-db
 
@@ -193,6 +192,9 @@ these akas can be either simple or complex.  When adding 
fields to a
 record, the simple name class is labeled "nickname", and the complex
 class is labeled "alt name".
 * Record Fields
+:PROPERTIES:
+:ID:       4170bd36-64bf-44b4-87d0-29fbed968851
+:END:
 ** Inserting new fields
 #+CINDEX: Inserting new fields
 Pressing "i" (~ebdb-insert-field~) with point on a record will prompt
@@ -525,13 +527,10 @@ code:
 
   Format letter to use in the summary buffer format string to mark a
   record.  Defaults to "e".
-* {{{buf(EBDB)}}} Buffers
+* EBDB Buffers
 :PROPERTIES:
 :ID:       877ca77a-06d6-4fbf-87ec-614d03c37e30
 :END:
-EBDB buffers inherit from special-mode, and so the usual special-mode
-keybindings apply.
-
 EBDB can create several separate buffers for displaying contacts.
 Typically, each MUA creates its own buffer, with names like
 {{{buf(EBDB-Gnus)}}}, etc.  Users can also create their own buffers
@@ -586,6 +585,12 @@ Search commands that currently only work with the "/" 
prefix are:
 - "/ 1": Prompt for a single record, and display it
 - "/ d": Search duplicate records
 
+Searches can be inverted:
+
+- Key: !, ebdb-search-invert
+
+  Invert the results of the next search.
+
 Each user-created {{{buf(EBDB)}}} buffer keeps track of search history
 in that buffer.  To pop back to previous searches, use:
 
@@ -618,6 +623,126 @@ transform functions.  Character folding works by calling
 foldable characters within the string using regular expressions.  This
 process happens /after/ the transform functions have run, so there is
 a possibility for unexpected search behavior.
+** The Basics of ebdb-mode
+EBDB buffers inherit from special-mode, and so the usual special-mode
+keybindings apply.
+
+- Key: n, ebdb-next-record
+
+  Move point to the next record.
+
+- Key: p, ebdb-prev-record
+
+  Move point to the previous record.
+
+- Key: N, ebdb-next-field
+
+  Move point to the next field.
+
+- Key: P, ebdb-prev-field
+
+  Move point to the previous field.
+
+- Key: c, ebdb-create-record
+
+  Create a new person record in the primary database.
+
+- Key: C, ebdb-create-record-extended
+
+  Prompt for database and record class, then create a new record.
+
+- Key: i, ebdb-insert-field
+
+  Insert a new field into the record under point, or the marked records.
+
+- Key: e, ebdb-edit-field
+
+  Edit the field under point.
+
+- Key: E, ebdb-edit-field-customize
+
+  Use the extended customize interface to edit the field under point.
+
+- Key: ;, ebdb-edit-foo
+
+  Either insert/edit the record's notes field or, with a prefix arg,
+  prompt for an existing field and edit it.
+
+- Key: C-k, ebdb-delete-field-or-record
+
+  With point on a record field, offer to delete that field.  With
+  point on a record header, offer to delete the whole record.
+
+- Key: RET, ebdb-record-action
+
+  Run an "action" on the field under point. If multiple actions are
+  provided, you'll be prompted to choose one.  Not all fields provide
+  actions.  "RET" on a mail field will compose a message to that mail
+  address
+
+- Key: m, ebdb-mail
+
+  Begin composing a message to the record under point.  With a prefix
+  arg, prompt for the mail address to use; otherwise use the record's
+  primary address.
+
+- Key: t, ebdb-toggle-records-format
+
+  Toggle between a multi-line and one-line display.
+
+- Key: T, ebdb-display-records-completely
+
+  Display all of a record's fields.
+
+- Key: r, ebdb-reformat-records
+
+  Redisplay the record under point.
+
+- Key: o, ebdb-omit-records
+
+  Remove the record under point (or marked records) from the buffer
+  (does not delete the records).
+
+- Key: w f, ebdb-copy-fields-as-kill
+
+  Copy the string value of the field under point to the kill ring.
+
+- Key: w r, ebdb-copy-records-as-kill
+
+  Copy a string representation of the whole record under point to the
+  kill ring.
+
+- Key: w m, ebdb-copy-mail-as-kill
+
+  Copy a name-plus-mail string citation for the record under point to
+  the kill ring.  These strings look like "John Q Public
+  <address@hidden>".  By default this will use the record's primary
+  address; supply a prefix arg to be prompted for which address to
+  use.
+
+- Key: g, revert-buffer
+
+  Redisplay all visible records.
+
+- Key: ?, ebdb-help
+
+  Show a very brief help message.
+
+- Key: h, ebdb-info
+
+  Open this manual.
+
+- Key: s, ebdb-save
+
+  Save all databases.
+
+- Key: q, quit-window
+
+  Delete the {{{buf(EBDB)}}} window.
+
+[[id:692cde31-73be-4faf-b436-7eae8a5d02d1][Creating Records]] and 
[[id:4170bd36-64bf-44b4-87d0-29fbed968851][Record Fields]] for more on record 
creation and
+field manipulation.
+
 ** Marking
 :PROPERTIES:
 :ID:       73462a5d-2ec7-4a83-8b38-f5be8e62b376
@@ -667,7 +792,7 @@ can enable it for "TAB" in ~message-mode~ by calling
 
 Several native EBDB commands involve selecting a record, or multiple
 records.  At present, the completion interface for these commands is a
-bit random: several of the command simply use ~completing-read~
+bit random: several of the commands simply use ~completing-read~
 directly, which isn't right.  At some point, all EBDB commands that
 ask the user to select a record will become aware of the
 currently-loaded completion frameworks.
@@ -1063,10 +1188,10 @@ The leading underscores on parameters are there to keep 
the compiler
 quiet: the arguments are necessary for dispatch, but aren't actually
 used in the body of the method.
 
-# Local Variables:
-# sentence-end-double-space: t
-# End
 * Index
 :PROPERTIES:
 :INDEX:    cp
 :END:
+# Local Variables:
+# sentence-end-double-space: t
+# End
diff --git a/ebdb.texi b/ebdb.texi
index b3d9673..3c62352 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -31,7 +31,7 @@ modify this GNU manual.”
 @finalout
 @titlepage
 @title EBDB Manual
address@hidden This manual is for version 0.2, updated 28 July, 2017
address@hidden This manual is for version 0.2, updated 29 July, 2017
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -50,12 +50,15 @@ modify this GNU manual.”
 * Creating Records::
 * Record Fields::
 * MUA Interaction::
-* *EBDB* Buffers::
+* EBDB Buffers::
+* Completion::
 * Snarfing::
 * Internationalization::
 * Diary Integration::
 * Mail Aliases::
 * vCard Support::
+* Org Integration::
+* Citing Records::
 * Hacking EBDB::
 * Index::
 
@@ -108,9 +111,10 @@ EBDB and MUA summary buffers
 * Sender name display::
 * Summary buffer marks::
 
-*EBDB* Buffers
+EBDB Buffers
 
 * Searching::
+* The Basics of ebdb-mode::
 * Marking::
 * Exporting/Formatting::
 
@@ -123,6 +127,9 @@ Searching
 
 
 
+
+
+
 Hacking EBDB
 
 * Field Classes::
@@ -249,7 +256,8 @@ Records can be moved or copied from one database to 
another. It's also
 possible for a single record to live in more than one database, though
 this functionality is experimental. When a record is loaded from more
 than one database, the two copies are compared using the ``timestamp''
-field, and the older copy is discarded.
+field, and the older copy is discarded.  In an *EBDB* buffer,
+the following keys can be used to manipulate databases and their records.
 
 @table @asis
 @kindex d m
@@ -437,7 +445,6 @@ and receiving emails.
 @node Loading MUA Code
 @section Loading MUA Code
 
-:ORDERED:  t
 MUA code is activated simply by loading the relevant library.  Keep in
 mind that mail-reading clients and mail-sending clients are considered
 separate MUAs.  For instance, if you use the Gnus package for reading
@@ -449,7 +456,9 @@ mail, and Message for sending it, you'll want two require 
statements:
 @end lisp
 
 There are other packages that provide other MUA integration: these are
-likewise activated simply by requiring the relevant library.
+likewise activated simply by requiring the relevant library, named
+``ebdb-<MUA>''.  MUAs supported by EBDB include gnus, message, mh-e,
+mu4e, rmail, and VM.
 
 @node Display and Updating
 @section Display and Updating
@@ -770,11 +779,8 @@ Format letter to use in the summary buffer format string 
to mark a
 record.  Defaults to ``e''.
 @end defopt
 
address@hidden *EBDB* Buffers
address@hidden *EBDB* Buffers
-
-EBDB buffers inherit from special-mode, and so the usual special-mode
-keybindings apply.
address@hidden EBDB Buffers
address@hidden EBDB Buffers
 
 EBDB can create several separate buffers for displaying contacts.
 Typically, each MUA creates its own buffer, with names like
@@ -809,6 +815,7 @@ requests another pop up.
 
 @menu
 * Searching::
+* The Basics of ebdb-mode::
 * Marking::
 * Exporting/Formatting::
 @end menu
@@ -870,6 +877,16 @@ Search commands that currently only work with the ``/'' 
prefix are:
 ``/ d'': Search duplicate records
 @end itemize
 
+Searches can be inverted:
+
address@hidden @asis
address@hidden !
address@hidden ebdb-search-invert
address@hidden @kbd{!} @address@hidden@address@hidden(@code{ebdb-search-invert})
+
+Invert the results of the next search.
address@hidden table
+
 Each user-created *EBDB* buffer keeps track of search history
 in that buffer.  To pop back to previous searches, use:
 
@@ -916,6 +933,180 @@ foldable characters within the string using regular 
expressions.  This
 process happens /after/ the transform functions have run, so there is
 a possibility for unexpected search behavior.
 
address@hidden The Basics of ebdb-mode
address@hidden The Basics of ebdb-mode
+
+EBDB buffers inherit from special-mode, and so the usual special-mode
+keybindings apply.
+
address@hidden @asis
address@hidden n
address@hidden ebdb-next-record
address@hidden @kbd{n} @address@hidden@address@hidden(@code{ebdb-next-record})
+
+Move point to the next record.
+
address@hidden p
address@hidden ebdb-prev-record
address@hidden @kbd{p} @address@hidden@address@hidden(@code{ebdb-prev-record})
+
+Move point to the previous record.
+
address@hidden N
address@hidden ebdb-next-field
address@hidden @kbd{N} @address@hidden@address@hidden(@code{ebdb-next-field})
+
+Move point to the next field.
+
address@hidden P
address@hidden ebdb-prev-field
address@hidden @kbd{P} @address@hidden@address@hidden(@code{ebdb-prev-field})
+
+Move point to the previous field.
+
address@hidden c
address@hidden ebdb-create-record
address@hidden @kbd{c} @address@hidden@address@hidden(@code{ebdb-create-record})
+
+Create a new person record in the primary database.
+
address@hidden C
address@hidden ebdb-create-record-extended
address@hidden @kbd{C} 
@address@hidden@address@hidden(@code{ebdb-create-record-extended})
+
+Prompt for database and record class, then create a new record.
+
address@hidden i
address@hidden ebdb-insert-field
address@hidden @kbd{i} @address@hidden@address@hidden(@code{ebdb-insert-field})
+
+Insert a new field into the record under point, or the marked records.
+
address@hidden e
address@hidden ebdb-edit-field
address@hidden @kbd{e} @address@hidden@address@hidden(@code{ebdb-edit-field})
+
+Edit the field under point.
+
address@hidden E
address@hidden ebdb-edit-field-customize
address@hidden @kbd{E} 
@address@hidden@address@hidden(@code{ebdb-edit-field-customize})
+
+Use the extended customize interface to edit the field under point.
+
address@hidden ;
address@hidden ebdb-edit-foo
address@hidden @kbd{;} @address@hidden@address@hidden(@code{ebdb-edit-foo})
+
+Either insert/edit the record's notes field or, with a prefix arg,
+prompt for an existing field and edit it.
+
address@hidden C-k
address@hidden ebdb-delete-field-or-record
address@hidden @kbd{C-k} 
@address@hidden@address@hidden(@code{ebdb-delete-field-or-record})
+
+With point on a record field, offer to delete that field.  With
+point on a record header, offer to delete the whole record.
+
address@hidden RET
address@hidden ebdb-record-action
address@hidden @kbd{RET} 
@address@hidden@address@hidden(@code{ebdb-record-action})
+
+Run an ``action'' on the field under point. If multiple actions are
+provided, you'll be prompted to choose one.  Not all fields provide
+actions.  ``RET'' on a mail field will compose a message to that mail
+address
+
address@hidden m
address@hidden ebdb-mail
address@hidden @kbd{m} @address@hidden@address@hidden(@code{ebdb-mail})
+
+Begin composing a message to the record under point.  With a prefix
+arg, prompt for the mail address to use; otherwise use the record's
+primary address.
+
address@hidden t
address@hidden ebdb-toggle-records-format
address@hidden @kbd{t} 
@address@hidden@address@hidden(@code{ebdb-toggle-records-format})
+
+Toggle between a multi-line and one-line display.
+
address@hidden T
address@hidden ebdb-display-records-completely
address@hidden @kbd{T} 
@address@hidden@address@hidden(@code{ebdb-display-records-completely})
+
+Display all of a record's fields.
+
address@hidden r
address@hidden ebdb-reformat-records
address@hidden @kbd{r} 
@address@hidden@address@hidden(@code{ebdb-reformat-records})
+
+Redisplay the record under point.
+
address@hidden o
address@hidden ebdb-omit-records
address@hidden @kbd{o} @address@hidden@address@hidden(@code{ebdb-omit-records})
+
+Remove the record under point (or marked records) from the buffer
+(does not delete the records).
+
address@hidden w f
address@hidden ebdb-copy-fields-as-kill
address@hidden @kbd{w f} 
@address@hidden@address@hidden(@code{ebdb-copy-fields-as-kill})
+
+Copy the string value of the field under point to the kill ring.
+
address@hidden w r
address@hidden ebdb-copy-records-as-kill
address@hidden @kbd{w r} 
@address@hidden@address@hidden(@code{ebdb-copy-records-as-kill})
+
+Copy a string representation of the whole record under point to the
+kill ring.
+
address@hidden w m
address@hidden ebdb-copy-mail-as-kill
address@hidden @kbd{w m} 
@address@hidden@address@hidden(@code{ebdb-copy-mail-as-kill})
+
+Copy a name-plus-mail string citation for the record under point to
+the kill ring.  These strings look like ``John Q Public
+<john@@public.com>''.  By default this will use the record's primary
+address; supply a prefix arg to be prompted for which address to
+use.
+
address@hidden g
address@hidden revert-buffer
address@hidden @kbd{g} @address@hidden@address@hidden(@code{revert-buffer})
+
+Redisplay all visible records.
+
address@hidden ?
address@hidden ebdb-help
address@hidden @kbd{?} @address@hidden@address@hidden(@code{ebdb-help})
+
+Show a very brief help message.
+
address@hidden h
address@hidden ebdb-info
address@hidden @kbd{h} @address@hidden@address@hidden(@code{ebdb-info})
+
+Open this manual.
+
address@hidden s
address@hidden ebdb-save
address@hidden @kbd{s} @address@hidden@address@hidden(@code{ebdb-save})
+
+Save all databases.
+
address@hidden q
address@hidden quit-window
address@hidden @kbd{q} @address@hidden@address@hidden(@code{quit-window})
+
+Delete the *EBDB* window.
address@hidden table
+
address@hidden Records} and @ref{Record Fields} for more on record creation and
+field manipulation.
+
 @node Marking
 @section Marking
 
@@ -955,6 +1146,29 @@ different format.
 
 It's possible to write new formatters, documentation is forthcoming.
 
address@hidden Completion
address@hidden Completion
+
+There are many Emacs completion frameworks out there, and EBDB comes
+with support for helm, counsel, and company.  See the relevant
+libraries; they provide the commands @code{helm-ebdb}, @code{counsel-ebdb}, and
address@hidden, respectively.  Counsel and company are made to be
+hooked into Emacs' existing completion frameworks; the helm command
+must be called explicitly.
+
+Another library, @file{ebdb-complete}, uses an
+ephemeral pop-up *EBDB* buffer for record completion.  The
+command @code{ebdb-complete} provides an interactive entry point, or you
+can enable it for ``TAB'' in @code{message-mode} by calling
address@hidden
+
+Several native EBDB commands involve selecting a record, or multiple
+records.  At present, the completion interface for these commands is a
+bit random: several of the commands simply use @code{completing-read}
+directly, which isn't right.  At some point, all EBDB commands that
+ask the user to select a record will become aware of the
+currently-loaded completion frameworks.
+
 @node Snarfing
 @chapter Snarfing
 
@@ -1013,7 +1227,7 @@ headers of forwarded emails.
 EBDB comes with an internationalization framework that can provide
 country- and region-specific behavior for certain fields.  This
 functionality is initialized by loading the
address@hidden library.  This library does
address@hidden library.  This library does
 nothing by itself, it simply provides hooks for other country-specific
 libraries, which must be loaded separately.
 
@@ -1030,10 +1244,10 @@ welcome, though less enthusiastically, are requests for 
new libraries.
 Internationalization libraries do not modify the database in any way,
 and can be safely unloaded.  They simply alter the way EBDB reads,
 parses and displays field values, and can also store extra information
-(eg.@: for searching purposes) in a record's cache.  Loading this
-library can (depending on country libraries' behavior) increase
-database load times, though it should not significantly affect search
-or display performance.
+(eg.@:g for searching purposes) in a record's cache.
+Loading this library can (depending on country libraries' behavior)
+increase database load times, though it should not significantly
+affect search or display performance.
 
 @node Diary Integration
 @chapter Diary Integration
@@ -1086,6 +1300,52 @@ will be available when formatting EBDB records (see
 Support for importing vCard files is on the EBDB roadmap, as is,
 eventually, support for CardDav servers.
 
address@hidden Org Integration
address@hidden Org Integration
+
+EBDB has standard support for Org functionality: creating links to
+EBDB records works as expected with ``C-c l'', and following a link will
+open an *EBDB* buffer and display the linked record.
+
+Typically, links are created using the record's UUID field -- these
+links are fast and accurate -- but it's also possible to create links
+that initiate an EBDB search, and return multiple records.  EBDB links
+are of the format ``ebdb:<field type>/<search string>''.  The ``field
+type'' is typically the name of an EBDB field class (for instance,
+``ebdb-field-anniversary''), and opening a link of this sort results in
+a search of all records for which <search string> matches the string
+value of that particular field type.  For convenience, a few field
+type shorthands are recognized: in addition to ``uuid'', there is
+``mail'', ``phone'', ``address'', ``notes'' and ``tags'' (see below).  For
+instance, to create a link to all records with a 206 phone area code,
+use address@hidden/206}'', and to create a link to all records who work at
+Google, use address@hidden/google.com}''.
+
+The @file{ebdb-org} library also contains the
address@hidden field class, allowing users to tag their
+contacts with existing Org tags.  Completion is offered as expected.
+The field doesn't do much else, at present, but in the future there
+will be options for popping up an *EBDB* buffer alongside an
+Org agenda buffer, etc.
+
address@hidden Citing Records
address@hidden Citing Records
+
+Often one wants to share contact information into other channels: for
+instance, pasting a contact's name and mail address in a message
+you're sending to someone else.  EBDB refers to this as ``citing'', and
+provides a general interface to this through:
+
address@hidden ebdb-cite-records
address@hidden Command ebdb-cite-records
+
+This command is not bound in any mode, but can be called
+interactively.  It prompts for a record, then inserts a citation for
+the record into the current buffer.  In most text-mode buffers, the
+citation looks like ``Some Name <some@@email.com>''.  In Org buffers,
+it is a link with a ``mailto:'' prefix.
address@hidden deffn
+
 @node Hacking EBDB
 @chapter Hacking EBDB