[elpa] externals/ebdb 8776051 341/350: Changes to manual and README, reflecting EBDB's move to ELPA

[Eric Abrahamsen]

branch: externals/ebdb
commit 8776051a4857a0abccec773f74c5303b5288af78
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>

    Changes to manual and README, reflecting EBDB's move to ELPA
    
    * README.org: This was sort of acting as a manual, before we had one.
    * ebdb.org: Mention which packages are now separately loadable.
    * ebdb.info: etc
    * ebdb.texi: etc
---
 README.org |  86 +++++--------------------------------
 ebdb.info  | 142 ++++++++++++++++++++++++++++++++-----------------------------
 ebdb.org   |  52 +++++++++++++---------
 ebdb.texi  |  45 ++++++++++++--------
 4 files changed, 146 insertions(+), 179 deletions(-)

diff --git a/README.org b/README.org
index 32c984d..bdf6bfb 100644
--- a/README.org
+++ b/README.org
@@ -1,81 +1,17 @@
 
 * EBDB
-EBDB is a EIEIO port of the BBDB package for Emacs.
+EBDB is a contact management/addressbook package for Emacs.
 
-In plain English: it is a re-write of the Insidious Big Brother
-Database -- Emacs' principal contact management/addressbook program --
-using Emacs Lisp's (relatively new) object oriented libraries. The "E"
-is vaguely meant to signify "EIEIO".
-** Why Did You Do This?
-In part to gain practice in writing object-oriented Elisp. The EIEIO
-and generic-function libraries are based on Common Lisp's 
[[https://en.wikipedia.org/wiki/Common_Lisp_Object_System][CLOS system]],
-which I think is the 
[[http://www.gigamonkeys.com/book/object-reorientation-generic-functions.html][cat's
 pyjamas]].
+It's a re-write of the Insidious Big Brother Database 
([[https://savannah.nongnu.org/projects/bbdb/][BBDB]]) using
+Emacs Lisp's (relatively new) object oriented libraries. The "E" is
+vaguely meant to signify 
"[[https://ericabrahamsen.net/tech/2016/feb/bbdb-eieio-object-oriented-elisp.html][EIEIO]]";.
 
-Also, a database/record-keeping library is an excellent candidate for
-the object-oriented programming approach. By making databases, records
-and fields into classes (and by making sure that the library code
-itself is agnostic as possible about those classes), third-party
-developers can easily create new subclasses, and new behavior for
-existing classes. By loading external packages, users can augment the
-behavior of EBDB without having to use hooks or even customization
-options.
-** Okay, But What's Cool About It Right Now?
-EBDB as it stands provides a few enhancements over BBDB.
+It lives in both the ELPA repositories, and on Github at
+https://github.com/girzel/ebdb. It's best to 
[[https://www.emacswiki.org/emacs/InstallingPackages][install from ELPA]], but
+bug reports and pull requests on Github will also be attended to.
+Alternately, run ~report-emacs-bugs~, include "EBDB" somewhere in the
+subject line, and cc the maintainer.
 
-1. Multiple databases.
-2. Records are identified by UUID. Combined with multiple database
-   support, this means that single records can live in more than one
-   database. The loading routine checks for duplicate records and does
-   its best to automatically merge them. Loading, editing and saving
-   records into multiple databases should all work transparently.
-3. Organizations are top-level records. To be precise, both "people"
-   and "organizations" are subclasses of an abstract parent class
-   (other record classes are planned). A person record can have a
-   "role" at an organization, and that role can contain an arbitrary
-   amount of metadata.
-4. Records can have relations to other records.
-5. ebdb-i18n.el. This pluggable internationalization framework allows
-   developers to write country-specific libraries providing different
-   behavior for records and fields depending on nationality. It works
-   for all countries except Abkhazia and the Vatican (don't ask).
-6. High configurability. EBDB has many customization options (though
-   fewer than BBDB had), but users and developers who are familiar
-   with generic functions can use them to fundamentally alter the
-   behavior and appearance of EBDB with very little code, and fairly
-   low risk of breakage. Want to prepend the string "Hi my name is "
-   to all the record names in your EBDB buffer? That would be three
-   lines of code.
-7. A native vCard database class is on its way. A native CardDav
-   database class is following at a significant distance.
-** What Are the Drawbacks?
+More EBDB-related packages are available in ELPA.
 
-Buggy code! Potential data loss! This is still very much beta.
-
-Other than that, loading is a bit slow, and the database persistence
-file is significantly larger than it was in BBDB. It's likely that
-optimizations can be made to reduce load times, and the size of the
-persistence file.
-** I Still Want to Try This, Is There a Migration Scheme?
-Yes, EBDB will read and migrate from a BBDB v3 data file. Actually,
-EBDB preserves the BBDB's old migration routines, so theoretically you
-could go from a BBDB v2 file, through BBDB v3, straight to EBDB. I
-wouldn't recommend that, though. To migrate:
-
-1. Load the EBDB code while your BBDB customizations are still in
-   place -- specifically, the `bbdb-file' option should point to your
-   existing BBDB file.
-2. Back up that file.
-3. Set `ebdb-sources' to a non-existent file name, where you'd like to
-   keep the new database.
-4. Run `ebdb-load'. You'll be prompted to create the new database, and
-   migrate to the new format. It will take a surprisingly long time.
-5. If there were any migration failures, you'll get a "BBDB Migration"
-   buffer containing the records which couldn't be migrated. Migration
-   bug reports are very welcome.
-
-Once you're migrated, load MUA interaction by simply requiring the
-relevant libraries, ie ebdb-gnus or ebdb-message. There's no more
-`initialize' or `auto-update-init'.
-
-Many of the customization options have changed: there are fewer of
-them, for a start. Please see the manual for details.
+See the manual for usage details.
diff --git a/ebdb.info b/ebdb.info
index 6082813..6f934fa 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -145,7 +145,7 @@ 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 lastly open a *EBDB* buffer where you can start to make new records
+and finally open a *EBDB* buffer where you can start to make new records
 (see *note Creating Records::).
 
 * Menu:
@@ -174,7 +174,7 @@ customizations still in place, set ‘ebdb-sources’ to a 
non-existent file
 name, and then run ‘ebdb-load’ (or any of the other EBDB entry
 commands).  You’ll be prompted to create the new database, and upgrade
 from BBDB. If any records could not be upgraded, they will be displayed
-in an *EBDB Migration* buffer.
+in an *EBDB Migration* buffer.  Migration bug reports are very welcome.
 
 
 File: ebdb.info,  Node: Variables and Options,  Prev: Record Migration,  Up: 
Migration from BBDB
@@ -1098,16 +1098,17 @@ File: ebdb.info,  Node: Completion,  Next: Snarfing,  
Prev: EBDB Buffers,  Up: T
 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
+There are many Emacs completion frameworks out there, and libraries
+exist providing EBDB support for helm, counsel, and company—these
+libraries must be loaded from the package repositories.  These libraries
+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 built-in 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
@@ -1175,16 +1176,23 @@ 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-i18n’ library.  This
 library does nothing by itself, it simply provides hooks for other
-country-specific libraries, which must be loaded separately.
+country-specific libraries.
+
+   Country libraries that do not depend on other external libraries may
+live within the EBDB codebase, in which case they will be loaded
+automatically when ‘ebdb-i18n’ is loaded.  Libraries with extra
+dependencies may be found in the package repositories.
 
-   At present, EBDB comes with only one country-specific library,
-‘ebdb-chn’, for Chinese-related fields.  It parses and displays phone
-numbers and names correctly, and also allows users to search on Chinese
-names using pinyin.  It requires the ‘pyim’ package, available on MELPA.
+   EBDB currently comes with only one country library, ‘ebdb-i18n-chn’,
+for Chinese-related fields.  It parses and displays phone numbers and
+names correctly, and also allows users to search on Chinese names using
+pinyin.  It can be installed from ELPA, and requires the ‘pyim’ package,
+available on MELPA.
 
    The present dearth of libraries is a result of the author scratching
-his own itch.  Contributions of new libraries are very welcome.  Also
-welcome, though less enthusiastically, are requests for new libraries.
+his own itch.  Contributions of new libraries are very welcome (see
+*note Writing Internationalization Libraries::).  Also 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,
@@ -1896,54 +1904,54 @@ Index
 Tag Table:
 Node: Top806
 Node: Getting Started2320
-Node: Migration from BBDB2942
-Node: Record Migration3117
-Node: Variables and Options3654
-Node: The EBDB Database4140
-Node: Creating Records7296
-Node: Record classes8343
-Node: Record names8676
-Node: Record Fields9351
-Node: Inserting New Fields9595
-Node: Editing Existing Fields10391
-Node: Deleting Records and Fields10991
-Node: Field Types11387
-Node: Role Fields13232
-Node: MUA Interaction14923
-Node: Loading MUA Code15447
-Node: Display and Updating16160
-Node: Pop-up Buffers16929
-Node: Auto-Updating Records17794
-Node: Noticing and Automatic Rules20179
-Node: Interactive Commands21522
-Node: EBDB and MUA summary buffers24011
-Node: Sender name display24497
-Node: Summary buffer marks25785
-Node: EBDB Buffers26980
-Node: Searching28173
-Node: Changing Search Behavior29883
-Node: The Basics of ebdb-mode31133
-Node: Marking34497
-Node: Exporting/Formatting34925
-Node: Completion35884
-Node: Snarfing37025
-Node: Internationalization39004
-Node: Diary Integration40429
-Node: Mail Aliases41295
-Node: vCard Support42004
-Node: Org Integration42503
-Node: Citing Records44077
-Node: Hacking EBDB44836
-Node: Field Classes47166
-Node: Init and Delete Methods50103
-Node: The Labeled Field Class51659
-Node: Actions52495
-Node: Custom Field Searching53160
-Node: Formatting in the EBDB Buffer54948
-Node: Writing Internationalization Libraries56947
-Node: Writing Integration For New MUAs61298
-Node: Article snarfing64724
-Node: Index65446
+Node: Migration from BBDB2943
+Node: Record Migration3118
+Node: Variables and Options3696
+Node: The EBDB Database4182
+Node: Creating Records7338
+Node: Record classes8385
+Node: Record names8718
+Node: Record Fields9393
+Node: Inserting New Fields9637
+Node: Editing Existing Fields10433
+Node: Deleting Records and Fields11033
+Node: Field Types11429
+Node: Role Fields13274
+Node: MUA Interaction14965
+Node: Loading MUA Code15489
+Node: Display and Updating16202
+Node: Pop-up Buffers16971
+Node: Auto-Updating Records17836
+Node: Noticing and Automatic Rules20221
+Node: Interactive Commands21564
+Node: EBDB and MUA summary buffers24053
+Node: Sender name display24539
+Node: Summary buffer marks25827
+Node: EBDB Buffers27022
+Node: Searching28215
+Node: Changing Search Behavior29925
+Node: The Basics of ebdb-mode31175
+Node: Marking34539
+Node: Exporting/Formatting34967
+Node: Completion35926
+Node: Snarfing37137
+Node: Internationalization39116
+Node: Diary Integration40848
+Node: Mail Aliases41714
+Node: vCard Support42423
+Node: Org Integration42922
+Node: Citing Records44496
+Node: Hacking EBDB45255
+Node: Field Classes47585
+Node: Init and Delete Methods50522
+Node: The Labeled Field Class52078
+Node: Actions52914
+Node: Custom Field Searching53579
+Node: Formatting in the EBDB Buffer55367
+Node: Writing Internationalization Libraries57366
+Node: Writing Integration For New MUAs61717
+Node: Article snarfing65143
+Node: Index65865
 
 End Tag Table
 
diff --git a/ebdb.org b/ebdb.org
index ca54831..fe1dce2 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -35,7 +35,7 @@ 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 lastly open a {{{buf(EBDB)}}} buffer where you can start to
+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]]).
 ** Migration from BBDB
 :PROPERTIES:
@@ -51,7 +51,8 @@ customizations still in place, set ~ebdb-sources~ to a 
non-existent
 file name, and then run ~ebdb-load~ (or any of the other EBDB entry
 commands).  You'll be prompted to create the new database, and upgrade
 from BBDB.  If any records could not be upgraded, they will be
-displayed in an {{{buf(EBDB Migration)}}} buffer.
+displayed in an {{{buf(EBDB Migration)}}} buffer.  Migration bug
+reports are very welcome.
 *** Variables and Options
 :PROPERTIES:
 
@@ -814,18 +815,19 @@ imperfect: not all fields can be exported correctly.  
VCard version
 
 It's possible to write new formatters, documentation is forthcoming.
 * 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
+There are many Emacs completion frameworks out there, and libraries
+exist providing EBDB support for helm, counsel, and company---these
+libraries must be loaded from the package repositories.  These
+libraries 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, @@texinfo:@file{@@ebdb-complete@@texinfo:}@@, uses an
-ephemeral pop-up {{{buf(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~.
+Another built-in library,
+@@texinfo:@file{@@ebdb-complete@@texinfo:}@@, uses an ephemeral pop-up
+{{{buf(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
@@ -883,17 +885,26 @@ country- and region-specific behavior for certain fields. 
 This
 functionality is initialized by loading the
 @@texinfo:@file{@@ebdb-i18n@@texinfo:}@@ library.  This library does
 nothing by itself, it simply provides hooks for other country-specific
-libraries, which must be loaded separately.
-
-At present, EBDB comes with only one country-specific library,
-@@texinfo:@file{@@ebdb-chn@@texinfo:}@@, for Chinese-related fields.
-It parses and displays phone numbers and names correctly, and also
-allows users to search on Chinese names using pinyin.  It requires the
-~pyim~ package, available on MELPA.
+libraries.
+
+Country libraries that do not depend on other external libraries may
+live within the EBDB codebase, in which case they will be loaded
+automatically when ~ebdb-i18n~ is loaded.  Libraries with external
+dependencies may be installed from the package repositories.  Because
+function autoloading doesn't work with generic methods, you'll need to
+require the libraries in addition to simply installing them.
+
+EBDB currently comes with only one country library,
+@@texinfo:@file{@@ebdb-i18n-chn@@texinfo:}@@, for Chinese-related
+fields.  It parses and displays phone numbers and names correctly, and
+also allows users to search on Chinese names using pinyin.  It can be
+installed from ELPA, and requires the ~pyim~ package, available on
+MELPA.
 
 The present dearth of libraries is a result of the author scratching
-his own itch.  Contributions of new libraries are very welcome.  Also
-welcome, though less enthusiastically, are requests for new libraries.
+his own itch.  Contributions of new libraries are very welcome (see
+[[id:5446ff9c-78ca-4e12-89cc-6d4ccd9b2b83][Writing Internationalization 
Libraries]]).  Also 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,
@@ -1227,6 +1238,9 @@ quiet: the arguments are necessary for dispatch, but 
aren't actually
 used in the body of the method.
 
 ** Writing Internationalization Libraries
+:PROPERTIES:
+:ID:       5446ff9c-78ca-4e12-89cc-6d4ccd9b2b83
+:END:
 Writing new internationalization libraries involves using generic
 functions. [[info:elisp#Generic%20Functions][Generic Functions]].  It will 
also require a bit of
 familiarity with EBDB's internals.
diff --git a/ebdb.texi b/ebdb.texi
index fe7da2d..ef6a57d 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -165,7 +165,7 @@ management software, it is enough to call the top-level 
@code{ebdb}
 command.  This will create a new database at the location specified by
 @code{ebdb-sources} (see @ref{The EBDB Database}), prompt you for a search
 string, fail to find anything (because you don't have any records
-yet), and lastly open a *EBDB* buffer where you can start to
+yet), and finally open a *EBDB* buffer where you can start to
 make new records (see @ref{Creating Records}).
 
 @menu
@@ -190,7 +190,8 @@ customizations still in place, set @code{ebdb-sources} to a 
non-existent
 file name, and then run @code{ebdb-load} (or any of the other EBDB entry
 commands).  You'll be prompted to create the new database, and upgrade
 from BBDB.  If any records could not be upgraded, they will be
-displayed in an *EBDB Migration* buffer.
+displayed in an *EBDB Migration* buffer.  Migration bug
+reports are very welcome.
 
 @node Variables and Options
 @subsection Variables and Options
@@ -1201,18 +1202,19 @@ It's possible to write new formatters, documentation is 
forthcoming.
 @node Completion
 @chapter 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
+There are many Emacs completion frameworks out there, and libraries
+exist providing EBDB support for helm, counsel, and company---these
+libraries must be loaded from the package repositories.  These
+libraries provide the commands @code{helm-ebdb}, @code{counsel-ebdb}, and
 @code{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, @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
+Another built-in library,
address@hidden, uses an ephemeral pop-up
+*EBDB* buffer for record completion.  The command
address@hidden provides an interactive entry point, or you can enable
+it for ``TAB'' in @code{message-mode} by calling @code{ebdb-complete-enable}.
 
 Several native EBDB commands involve selecting a record, or multiple
 records.  At present, the completion interface for these commands is a
@@ -1282,17 +1284,24 @@ country- and region-specific behavior for certain 
fields.  This
 functionality is initialized by loading the
 @file{ebdb-i18n} library.  This library does
 nothing by itself, it simply provides hooks for other country-specific
-libraries, which must be loaded separately.
+libraries.
 
-At present, EBDB comes with only one country-specific library,
address@hidden, for Chinese-related fields.
-It parses and displays phone numbers and names correctly, and also
-allows users to search on Chinese names using pinyin.  It requires the
address@hidden package, available on MELPA.
+Country libraries that do not depend on other external libraries may
+live within the EBDB codebase, in which case they will be loaded
+automatically when @code{ebdb-i18n} is loaded.  Libraries with extra
+dependencies may be found in the package repositories.
+
+EBDB currently comes with only one country library,
address@hidden, for Chinese-related
+fields.  It parses and displays phone numbers and names correctly, and
+also allows users to search on Chinese names using pinyin.  It can be
+installed from ELPA, and requires the @code{pyim} package, available on
+MELPA.
 
 The present dearth of libraries is a result of the author scratching
-his own itch.  Contributions of new libraries are very welcome.  Also
-welcome, though less enthusiastically, are requests for new libraries.
+his own itch.  Contributions of new libraries are very welcome (see
address@hidden Internationalization Libraries}).  Also 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,