[elpa] externals/ebdb 0fe0957 289/350: Large pile of manual, docstring, and comment edits

[Eric Abrahamsen]

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

    Large pile of manual, docstring, and comment edits
    
    * ebdb-mua.el: Some new information, but mostly typo and reformatting
      edits.
    * ebdb.org: Mostly new information regarding MUA changes.  Also, start
      reformatting for the use of ox-texinfo-plus, though a future commit
      will focus on that.
---
 ebdb-mua.el |  98 ++++++++++++++-------------
 ebdb.org    | 221 ++++++++++++++++++++++++++++++++++++++----------------------
 2 files changed, 191 insertions(+), 128 deletions(-)

diff --git a/ebdb-mua.el b/ebdb-mua.el
index e8d8583..cb105c8 100644
--- a/ebdb-mua.el
+++ b/ebdb-mua.el
@@ -25,7 +25,7 @@
 ;; For simplicity's sake, all these packages will be referred to as
 ;; MUAs.
 
-;; Essentially, this library can make three things happen:
+;; Essentially, this library can make four things happen:
 
 ;; 1. Return EBDB records matched by criteria provided by the MUA, and
 ;; optionally display those records in a pop-up buffer.
@@ -37,8 +37,11 @@
 ;; updates may be automatic or interactive, depending on the user's
 ;; configuration.
 
-;; 3. Provide keybindings for editing or otherwise manipulating the
-;; records afterwards.
+;; 3. Provide hooks for allowing records to be updated automatically
+;; by user-specified functions.
+
+;; 4. Provide keybindings for editing or otherwise manipulating the
+;; records interactively.
 
 ;;; Code:
 
@@ -111,18 +114,24 @@ The strings HEADER belong to CLASS."
 
 (defcustom ebdb-message-all-addresses nil
   "If t `ebdb-update-records' returns all mail addresses of a message.
-Otherwise this function returns only the first mail address of each message."
+
+Otherwise this function returns only the first mail address of
+each message."
+
   :group 'ebdb-mua
   :type 'boolean)
 
 (defcustom ebdb-message-try-all-headers nil
   "If t try all message headers to extract an email address from a message.
-Several EBDB commands extract either the sender or the recipients' email
-addresses from a message according to `ebdb-message-headers'.  If EBDB does not
-find any email address in this subset of message headers (for example, because
-an email address is excluded because of `ebdb-user-mail-address-re')
-but `ebdb-message-try-all-headers' is t, then these commands will also consider
-the email addresses in the remaining headers."
+
+Several EBDB commands extract either the sender or the
+recipients' email addresses from a message according to
+`ebdb-message-headers'.  If EBDB does not find any email address
+in this subset of message headers (for example, because an email
+address is excluded because of `ebdb-user-mail-address-re') but
+`ebdb-message-try-all-headers' is t, then these commands will
+also consider the email addresses in the remaining headers."
+
   :group 'ebdb-mua
   :type 'boolean)
 
@@ -149,7 +158,7 @@ EBDB records are only created for messages sent by people 
at Maximegalon U.,
 or people posting about time travel.
 If t accept all messages.  If nil, accept all messages.
 
-See also `ebdb-ignore-message-alist', which has the opposite effect."
+See also `ebdb-ignore-header-alist', which has the opposite effect."
   :group 'ebdb-mua
   :type '(repeat (cons
                   (choice (symbol :tag "Sender" sender)
@@ -173,7 +182,7 @@ no EBDB records are created for messages from any mailer 
daemon,
 or messages sent to or CCed to either of two mailing lists.
 If t ignore all messages.  If nil do not ignore any messages.
 
-See also `ebdb-accept-message-alist', which has the opposite effect."
+See also `ebdb-accept-header-alist', which has the opposite effect."
   :group 'ebdb-mua
   :type '(repeat (cons
                   (choice (symbol :tag "Sender" sender)
@@ -323,16 +332,17 @@ See also `ebdb-add-mails' and 
`ebdb-canonicalize-mail-function'."
   :type 'boolean)
 
 (defcustom ebdb-notice-mail-hook nil
-  "Hook run each time a mail address of a record is \"noticed\" in a message.
-This means that the mail address in a message belongs to an existing EBDB 
record
-or to a record EBDB has created for the mail address.
+  "Hook run when a record's mail address is \"noticed\" in a message.
+
+This means that the mail address in a message belongs to an
+existing EBDB record or to a record EBDB has created for the mail
+address.
 
 Run with one argument, the record.  It is up to the hook function
-to determine which MUA is used and to act appropriately.
-Hook functions can use the variable `ebdb-update-records-address'
-to determine the header and class of the mail address according
-to `ebdb-message-headers'.  See `ebdb-auto-notes' for how to annotate records
-using `ebdb-update-records-address' and the headers of a mail message.
+to determine which MUA is used and to act appropriately.  Hook
+functions can use the variable `ebdb-update-records-address' to
+determine the header and class of the mail address according to
+`ebdb-message-headers'.
 
 If a message contains multiple mail addresses belonging to one EBDB record,
 this hook is run for each mail address.  Use `ebdb-notice-record-hook'
@@ -475,8 +485,7 @@ Currently no other MUAs support this EBDB feature."
   "Return non-nil if REGEXP matches value of HEADER."
   (let ((val (ebdb-message-header header))
         (case-fold-search t)) ; RW: Is this what we want?
-    (when (and val (string-match regexp val))
-      (throw 'done t))))
+    (and val (string-match regexp val))))
 
 (defsubst ebdb-mua-check-header (header-type address-parts &optional invert)
   (let ((rest (if invert
@@ -579,7 +588,8 @@ are discarded as appropriate."
 
 ;;;###autoload
 (defun ebdb-update-records (address-list &optional update-p sort)
-  "Return the list of EBDB records matching ADDRESS-LIST.
+  "Find and possibly edit the records matching ADDRESS-LIST.
+
 ADDRESS-LIST is a list of mail addresses.  (It can be extracted from
 a mail message using `ebdb-get-address-components'.)
 UPDATE-P may take the following values:
@@ -604,7 +614,7 @@ Usually this function is called by the wrapper 
`ebdb-mua-auto-update'."
   (when (eq t update-p)
     (setq update-p 'create))
 
-  (let ( ;; `ebdb-update-records-p' and `ebdb-offer-to-create' are used here
+  (let (;; `ebdb-update-records-p' and `ebdb-offer-to-create' are used here
         ;; as internal variables for communication with `ebdb-query-create'.
         ;; This does not affect the value of the global user variable
         ;; `ebdb-mua-auto-update-p'.
@@ -924,8 +934,7 @@ Return the records matching ADDRESS or nil."
                         (message "noticed naked address \"%s\"" mail))))))
 
         (run-hook-with-args 'ebdb-notice-mail-hook record)
-       ;; (ebdb-notice record) ; I think this is already happening in
-       ;; `ebdb-update-records'.
+
         (push record new-records)))
 
     (nreverse new-records)))
@@ -970,9 +979,11 @@ apply, however."
 ;;;###autoload
 (defun ebdb-mua-display-records (&optional header-class all)
   "Display the EBDB record(s) for the addresses in this message.
-This looks into the headers of a message according to HEADER-CLASS.
-Then for the mail addresses found the corresponding EBDB records are displayed.
-Records are not created or updated.
+
+This looks into the headers of a message according to
+HEADER-CLASS.  Then for the mail addresses found the
+corresponding EBDB records are displayed.  Records are not
+created or updated.
 
 HEADER-CLASS is defined in `ebdb-message-headers'.  If it is nil,
 use all classes in `ebdb-message-headers'.  If ALL is non-nil,
@@ -988,10 +999,6 @@ bind `ebdb-message-all-addresses' to ALL."
     (if records (ebdb-display-records records fmt nil nil (ebdb-popup-window)))
     records))
 
-;; The following commands are some frontends for `ebdb-mua-display-records',
-;; which is always doing the real work.  In your init file, you can further
-;; modify or adapt these simple commands to your liking.
-
 ;;;###autoload
 (defun ebdb-mua-display-sender ()
   "Display the EBDB record(s) for the sender of this message."
@@ -1084,26 +1091,21 @@ where it was in the MUA, rather than quitting the EBDB 
buffer."
 ;;;###autoload
 (defun ebdb-mua-auto-update (&optional header-class update-p)
   "Update EBDB automatically based on incoming and outgoing messages.
-This looks into the headers of a message according to HEADER-CLASS.
-Then for the mail addresses found the corresponding EBDB records are updated.
-UPDATE-P determines whether only existing EBDB records are taken
-or whether also new records are created for these mail addresses.
-Return matching records.
+
+This looks into the headers of a message according to
+HEADER-CLASS.  Then for the mail addresses found the
+corresponding EBDB records are updated.  UPDATE-P determines
+whether only existing EBDB records are taken or whether also new
+records are created for these mail addresses.  Return matching
+records.
 
 HEADER-CLASS is defined in `ebdb-message-headers'.  If it is nil,
 use all classes in `ebdb-message-headers'.  UPDATE-P may take the
-same values as `ebdb-mua-auto-update-p'.  If UPDATE-P is nil,
-use `ebdb-mua-auto-update-p' (which see).
+same values as `ebdb-mua-auto-update-p'.  If UPDATE-P is nil, use
+`ebdb-mua-auto-update-p' (which see).
 
 If `ebdb-mua-pop-up' is non-nil, EBDB pops up the *EBDB* buffer
-along with the MUA window(s), displaying the matching records
-using `ebdb-pop-up-layout'.
-If this is nil, EBDB is updated silently.
-
-This function is intended for noninteractive use via appropriate MUA hooks.
-Call `ebdb-mua-auto-update-init' in your init file to put this function
-into the respective MUA hooks.
-See `ebdb-mua-display-records' and friends for interactive commands."
+along with the MUA window(s), displaying the matching records."
   (let* ((ebdb-silent-internal t)
         records)
     (setq records (ebdb-update-records
diff --git a/ebdb.org b/ebdb.org
index 882749f..97276d1 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -138,8 +138,8 @@ You can also tell EBDB which record represents you:
 Currently this option's only use is to serve as a source for
 `ebdb-user-mail-address-re'.
 ** Record classes
-EBDB comes with two record classes, representing individuals and
-organizations.
+EBDB comes with two record classes, representing individuals
+(`ebdb-record-person') and organizations (`ebdb-record-organization').
 ** Record names
 EBDB comes with two classes for name fields: "simple" and "complex".
 Simple names are just a single string, complex names are split out
@@ -151,9 +151,10 @@ When adding fields to a record, the simple name class is 
labeled
 "nickname", and the complex class is labeled "alt name".
 * Record Fields
 ** Inserting new fields
-Press "i" (`ebdb-insert-field') with point on a record will prompt for
-a field type, then field values, and add the field to the record.  See
-[[id:cb2190f4-f2e6-4082-9671-24e11e5cc0c6][Field types]] for more information 
about the various kinds of fields.
+Pressing "i" (`ebdb-insert-field') with point on a record will prompt
+for a field type, then field values, and add the field to the record.
+See [[id:cb2190f4-f2e6-4082-9671-24e11e5cc0c6][Field types]] for more 
information about the various kinds of
+fields.
 
 When entering field data, optional data can be skipped by entering a
 blank string, or by pressing "C-g".  The first "C-g" will cancel the
@@ -207,48 +208,72 @@ of labels (for instance, anniversary fields may be 
labeled "birthday",
 Loading secondary libraries may make more field types available.
 * MUA Interaction
 One of EBDB's most important features is the ability to create, update
-and display records based on messages received in your mail user
-agent.
-** Loading MUA code
+and display records based on messages received or sent in your mail
+user agent(s).  In theory, EBDB can be integrated with any software
+package, but it's most common to use it in conjunction with sending
+and receiving emails.
+** Loading MUA Code
 MUA code is activated simply by loading the relevant library.  Keep in
-mind that "MUA" here means both a mail-reading client, and a
-mail-sending client.  For instance, if you use the Gnus package for
-reading mail, and Message for sending it, you'll want two require
-statements:
+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:
 
 #+BEGIN_SRC elisp
 (require 'ebdb-gnus)
 (require 'ebdb-message)
 #+END_SRC
 
-There are other packages that provide other functionality: these are
+There are other packages that provide other MUA integration: these are
 likewise activated simply by requiring the relevant library.
-** Display and updating
-When you open a message in your MUA, EBDB can react in many different
-ways: displaying records for the sender and recipients of the message;
-creating new records for unfamiliar mail addresses; and updating
-existing records with new information.  EBDB also provides several
-interactive commands for editing the records associated with the
-selected message.
+** Display and Updating
+
+When a message is opened in an MUA, EBDB can do certain things with
+the records referenced in that message. It can:
+
+- Pop up a buffer displaying the records.
+- Create new records, or alter existing records, based on information
+   provided by the MUA.
+- Run automatic rules to edit the records.
+- Provide keybindings to manually edit the records.
+
+Each of these functionalities is optional, and can be customized
+independently of the others.
+*** Pop-up Buffers
+Each MUA associated with EBDB creates its own pop-up buffer, with a
+name like \ast{}EBDB-Gnus\ast{} or \ast{}EBDB-Rmail\ast{}.  MUAs will
+re-use their own buffers, and will not interfere with buffers the user
+has created using the `ebdb' command, or by cloning or renaming
+existing buffers.
 
-The first and most important option governing this behavior is:
+- Variable: ebdb-mua-pop-up
+  If nil, MUAs will not automatically pop up buffers.  It is still
+  possible to manually create the buffer using interactive commands
+  (see [[id:38166454-6750-48e9-a5e5-313ff9264c6d][Interactive Commands in 
MUAs]]).
+
+At present, there are *no* user customization options controlling the
+size and layout of MUA pop-up buffers: each MUA creates the pop-up
+according to hard-coded rules.  This will likely change in the future:
+please complain to the author.
+*** Auto-Updating Records
+EBDB can automatically update the name and mail addresses of records
+based on information in an MUA message. The first and most important
+option governing this behavior is:
 
 - Variable: ebdb-mua-auto-update-p
   This option determines how EBDB acts upon mail addresses found in
   incoming messages.  If nil, nothing will happen.  Other options
-  include the symbols 'search (only find existing records), 'update
-  (only find existing records, and update their name and mail fields
-  as necessary), 'query (find existing records, and query about the
-  creation of new records), and 'create (automatically create new
-  records).  A value of t is considered equivalent to 'create.  The
-  option can also be set to a function which returns one of the above
-  symbols.
+  include the symbols 'update (only find existing records, and update
+  their name and mail fields as necessary), 'query (find existing
+  records, and query about the editing and creation of new records),
+  and 'create (automatically create new records).  A value of t is
+  considered equivalent to 'create.  The option can also be set to a
+  function which returns one of the above symbols.
 
 This option only governs what EBDB does automatically, each time a
-message is displayed.  It's also possible to manually display,
-update and edit records using the commands in 
[[id:38166454-6750-48e9-a5e5-313ff9264c6d][Interactive Commands in
-MUAs]].  When updating records either automatically or interactively, a
-few more options come into play:
+message is displayed.  The same process can be run interactively using
+the commands in [[id:38166454-6750-48e9-a5e5-313ff9264c6d][Interactive 
Commands in MUAs]].  When updating records
+either automatically or interactively, a few more options come into
+play:
 
 - Variable: ebdb-add-name
   Whether to automatically change record names.  See docstring for
@@ -260,8 +285,8 @@ few more options come into play:
   How to handle apparently new mail addresses.  See docstring for
   details.
 
-There are also options governing whether EBDB considers mail addresses
-or not:
+There are also options governing whether EBDB will consider a mail
+address or not:
 
 - Variable: ebdb-accept-header-alist
   An alist governing which addresses in which headers will be
@@ -276,22 +301,73 @@ or not:
   the symbol 'self, in which case the value will be constructed from
   the record pointed to by the option `ebdb-record-self'.
 
-*** Pop-up buffers
-Each MUA associated with EBDB will create its own pop-up buffer, with
-a name like \ast{}EBDB-Gnus\ast{} or \ast{}EBDB-Rmail\ast{}.  MUAs
-will re-use their own buffers, and not interfere with buffers the user
-has created using `ebdb', or by cloning or renaming existing buffers.
-
-- Variable: ebdb-mua-pop-up
-  If nil, MUAs will not create pop-up buffers.  It may still be
-  possible to manually create the buffer (and/or edit EBDB records)
-  using interactive commands (see 
[[id:38166454-6750-48e9-a5e5-313ff9264c6d][Interactive Commands in MUAs]]).
+*** Noticing and Automatic Rules
+
+In addition to updating records' name and mail fields, it's possible
+to run other arbitrary edits on records when they are referenced in a
+message.  This process is called "noticing". Two hooks are run as a
+part of noticing:
+
+- User Option: ebdb-notice-record-hook
+  This hook is run once per record noticed, with two arguments: the
+  record, and one of the symbols 'sender and 'recipient, indicating
+  where in the message headers the record was found.
+- User Option: ebdb-notice-mail-hook
+  This hook is run once per mail message noticed: if multiple
+  addresses belong to a single record, it will be called once per
+  address.  The hook is run with one argument: the record.
+
+When a record is noticed, it will also call the method
+`ebdb-notice-field' on all of its fields.  Using this method requires
+a bit of familiarity with [[info:elisp#Generic%20Functions][info:elisp#Generic 
Functions]]; suffice it to
+say that the first argument is the field instance being noticed, the
+second argument is one of the symbols 'sender or 'recipient, and the
+third argument is the record being noticed.
+
+*** Interactive Commands
+:PROPERTIES:
+:ID:       38166454-6750-48e9-a5e5-313ff9264c6d
+:END:
+Some interactive commands are also provided for operating on the
+relevant EBDB records.  In message-reading MUAs, EBDB creates its own
+keymap, and binds it to the key ";".  The following commands assume
+this binding, and only specify the further binding.  Ie, you'll have
+to press ";:" to call `ebdb-mua-display-records'.
+
+- Key: :, ebdb-mua-update-records
+  If the option `ebdb-mua-auto-update-p' is nil, this command can be
+  used to do the same thing, and will behave as if that option were
+  set to 'query.
+- Key: ;, ebdb-mua-display-all-records
+  If the option `ebdb-mua-pop-up' is nil, this command can be used to
+  do the same thing.
+- Key: ', ebdb-mua-edit-sender-notes
+  This command allows you to edit the notes field of the message
+  sender.
+- Key: ", ebdb-mua-in-ebdb-buffer
+  This command moves point to the relevant EBDB pop-up buffer (popping
+  the buffer up first, if necessary).  You can then issue commands in
+  the EBDB buffer as usual, with the exception that "q" will move
+  point back to the previously-selected window, rather than quitting
+  the EBDB buffer.
+- Key: s, ebdb-mua-snarf-article
+  This command scans the body text of the current message, and
+  attempts to snarf new record information from it.  Email addresses
+  and names in the body text will be handled, as will information in
+  the headers of forwarded mail, and information in the signature will
+  be associated with the sender.  The user is always prompted before
+  edits are made.  This functionality is highly unreliable, and
+  probably won't work as advertised.
+
+Commands that are not bound to any keys by default:
+
+- Command: ebdb-mua-display-sender
+  Only display the sender.
+- Command: ebdb-mua-display-recipients
+  Only display the recipients.
+- Command: ebdb-mua-display-all-recipients
+  Only display recipients, using all mail addresses from the message.
 
-At present, there are *no* user customization options controlling the
-size and location of MUA pop-up buffers: each MUA creates the pop-up
-according to hard-coded rules.  This will likely change in the future:
-please complain to the author.
-*** Annotation and Noticing
 ** EBDB and MUA summary buffers
 EBDB can affect the way message senders are displayed in your MUA's
 summary buffer.  It can do this in two ways: 1) by changing the way
@@ -301,15 +377,18 @@ one-character mark next to the contact's name.
 EBDB can "unify" the name displayed for a sender that exists in the
 database.  In general, an MUA will display the name part of the From:
 header in the mailbox summary buffer.  EBDB can replace that display
-name with information from the database.
-
-- Variable: ebdb-message-clean-name-function
-- Variable: ebdb-message-mail-as-name
-- Variable: edb-mua-summary-unification-list
-
-- Variable: ebdb-mua-summary-unify-format-letter
-  Format letter to use for the EBDB-unified sender name in an MUA
-  summary buffer.  Defaults to "E".
+name with information from the database.  This only works for Gnus and
+VM, which allow for overriding how message senders are displayed.  The
+format letter (see below) should be added to
+`gnus-summary-line-format' for Gnus (which see), and
+`vm-summary-format' for VM (ditto).
+
+- User Option: ebdb-message-clean-name-function
+- User Option: ebdb-message-mail-as-name
+- User Option: edb-mua-summary-unification-list
+- User Option: ebdb-mua-summary-unify-format-letter
+  Format letter to use for the EBDB-unified sender name in an Gnus or
+  VM summary buffer.  Defaults to "E".
 
 *** Summary buffer marks
 EBDB can display a one-character mark next to the name of senders that
@@ -317,7 +396,7 @@ are in the database -- at present this is only possible in 
the Gnus
 and VM MUAs.  This can be done in one of three ways.  From most
 general to most specific:
 
-- Variable: ebdb-mua-summary-mark
+- User Option: ebdb-mua-summary-mark
   Set to a single-character string to use for all senders in the EBDB
   database.  Set to nil to not mark senders at all.
 - Function: ebdb-mua-make-summary-mark record
@@ -331,13 +410,9 @@ Marks are displayed in MUA summary buffers by customizing 
the format
 string provided by Gnus or VM, and adding the EBDB-specific format
 code:
 
-- Variable: ebdb-mua-summary-mark-format-letter
+- User Option: ebdb-mua-summary-mark-format-letter
   Format letter to use in the summary buffer format string to mark a
   record.  Defaults to "e".
-*** Interactive Commands in MUAs
-:PROPERTIES:
-:ID:       38166454-6750-48e9-a5e5-313ff9264c6d
-:END:
 * EBDB Buffers
 :PROPERTIES:
 :ID:       877ca77a-06d6-4fbf-87ec-614d03c37e30
@@ -485,20 +560,6 @@ information for that day.
 
 Support for this feature is rudimentary.  More customization options
 are forthcoming.
-* Migration from BBDB
-** Record Migration
-It's possible to migrate records from a BBDB file.  With your BBDB
-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 \ast{}EBDB Migration\ast{} buffer.
-** Variables and Options
-Many of the old BBDB customization options have been changed or
-removed entirely in EBDB.  It's probably best to put your BBDB
-customizations aside, and set new EBDB options as you come across
-them.  The most important options are detailed in this manual, you can
-also customize the "EBDB" group to see what's available.
 * Hacking EBDB
 :PROPERTIES:
 :ID:       a58993a8-0631-459f-8bd6-7155bb6df605
@@ -597,14 +658,14 @@ provide default values for the new object.
                             "Gender: " '(female male other unknown none)
                             nil t
                             (when obj (symbol-name (slot-value obj 
:gender)))))))
-       (setq slots (plist-put :gender gender))))
+       (setq slots (plist-put slots :gender gender))))
     (cl-call-next-method class slots obj))
 
   (cl-defmethod ebdb-parse ((class (subclass ebdb-field-gender))
                            str &optional slots)
     (when (and (null (plist-get slots :gender))
               (member str '("female" "male" "other" "unknown" "none")))
-      (setq slots (plist-put slots :gender str)))
+      (setq slots (plist-put slots :gender (intern str)))
     (cl-call-next-method class str slots))
 
   (cl-defmethod ebdb-string ((field ebdb-field-gender))