[elpa] externals/ebdb b9ac670 333/350: Add new manual section about writing MUA integration

[Eric Abrahamsen]

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

    Add new manual section about writing MUA integration
    
    * ebdb.org (Writing Integration For New MUAs): New section.
    * ebdb.texi: etc
    * ebdb.info: etc
---
 ebdb.info | 201 +++++++++++++++++++++++++++++++++++++++++++++++---------------
 ebdb.org  |  84 ++++++++++++++++++++++++++
 ebdb.texi | 105 ++++++++++++++++++++++++++++++++
 3 files changed, 342 insertions(+), 48 deletions(-)

diff --git a/ebdb.info b/ebdb.info
index 5553b90..79eb290 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -118,6 +118,7 @@ Hacking EBDB
 
 * Field Classes::
 * Writing Internationalization Libraries::
+* Writing Integration For New MUAs::
 
 Field Classes
 
@@ -127,6 +128,12 @@ Field Classes
 * Custom Field Searching::
 * Formatting in the EBDB Buffer::
 
+
+
+Writing Integration For New MUAs
+
+* Article snarfing::
+
 
 File: ebdb.info,  Node: Getting Started,  Next: The EBDB Database,  Prev: Top, 
 Up: Top
 
@@ -1357,6 +1364,7 @@ existing objects.  This may be addressed in the future.
 
 * Field Classes::
 * Writing Internationalization Libraries::
+* Writing Integration For New MUAs::
 
 
 File: ebdb.info,  Node: Field Classes,  Next: Writing Internationalization 
Libraries,  Up: Hacking EBDB
@@ -1582,7 +1590,7 @@ quiet: the arguments are necessary for dispatch, but 
aren’t actually
 used in the body of the method.
 
 
-File: ebdb.info,  Node: Writing Internationalization Libraries,  Prev: Field 
Classes,  Up: Hacking EBDB
+File: ebdb.info,  Node: Writing Internationalization Libraries,  Next: Writing 
Integration For New MUAs,  Prev: Field Classes,  Up: Hacking EBDB
 
 15.2 Writing Internationalization Libraries
 ===========================================
@@ -1680,6 +1688,101 @@ use them.  The symbol specs for country codes and 
script names can also
 be specialized on with the ‘eql’ specializer.
 
 
+File: ebdb.info,  Node: Writing Integration For New MUAs,  Prev: Writing 
Internationalization Libraries,  Up: Hacking EBDB
+
+15.3 Writing Integration For New MUAs
+=====================================
+
+Theoretically EBDB can be incorporated into any Emacs package, but it’s
+most commonly used in conjunction with a mail user agent.  It comes with
+support for a few MUAs out of the box, but integration with a new one
+can be written fairly easily.
+
+   The first step of integration involves hooking the function
+‘ebdb-mua-auto-update’ somewhere into the MUA’s operation.  For most
+MUAs, the appropriate place is when a message or article is opened for
+viewing by the user.  This allows EBDB to act on the information found
+in that message.
+
+   The second step requires providing new versions of a handful of
+generic functions.  All MUA-specific generic functions specialize on the
+current major-mode, using the ‘&context’ specializer.  See below for
+examples.
+
+   When ‘ebdb-mua-auto-update’ runs, it scans the headers of the current
+article/message for name/mail data, and uses that data to locate,
+create, edit, and display records.  It does this by calling the generic
+function ‘ebdb-message-header’ with the string header name; it is the
+responsibility of the MUA to implement this function, and return the
+contents of the appropriate header.  For instance, in Gnus:
+
+     (cl-defmethod ebdb-message-header ((header string)
+                                  &context (major-mode gnus-summary-mode))
+       "Return value of HEADER for current Gnus message."
+       (set-buffer gnus-article-buffer)
+       (gnus-fetch-original-field header))
+
+
+   The first argument is the string header, and the second is the
+specializer on the current major-mode.  Possible header values include
+those found in ‘ebdb-message-headers’.  Note that if you expect this
+function to be called in more than one major-mode, you’ll have to
+provide multiple versions of the function.  The &context specializer
+uses ‘derived-mode-p’ behind the scenes, though, so if all the modes
+derive from a single parent mode (and the behavior should be the same in
+all derived modes) it is enough to specialize on the parent mode.
+
+   Some MUAs might need to do a bit of work to ensure that the article
+in question is opened and set up properly:
+
+ -- Function: ebdb-mua-prepare-article
+     Called with no argument but the mode specializer, this function
+     should do whatever is necessary to prepare the article.
+
+   Providing *EBDB* buffer pop-up support involves implementing two
+separate functions:
+
+ -- Function: ebdb-make-buffer-name
+     Called with no arguments but the mode specializer, this function
+     should return the string name of the *EBDB* buffer to be associated
+     with this MUA. Usually the function body will look like: ‘(format
+     "*%s-<mua>" ebdb-buffer-name)’.
+
+ -- Function: ebdb-popup-window
+     Called with no arguments but the mode specializer, this function
+     should return a list of two elements: the window to be split to
+     make room for the *EBDB* buffer window, and a float value between 0
+     and 1 indicating the size of the new *EBDB* buffer window, as a
+     percentage of the window being split.
+
+   In addition, it might be nice to bind the ‘ebdb-mua-keymap’ in the
+MUA’s mode-map.  This map provides bindings for some commonly-used EBDB
+functions.
+
+* Menu:
+
+* Article snarfing::
+
+
+File: ebdb.info,  Node: Article snarfing,  Up: Writing Integration For New MUAs
+
+15.3.1 Article snarfing
+-----------------------
+
+EBDB can scan articles or messages for likely field information, and
+prompt the user to add the fields to new or existing records—this is
+done by the user with the interactive command ‘ebdb-mua-snarf-article’.
+In order to work, the MUA must be able to provide that function with the
+text of the message body, and the text of the message signature (if
+any).  This is done with two generic functions:
+
+ -- Function: ebdb-mua-article-body
+     Return the text of the article body, or nil.
+
+ -- Function: ebdb-mua-article-signature
+     Return the text of the article signature, or nil.
+
+
 File: ebdb.info,  Node: Index,  Prev: Hacking EBDB,  Up: Top
 
 Index
@@ -1792,53 +1895,55 @@ Index
 
 Tag Table:
 Node: Top806
-Node: Getting Started2225
-Node: Migration from BBDB2847
-Node: Record Migration3022
-Node: Variables and Options3559
-Node: The EBDB Database4045
-Node: Creating Records7201
-Node: Record classes8248
-Node: Record names8581
-Node: Record Fields9256
-Node: Inserting New Fields9500
-Node: Editing Existing Fields10296
-Node: Deleting Records and Fields10896
-Node: Field Types11292
-Node: Role Fields13137
-Node: MUA Interaction14828
-Node: Loading MUA Code15352
-Node: Display and Updating16065
-Node: Pop-up Buffers16834
-Node: Auto-Updating Records17699
-Node: Noticing and Automatic Rules20084
-Node: Interactive Commands21427
-Node: EBDB and MUA summary buffers23916
-Node: Sender name display24402
-Node: Summary buffer marks25690
-Node: EBDB Buffers26885
-Node: Searching28078
-Node: Changing Search Behavior29788
-Node: The Basics of ebdb-mode31038
-Node: Marking34402
-Node: Exporting/Formatting34830
-Node: Completion35789
-Node: Snarfing36930
-Node: Internationalization38909
-Node: Diary Integration40334
-Node: Mail Aliases41200
-Node: vCard Support41909
-Node: Org Integration42408
-Node: Citing Records43982
-Node: Hacking EBDB44741
-Node: Field Classes47034
-Node: Init and Delete Methods49971
-Node: The Labeled Field Class51527
-Node: Actions52363
-Node: Custom Field Searching53028
-Node: Formatting in the EBDB Buffer54816
-Node: Writing Internationalization Libraries56815
-Node: Index61119
+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 MUAs61292
+Node: Article snarfing64710
+Node: Index65432
 
 End Tag Table
 
diff --git a/ebdb.org b/ebdb.org
index 62ae649..e6d7fb9 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -1319,6 +1319,90 @@ using ~eql~.
 See the signatures of the other internationalized methods for how to
 use them.  The symbol specs for country codes and script names can
 also be specialized on with the ~eql~ specializer.
+** Writing Integration For New MUAs
+Theoretically EBDB can be incorporated into any Emacs package, but
+it's most commonly used in conjunction with a mail user agent.  It
+comes with support for a few MUAs out of the box, but integration with
+a new one can be written fairly easily.
+
+The first step of integration involves hooking the function
+~ebdb-mua-auto-update~ somewhere into the MUA's operation.  For most
+MUAs, the appropriate place is when a message or article is opened for
+viewing by the user.  This allows EBDB to act on the information found
+in that message.
+
+The second step requires providing new versions of a handful of
+generic functions.  All MUA-specific generic functions specialize on
+the current major-mode, using the ~&context~ specializer.  See below
+for examples.
+
+When ~ebdb-mua-auto-update~ runs, it scans the headers of the current
+article/message for name/mail data, and uses that data to locate,
+create, edit, and display records.  It does this by calling the
+generic function ~ebdb-message-header~ with the string header name; it
+is the responsibility of the MUA to implement this function, and
+return the contents of the appropriate header.  For instance, in Gnus:
+
+#+BEGIN_SRC emacs-lisp
+  (cl-defmethod ebdb-message-header ((header string)
+                                     &context (major-mode gnus-summary-mode))
+    "Return value of HEADER for current Gnus message."
+    (set-buffer gnus-article-buffer)
+    (gnus-fetch-original-field header))
+
+#+END_SRC
+
+The first argument is the string header, and the second is the
+specializer on the current major-mode.  Possible header values include
+those found in ~ebdb-message-headers~. Note that if you expect this
+function to be called in more than one major-mode, you'll have to
+provide multiple versions of the function.  The &context specializer
+uses ~derived-mode-p~ behind the scenes, though, so if all the modes
+derive from a single parent mode (and the behavior should be the same
+in all derived modes) it is enough to specialize on the parent mode.
+
+Some MUAs might need to do a bit of work to ensure that the article in
+question is opened and set up properly:
+
+- Function: ebdb-mua-prepare-article
+  Called with no argument but the mode specializer, this function
+  should do whatever is necessary to prepare the article.
+
+Providing {{{buf(EBDB)}}} buffer pop-up support involves implementing
+two separate functions:
+
+- Function: ebdb-make-buffer-name
+  Called with no arguments but the mode specializer, this function
+  should return the string name of the {{{buf(EBDB)}}} buffer to be
+  associated with this MUA.  Usually the function body will look like:
+  ~(format "*%s-<mua>" ebdb-buffer-name)~.
+
+- Function: ebdb-popup-window
+  Called with no arguments but the mode specializer, this function
+  should return a list of two elements: the window to be split to make
+  room for the {{{buf(EBDB)}}} buffer window, and a float value
+  between 0 and 1 indicating the size of the new {{{buf(EBDB)}}}
+  buffer window, as a percentage of the window being split.
+
+In addition, it might be nice to bind the ~ebdb-mua-keymap~ in the
+MUA's mode-map.  This map provides bindings for some commonly-used
+EBDB functions.
+
+*** Article snarfing
+
+EBDB can scan articles or messages for likely field information, and
+prompt the user to add the fields to new or existing records---this is
+done by the user with the interactive command
+~ebdb-mua-snarf-article~.  In order to work, the MUA must be able to
+provide that function with the text of the message body, and the text
+of the message signature (if any).  This is done with two generic
+functions:
+
+- Function: ebdb-mua-article-body
+  Return the text of the article body, or nil.
+
+- Function: ebdb-mua-article-signature
+  Return the text of the article signature, or nil.
 * Index
 :PROPERTIES:
 :INDEX:    cp
diff --git a/ebdb.texi b/ebdb.texi
index 5ea0bd6..3affac7 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -139,6 +139,7 @@ Hacking EBDB
 
 * Field Classes::
 * Writing Internationalization Libraries::
+* Writing Integration For New MUAs::
 
 Field Classes
 
@@ -147,6 +148,12 @@ Field Classes
 * Actions::
 * Custom Field Searching::
 * Formatting in the EBDB Buffer::
+
+
+
+Writing Integration For New MUAs
+
+* Article snarfing::
 @end detailmenu
 @end menu
 
@@ -1461,6 +1468,7 @@ existing objects.  This may be addressed in the future.
 @menu
 * Field Classes::
 * Writing Internationalization Libraries::
+* Writing Integration For New MUAs::
 @end menu
 
 @node Field Classes
@@ -1799,6 +1807,103 @@ See the signatures of the other internationalized 
methods for how to
 use them.  The symbol specs for country codes and script names can
 also be specialized on with the @code{eql} specializer.
 
address@hidden Writing Integration For New MUAs
address@hidden Writing Integration For New MUAs
+
+Theoretically EBDB can be incorporated into any Emacs package, but
+it's most commonly used in conjunction with a mail user agent.  It
+comes with support for a few MUAs out of the box, but integration with
+a new one can be written fairly easily.
+
+The first step of integration involves hooking the function
address@hidden somewhere into the MUA's operation.  For most
+MUAs, the appropriate place is when a message or article is opened for
+viewing by the user.  This allows EBDB to act on the information found
+in that message.
+
+The second step requires providing new versions of a handful of
+generic functions.  All MUA-specific generic functions specialize on
+the current major-mode, using the @code{&context} specializer.  See below
+for examples.
+
+When @code{ebdb-mua-auto-update} runs, it scans the headers of the current
+article/message for name/mail data, and uses that data to locate,
+create, edit, and display records.  It does this by calling the
+generic function @code{ebdb-message-header} with the string header name; it
+is the responsibility of the MUA to implement this function, and
+return the contents of the appropriate header.  For instance, in Gnus:
+
address@hidden
+(cl-defmethod ebdb-message-header ((header string)
+                                  &context (major-mode gnus-summary-mode))
+  "Return value of HEADER for current Gnus message."
+  (set-buffer gnus-article-buffer)
+  (gnus-fetch-original-field header))
+
address@hidden lisp
+
+The first argument is the string header, and the second is the
+specializer on the current major-mode.  Possible header values include
+those found in @code{ebdb-message-headers}. Note that if you expect this
+function to be called in more than one major-mode, you'll have to
+provide multiple versions of the function.  The &context specializer
+uses @code{derived-mode-p} behind the scenes, though, so if all the modes
+derive from a single parent mode (and the behavior should be the same
+in all derived modes) it is enough to specialize on the parent mode.
+
+Some MUAs might need to do a bit of work to ensure that the article in
+question is opened and set up properly:
+
address@hidden ebdb-mua-prepare-article
+Called with no argument but the mode specializer, this function
+should do whatever is necessary to prepare the article.
address@hidden defun
+
+Providing *EBDB* buffer pop-up support involves implementing
+two separate functions:
+
address@hidden ebdb-make-buffer-name
+Called with no arguments but the mode specializer, this function
+should return the string name of the *EBDB* buffer to be
+associated with this MUA.  Usually the function body will look like:
address@hidden(format "*%s-<mua>" ebdb-buffer-name)}.
address@hidden defun
+
address@hidden ebdb-popup-window
+Called with no arguments but the mode specializer, this function
+should return a list of two elements: the window to be split to make
+room for the *EBDB* buffer window, and a float value
+between 0 and 1 indicating the size of the new *EBDB*
+buffer window, as a percentage of the window being split.
address@hidden defun
+
+In addition, it might be nice to bind the @code{ebdb-mua-keymap} in the
+MUA's mode-map.  This map provides bindings for some commonly-used
+EBDB functions.
+
address@hidden
+* Article snarfing::
address@hidden menu
+
address@hidden Article snarfing
address@hidden Article snarfing
+
+EBDB can scan articles or messages for likely field information, and
+prompt the user to add the fields to new or existing records---this is
+done by the user with the interactive command
address@hidden  In order to work, the MUA must be able to
+provide that function with the text of the message body, and the text
+of the message signature (if any).  This is done with two generic
+functions:
+
address@hidden ebdb-mua-article-body
+Return the text of the article body, or nil.
address@hidden defun
+
address@hidden ebdb-mua-article-signature
+Return the text of the article signature, or nil.
address@hidden defun
+
 @node Index
 @unnumbered Index