[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/ebdb b9ac670 333/350: Add new manual section about writ
From: |
Eric Abrahamsen |
Subject: |
[elpa] externals/ebdb b9ac670 333/350: Add new manual section about writing MUA integration |
Date: |
Mon, 14 Aug 2017 11:47:05 -0400 (EDT) |
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
- [elpa] externals/ebdb acaf3d0 350/350: Move the mail field sorting thing to a :before method, (continued)
- [elpa] externals/ebdb acaf3d0 350/350: Move the mail field sorting thing to a :before method, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 2c05d6e 348/350: Wrong slot names when reading addresses, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb a4e9f16 324/350: Also snarf URL fields, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 761dc23 346/350: Fix bug in searching by database, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 6c13763 335/350: Don't require ebdb-chn from ebdb-i18n, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb f64c791 347/350: Add internationalized version of ebdb-string for addresses, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 2d74de4 345/350: Use autoload cookies on defclass statements, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb a035748 318/350: Mention role fields in the manual, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 5e25f5b 344/350: Remove Brian Edmonds' code until copyright resolved, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb e555044 294/350: Expand manual, and edit for use of ox-texinfo-plus, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb b9ac670 333/350: Add new manual section about writing MUA integration,
Eric Abrahamsen <=
- [elpa] externals/ebdb 5fbc902 343/350: New option ebdb-i18n-countries-pref-scripts, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 84b348e 311/350: Basic finished version of manual, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 534d3b7 298/350: Start tracking manual texi and info files, Eric Abrahamsen, 2017/08/14