[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/ebdb 8868ceb 26/33: Remove texinfo manual dependency on
|
From: |
Eric Abrahamsen |
|
Subject: |
[elpa] externals/ebdb 8868ceb 26/33: Remove texinfo manual dependency on texinfo+ |
|
Date: |
Sun, 3 Sep 2017 17:02:24 -0400 (EDT) |
branch: externals/ebdb
commit 8868cebf5f88a2ed3afdc45738cf8ed21003c736
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>
Remove texinfo manual dependency on texinfo+
* ebdb.org: The Org-format manual now only uses native ox-texinfo
processing. Also made quite a few refinements to the manual.
* ebdb.info: etc
* ebdb.texi: etc
---
ebdb.info | 1221 ++++++++++++++++++++++++++++++----------------------
ebdb.org | 1435 ++++++++++++++++++++++++++++++++++++-------------------------
ebdb.texi | 1177 +++++++++++++++++++++++++-------------------------
3 files changed, 2165 insertions(+), 1668 deletions(-)
diff --git a/ebdb.info b/ebdb.info
index e2fbf13..6e9248a 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -73,7 +73,9 @@ Record Fields
Field Types
-* Role Fields::
+* Role fields::
+* Tag field::
+* Mail folder field::
MUA Interaction
@@ -124,6 +126,7 @@ Field Classes
* Init and Delete Methods::
* The Labeled Field Class::
+* The Singleton Field Class::
* Actions::
* Custom Field Searching::
* Formatting in the EBDB Buffer::
@@ -200,7 +203,6 @@ its contacts in the same file as the database itself,
though other
database classes may store contacts elsewhere.
-- User Option: ebdb-sources
-
User option specifying one or more databases to load. It can be a
single element, or a list of elements. Each element can be a
filename, from which a database is loaded, or it can be an instance
@@ -209,29 +211,24 @@ database classes may store contacts elsewhere.
Databases have a few user-facing settings:
- -- User Option: read-only
-
- If t, records can only be read from the database, not edited or
- deleted.
-
- -- User Option: auto-save
+ -- Instance Variable of Database: ‘boolean’ read-only
+ If non-nil, records can only be read from the database, not edited
+ or deleted.
- Set to nil to prevent auto-saving of the database’s records.
+ -- Instance Variable of Database: ‘boolean’ auto-save
+ If non-nil, the database’s records will not be autosaved.
- -- User Option: buffer-char
+ -- Instance Variable of Database: ‘character’ buffer-char
+ A single character that will be displayed next to records in the
+ *EBDB* buffer, indicating which database they belong to.
- Set to a single character that will be displayed next to records in
- the *EBDB* buffer, indicating which database they belong to.
-
- -- User Option: disabled
-
- When t, the database will essentially be ignored – no records will
- be read from it. Setting this to t will only take effect on next
- restart; to disable a database immediately, use
+ -- Instance Variable of Database: ‘boolean’ disabled
+ When non-nil , the database will essentially be ignored—no records
+ will be read from it. Setting this to t will only take effect on
+ next restart; to disable a database immediately, use
‘ebdb-disable-database’ below.
- -- User Option: record-class
-
+ -- Instance Variable of Database: ‘symbol’ record-class
The default record class to use when creating new records in this
database. The default is ‘ebdb-default-record-class’.
@@ -239,40 +236,38 @@ database classes may store contacts elsewhere.
file, it’s safer to use the customization interface to do so from the
*EBDB* buffer.
-‘d e’ (‘ebdb-customize-database db’)
-
- Use the customize interface to edit the definition of DB.
+‘d e’
+ Use the customize interface to edit the definition of a database
+ (‘ebdb-customize-database’).
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. In an *EBDB*
-buffer, the following keys can be used to manipulate databases and their
-records.
-
-‘d m’ (‘ebdb-move-record record to-db’)
-
- Move RECORD from its existing database to TO-DB.
+more than one database, the two copies are compared using the 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 c’ (‘ebdb-copy-record record to-db’)
+‘d m’
+ Move a record from its current database to another
+ (‘ebdb-move-record’).
- Copy RECORD into TO-DB, leaving it in its existing database(s).
+‘d c’
+ Copy a record into a new database, leaving it in its existing
+ database(s) (‘ebdb-copy-record’).
Other database-related commands:
-‘d r’ (‘ebdb-reload-database db’)
-
+‘d r’
Reload all records from a database. This also redisplays any of
- those records that were visible in *EBDB* buffers.
-
-‘d d’ (‘ebdb-disable-database db’)
+ those records that were visible in *EBDB* buffers
+ (‘ebdb-reload-database’).
- This command disables a database, unloading all of its records and
- essentially ignoring it from now on. The disabled state persists
- between restarts. To re-enable a database, edit it using
- ‘ebdb-customize-database’, set ’disabled to nil, and then reload it
- with ‘ebdb-reload-database’.
+‘d d’
+ This command (‘ebdb-disable-database’) disables a database,
+ unloading all of its records and essentially ignoring it from now
+ on. The disabled state persists between restarts. To re-enable a
+ database, edit it using ‘ebdb-customize-database’, set ‘disabled’
+ to nil, and then reload it with ‘ebdb-reload-database’.
File: ebdb.info, Node: Creating Records, Next: Record Fields, Prev: The
EBDB Database, Up: Top
@@ -280,24 +275,24 @@ File: ebdb.info, Node: Creating Records, Next: Record
Fields, Prev: The EBDB
3 Creating Records
******************
-Create a record using “c” (‘ebdb-create’) in the *EBDB* buffer. With no
-prefix arg, this command will create an instance of the default record
-class, in the database at the head of ‘ebdb-sources’.
+Create a record using ‘c’ (‘ebdb-create-record’) in the *EBDB* buffer.
+This command will create an instance of the default record class, in the
+database at the head of ‘ebdb-sources’.
-- User Option: ebdb-default-record-class
-
The default record class to use when creating new records.
+ Defaults to ‘ebdb-record-person’.
- Alternately create a record using “C” (‘ebdb-create-extended’), which
-will prompt for a record class to use, as well as a database to store
-the record in, if there is more than one.
+ Alternately create a record using ‘C’
+(‘ebdb-create-record-extended’), which will prompt for a record class to
+use, as well as a database to store the record in, if there is more than
+one.
You can also tell EBDB which record represents you:
-- User Option: ebdb-record-self
-
The value of this option should be the UUID of your own record.
- You can find this by pressing “T” (to show all fields) on your
+ You can find this by pressing ‘T’ (to show all fields) on your
record.
Currently this option’s only use is to serve as a source for
@@ -316,7 +311,8 @@ File: ebdb.info, Node: Record classes, Next: Record
names, Up: Creating Recor
EBDB comes with two record classes, representing individuals
(‘ebdb-record-person’) and organizations (‘ebdb-record-organization’).
-Records can have “roles” at organizations *note Role Fields::.
+Records can have “roles” at organizations, *note Role Fields: Role
+fields.
File: ebdb.info, Node: Record names, Prev: Record classes, Up: Creating
Records
@@ -354,16 +350,16 @@ File: ebdb.info, Node: Inserting New Fields, Next:
Editing Existing Fields, U
4.1 Inserting New Fields
========================
-Pressing “i” (‘ebdb-insert-field’) with point on a record will prompt
+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 below 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
-current data prompt; the second “C-g” will cancel the creation of the
+blank string, or by pressing ‘C-g’. The first ‘C-g’ will cancel the
+current data prompt; the second ‘C-g’ will cancel the creation of the
field altogether. For instance, when creating address fields, EBDB will
allow you to create an arbitrary number of street lines. When you’ve
-added enough, either enter a blank string, or hit “C-g”.
+added enough, either enter a blank string, or hit ‘C-g’.
File: ebdb.info, Node: Editing Existing Fields, Next: Deleting Records and
Fields, Prev: Inserting New Fields, Up: Record Fields
@@ -371,10 +367,10 @@ File: ebdb.info, Node: Editing Existing Fields, Next:
Deleting Records and Fie
4.2 Editing Existing Fields
===========================
-Pressing “e” (‘ebdb-edit-field’) with point on a field will allow you to
+Pressing ‘e’ (‘ebdb-edit-field’) with point on a field will allow you to
edit an existing field, with the previous values as defaults.
- Alternately, press “E” (‘ebdb-edit-field-customize’) to edit the
+ Alternately, press ‘E’ (‘ebdb-edit-field-customize’) to edit the
field’s values using the Customize interface. Some fields have slots
that can only be edited this way; other fields have slots that cannot be
edited at all once the field is created.
@@ -385,8 +381,8 @@ File: ebdb.info, Node: Deleting Records and Fields, Next:
Field Types, Prev:
4.3 Deleting Records and Fields
===============================
-Pressing “C-k” on a field will ask you for confirmation, then delete the
-field. Pressing “C-k” while point is on or before a record’s main name
+Pressing ‘C-k’ on a field will ask you for confirmation, then delete the
+field. Pressing ‘C-k’ while point is on or before a record’s main name
will instead prompt to delete the whole record.
@@ -398,7 +394,7 @@ File: ebdb.info, Node: Field Types, Prev: Deleting
Records and Fields, Up: Re
Fields can be classed in a few different categories. Some are
“plumbing” fields, that are present for all records, but not generally
visible or user-editable: these include the creation date, timestamp,
-and UUID. You can view these fields by hitting “T” on the record. Other
+and UUID. You can view these fields by hitting ‘T’ on the record. Other
fields are “built-in”: basic fields that get special treatment. These
include the name, mail, phone, address, and notes fields. EBDB comes
with default classes for these fields: if you would like to use
@@ -407,33 +403,41 @@ existing ones) and use those instead. See *note Hacking
EBDB:: for more
information.
Besides the “plumbing” and “built-in” fields, all other fields are
-“user” fields, and belong to one of two types: ‘ebdb-field-user’ and
-‘ebdb-field-user-simple’. The former is an abstract class, used to
-build fields with more complicated structures. The latter represents a
-simple field with a string label and a string value, and no special
+referred to as “user” fields. These can hold any kind of information
+you want to associate with a record. Some user fields are simple string
+keys and string values; others have more complicated data structures and
behavior.
- When adding fields to a record, EBDB offers up all the known labels
-of the simple user field class as possible choices. Typing in an
-unknown string will define a new label, which will be offered as a
-choice in the future.
+ When adding a field to a record, you’ll be prompted for a field type.
+The list will include the built-in fields, more complicated field types,
+and also all the simple string keys you’ve defined so far. If you enter
+a string key that EBDB hasn’t seen before, it will prompt for
+confirmation, then define that key for future use.
+
+ EBDB comes with more complicated classes including “anniversary”,
+“url”, “id”, “relation”, “role” and more. Many of these fields have
+their own list of labels: for instance, anniversary fields may be
+labeled “birthday” or “wedding”, and URL fields might be labeled
+“homepage” or “file-sharing”.
- Fields built from ‘ebdb-field-user’ will have their own string name.
-EBDB comes with classes including “anniversary”, “url”, “id”,
-“relation”, “role” and more. Many of these fields have their own list
-of labels (for instance, anniversary fields may be labeled “birthday”,
-“wedding”, etc).
+ In the case of fields with labels, you’ll first choose the general
+field (“anniversary”) and then be prompted to choose the label
+(“birthday”). Again, if you choose a label that hasn’t been seen
+before, EBDB will first prompt for confirmation, then define the label
+for future use.
Loading secondary libraries may make more field types available.
* Menu:
-* Role Fields::
+* Role fields::
+* Tag field::
+* Mail folder field::
-File: ebdb.info, Node: Role Fields, Up: Field Types
+File: ebdb.info, Node: Role fields, Next: Tag field, Up: Field Types
-4.4.1 Role Fields
+4.4.1 Role fields
-----------------
One type of field worth mentioning in particular is the role field.
@@ -441,13 +445,12 @@ EBDB records come in two types at present: person and
organization.
People have roles at organizations: jobs, volunteer positions, etc.
People are also likely to have roles at more than one organization.
- When adding a role field to a record, you’ll be prompted to choose
-the relevant organization role, prompted for a string label denoting eg.
-a job title, and prompted for a mail address that belongs only to this
-role field (ie. an institutional email address). If the organization
-has a “domain” field type, and the person has an existing mail address
-that matches that domain, you’ll be prompted to move that address to the
-role field.
+ When adding a role field to a record, you’ll be prompted for a string
+label denoting eg. a job title, prompted for an organization, and
+prompted for a mail address that belongs only to this role field (ie. an
+institutional email address). If the organization has a “domain” field
+type, and the person has an existing mail address that matches that
+domain, you’ll be prompted to move that address to the role field.
When viewing organization records, the role fields for all related
person records are also displayed as part of the organization record.
@@ -455,7 +458,7 @@ person records are also displayed as part of the
organization record.
If a person’s role at an organization later comes to an end, the role
field can be deleted, or marked as “defunct”, if record keeping is
desired. This can only be done using the customize-based editing
-interface (the “E” key on the role field).
+interface (the ‘E’ key on the role field).
In fact, in addition to a mail field, role fields can contain an
arbitrary number of other fields, representing metadata about the role
@@ -468,6 +471,33 @@ very welcome.
This will be addressed in future.
+File: ebdb.info, Node: Tag field, Next: Mail folder field, Prev: Role
fields, Up: Field Types
+
+4.4.2 Tag field
+---------------
+
+EBDB comes with a field holding arbitrary tags for records. When
+searching on the tags field (using ‘/ x’ and selecting “tags”), EBDB
+provides the same tag search syntax as Org does, eg.
+“work|laptop+night”. *Note (org)Matching tags and properties:: for more
+information.
+
+ The ‘ebdb-org’ library comes with another tagging class,
+‘ebdb-org-field-tags’, that behaves just like the standard class, except
+the user’s Org-file tags are offered for completion. *note Org
+Integration::.
+
+
+File: ebdb.info, Node: Mail folder field, Prev: Tag field, Up: Field Types
+
+4.4.3 Mail folder field
+-----------------------
+
+The “mail folder” field is used to indicate which folder or group
+incoming mail from the contact should be filed into. Currently only
+Gnus supports this; support in other MUAs is forthcoming.
+
+
File: ebdb.info, Node: MUA Interaction, Next: EBDB Buffers, Prev: Record
Fields, Up: Top
5 MUA Interaction
@@ -502,7 +532,7 @@ mail, and Message for sending it, you’ll want two require
statements:
There are other packages that provide other MUA integration: these
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.
+and rmail.
File: ebdb.info, Node: Display and Updating, Next: EBDB and MUA summary
buffers, Prev: Loading MUA Code, Up: MUA Interaction
@@ -514,12 +544,9 @@ 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
@@ -538,18 +565,17 @@ File: ebdb.info, Node: Pop-up Buffers, Next:
Auto-Updating Records, Up: Displ
5.2.1 Pop-up Buffers
--------------------
-Each MUA associated with EBDB creates its own pop-up buffer, with a name
-like *EBDB-Gnus* or {{{(buf(EBDB-Rmail)}}}. 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.
+Each MUA creates its own EBDB pop-up buffer, with a name like
+*EBDB-Gnus* or *EBDB-Rmail*. 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.
-- User Option: 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 below).
- At present, there are *no* user customization options controlling the
+ 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.
@@ -565,15 +591,14 @@ based on information in an MUA message. The first and
most important
option governing this behavior is:
-- User Option: 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 ’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.
+ 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. The same process can be run interactively using
@@ -581,39 +606,33 @@ the commands below. When updating records either
automatically or
interactively, a few more options come into play:
-- User Option: ebdb-add-name
-
Whether to automatically change record names. See docstring for
details.
-- User Option: ebdb-add-aka
-
Whether to automatically add new names as akas. See docstring for
details.
-- User Option: ebdb-add-mails
-
How to handle apparently new mail addresses. See docstring for
details.
There are also options governing whether EBDB will consider a mail
address or not:
- -- User Option: ebdb-accept-header-alist
-
+ -- User Option: ebdb-accept-header-list
An alist governing which addresses in which headers will be
accepted. See docstring for details.
- -- User Option: ebdb-ignore-header-alist
-
+ -- User Option: ebdb-ignore-header-list
An alist governing which addresses in which headers will be
ignored. See docstring for details.
- -- User Option: ebdb-user-mail-address-re
-
+ -- User Option: ebdb-user-name-address-re
A regular expression matching the user’s own mail address(es). In
- addition to a regexp, this can also be the symbol ’message, in
+ addition to a regexp, this can also be the symbol ‘message’, in
which case the value will be copied from
- ‘message-alternative-emails’, or the symbol ’self, in which case
+ ‘message-alternative-emails’, or the symbol ‘self’, in which case
the value will be constructed from the record pointed to by the
option ‘ebdb-record-self’.
@@ -629,24 +648,21 @@ 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
+ 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 *note Generic Functions:
-(elisp)Generic%20Functions.; 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.
+bit of familiarity with *note (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.
File: ebdb.info, Node: Interactive Commands, Prev: Noticing and Automatic
Rules, Up: Display and Updating
@@ -660,32 +676,27 @@ keymap, and binds it to the key “;”. The following list
assumes this
binding, and only specifies the further binding. Ie, press “;:” to call
‘ebdb-mua-display-records’.
-‘:’ (‘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.
-
-‘;’ (‘ebdb-mua-display-all-records’)
+‘:’
+ If the option ‘ebdb-mua-auto-update-p’ is nil, this command
+ (‘ebdb-mua-update-records’) can be used to do the same thing, and
+ will behave as if that option were set to ‘query’.
+‘;’
If the option ‘ebdb-mua-pop-up’ is nil, this command can be used to
- do the same thing.
-
-‘'’ (‘ebdb-mua-edit-sender-notes’)
+ do the same thing (‘ebdb-mua-display-all-records’).
- This command allows you to edit the notes field of the message
- sender.
-
-‘``’ (‘ebdb-mua-in-ebdb-buffer’)
+‘'’
+ Edit the notes field of the message sender
+ (‘ebdb-mua-edit-sender-notes’).
+‘”’
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”
+ 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.
-‘s’ (‘ebdb-mua-snarf-article’)
-
+‘s’
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
@@ -694,25 +705,21 @@ binding, and only specifies the further binding. Ie,
press “;:” to call
before edits are made. This functionality is highly unreliable,
and probably won’t work as advertised.
- -- Command: ebdb-mua-yank-cc
+ Other command are not bound by default:
+ -- Command: ebdb-mua-yank-cc
Prompt for an existing *EBDB* buffer, and add addresses for all the
- records displayed there to the CC: line of the message being
+ records displayed there to the “CC:” line of the message being
composed. This command is not bound by default, because the EBDB
keymap is not bound by default in message composition MUAs.
- Other 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.
@@ -740,30 +747,26 @@ File: ebdb.info, Node: Sender name display, Next:
Summary buffer marks, Up: E
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. This only works for Gnus and
-VM, which allow for overriding how message senders are displayed. The
+name with information from the database. This only works for Gnus,
+which allows 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).
+for Gnus (which see).
-- User Option: ebdb-message-clean-name-function
-
A function used to clean up the name extracted from the headers of
a message.
-- User Option: ebdb-message-mail-as-name
-
If non-nil, the mail address will be used as a fallback for new
record names.
-- User Option: ebdb-mua-summary-unification-list
-
A list of fields used by ‘ebdb-mua-summary-unify’ to return a value
for unification. See docstring for details.
-- 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”.
+ Format letter to use for the EBDB-unified sender name in a Gnus
+ summary buffer. Defaults to “E”.
File: ebdb.info, Node: Summary buffer marks, Prev: Sender name display, Up:
EBDB and MUA summary buffers
@@ -772,30 +775,25 @@ File: ebdb.info, Node: Summary buffer marks, Prev:
Sender name display, Up: E
--------------------------
EBDB can display a one-character mark next to the name of senders that
-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:
+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:
-- 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
-
+ -- Method on ebdb-record: ebdb-mua-make-summary-mark record
This generic function accepts RECORD as a single argument, and
returns a single-character string to be used as a mark.
- • Field class: ebdb-field-summary-mark
-
- Give a record an instance of this field class to use a specific
- mark for that record.
+ Alternately, give a record an instance of the “summary mark” field
+class to use that specific mark for that record.
Marks are displayed in MUA summary buffers by customizing the format
-string provided by Gnus or VM, and adding the EBDB-specific format code:
+string provided by Gnus, and adding the EBDB-specific format code:
-- 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”.
@@ -814,20 +812,17 @@ using the ‘ebdb-clone-buffer’ and ‘ebdb-rename-buffer’
commands within
existing EBDB buffers.
-- User Option: ebdb-buffer-name
-
The base string that is used to create EBDB buffers, without
asterisks. Defaults to “EBDB”.
-‘b c’ (‘ebdb-clone-buffer’)
-
+‘b c’
Prompt for a buffer name, and create a new EBDB buffer displaying
- the same records as the original buffer.
-
-‘b r’ (‘ebdb-rename-buffer’)
+ the same records as the original buffer (‘ebdb-clone-buffer’).
- Rename the current EBDB buffer. If this is done in a MUA pop-up
- buffer, the original buffer will be recreated next time the MUA
- requests another pop up.
+‘b r’
+ Rename the current EBDB buffer (‘ebdb-rename-buffer’). If this is
+ done in a MUA pop-up buffer, the original buffer will be recreated
+ next time the MUA requests another pop up.
* Menu:
@@ -842,54 +837,56 @@ File: ebdb.info, Node: Searching, Next: The Basics of
ebdb-mode, Up: EBDB Buf
6.1 Searching
=============
-The most general search is performed with “/ /”, which searches on many
+The most general search is performed with ‘/ /’, which searches on many
different record fields and displays the results.
The EBDB major mode provides many keys for searching on specific
record fields. Most of these keys are used after one of three prefix
-keys, which change the behavior of the search: “/” clears the buffer
-before displaying the results, “|” searches only among the records
-already displayed, and “+” appends the search results to the records
+keys, which change the behavior of the search: ‘/’ clears the buffer
+before displaying the results, ‘|’ searches only among the records
+already displayed, and ‘+’ appends the search results to the records
already displayed.
- For instance, record name search is on the key “n”, meaning you can
-use “/ n”, “| n”, or “+ n”. Search keys that work this way are:
-
- • “n”: Search names
-
- • “o”: Search organizations
-
- • “p”: Search phones
-
- • “a”: Search addresses
-
- • “m”: Search mails
-
- • “x”: Search user fields (prompts for which field to search on)
-
- • “c”: Search records that have been modified since last save
-
- • “C”: Search by record class
-
- • “D”: Prompt for a database and display all records belonging to
- that database
-
- Search commands that currently only work with the “/” prefix are:
-
- • “/ 1”: Prompt for a single record, and display it
-
- • “/ d”: Search duplicate records
+ For instance, record name search is on the key ‘n’, meaning you can
+use ‘/ n’, ‘| n’, or ‘+ n’. Search keys that work this way are:
+
+‘n’
+ Search names
+‘o’
+ Search organizations
+‘p’
+ Search phones
+‘a’
+ Search addresses
+‘m’
+ Search mails
+‘x’
+ Search user fields (prompts for which field to search on)
+‘c’
+ Search records that have been modified since last save
+‘C’
+ Search by record class
+‘D’
+ Prompt for a database and display all records belonging to that
+ database
+
+ 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:
-‘!’ (‘ebdb-search-invert’)
-
- Invert the results of the next search.
+‘!’
+ Invert the results of the next search (‘ebdb-search-invert’).
Each user-created *EBDB* buffer keeps track of search history in that
buffer. To pop back to previous searches, use:
-‘^’ (‘ebdb-search-pop’)
+‘^’
+ ‘ebdb-search-pop’
* Menu:
@@ -904,17 +901,14 @@ File: ebdb.info, Node: Changing Search Behavior, Up:
Searching
There are three ways to alter the behavior of EBDB searches.
-- User Option: ebdb-case-fold-search
-
An equivalent to the regular ‘case-fold-search’ variable, which
see. Defaults to the value of that variable.
-- User Option: ebdb-char-fold-search
-
Controls whether character folding is used when matching search
strings against record values.
-- User Option: ebdb-search-transform-functions
-
A list of functions that can be used to arbitrarily transform
search strings. Each function should accept a single string
argument, and return the transformed string. If the search
@@ -925,7 +919,7 @@ There are three ways to alter the behavior of EBDB searches.
transform functions. Character folding works by calling
‘char-fold-to-regexp’ on the search string, effectively replacing
foldable characters within the string using regular expressions. This
-process happens /after/ the transform functions have run, so there is a
+process happens _after_ the transform functions have run, so there is a
possibility for unexpected search behavior.
@@ -937,126 +931,109 @@ File: ebdb.info, Node: The Basics of ebdb-mode, Next:
Marking, Prev: Searchin
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.
+‘n’
+ Move point to the next record (‘ebdb-next-record’).
-‘P’ (‘ebdb-prev-field’)
+‘p’
+ Move point to the previous record (‘ebdb-prev-record’).
- Move point to the previous field.
+‘N’
+ Move point to the next field (‘ebdb-next-field’).
-‘c’ (‘ebdb-create-record’)
+‘P’
+ Move point to the previous field (‘ebdb-prev-field’).
- Create a new person record in the primary database.
+‘c’
+ Create a new person record in the primary database
+ (‘ebdb-create-record’).
-‘C’ (‘ebdb-create-record-extended’)
-
- Prompt for database and record class, then create a new record.
-
-‘i’ (‘ebdb-insert-field’)
+‘C’
+ Prompt for database and record class, then create a new record
+ (‘ebdb-create-record-extended’).
+‘i’
Insert a new field into the record under point, or the marked
- records.
-
-‘e’ (‘ebdb-edit-field’)
+ records (‘ebdb-insert-field’).
- Edit the field under point.
+‘e’
+ Edit the field under point (‘ebdb-edit-field’).
-‘E’ (‘ebdb-edit-field-customize’)
-
- Use the extended customize interface to edit the field under point.
-
-‘;’ (‘ebdb-edit-foo’)
+‘E’
+ Use the extended customize interface to edit the field under point
+ (‘ebdb-edit-field-customize’).
+‘;’
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’)
+ prompt for an existing field and edit it (‘ebdb-edit-foo’).
+‘C-k’
With point on a record field, offer to delete that field. With
point on a record header, offer to delete the whole record.
+ (‘ebdb-delete-field-or-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’)
-
- Toggle between a multi-line and one-line display.
+‘<RET>’
+ Run an “action” on the field under point (‘ebdb-record-action’).
+ 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
-‘T’ (‘ebdb-display-records-completely’)
+‘m’
+ Begin composing a message to the record under point (‘ebdb-mail’).
+ With a prefix arg, prompt for the mail address to use; otherwise
+ use the record’s primary address.
- Display all of a record’s fields.
+‘t’
+ Toggle between a multi-line and one-line display
+ (‘ebdb-toggle-records-format’).
-‘r’ (‘ebdb-reformat-records’)
+‘T’
+ Display all of a record’s fields
+ (‘ebdb-display-records-completely’).
- Redisplay the record under point.
-
-‘o’ (‘ebdb-omit-records’)
+‘r’
+ Redisplay the record under point (‘ebdb-reformat-records’).
+‘o’
Remove the record under point (or marked records) from the buffer
- (does not delete the records).
-
-‘I’ (‘ebdb-cite-records-ebdb’)
+ (does not delete the records) (‘ebdb-omit-records’).
+‘I’
Put a “citation” for the record under point (or marked records)
- onto the kill ring. A “citation” is a name-and-mail string for the
- record. Prompt for a style, meaning a textual mode. With a prefix
- arg, arrange citations in a list, otherwise inline.
-
-‘w f’ (‘ebdb-copy-fields-as-kill’)
+ onto the kill ring (‘ebdb-cite-records-ebdb’). A “citation” is a
+ name-and-mail string for the record. Prompt for a style, meaning a
+ textual mode. With a prefix arg, arrange citations in a list,
+ otherwise inline.
- Copy the string value of the field under point to the kill ring.
+‘w f’
-‘w r’ (‘ebdb-copy-records-as-kill’)
+ Copy the string value of the field under point to the kill ring
+ (‘ebdb-copy-fields-as-kill’).
+‘w r’
Copy a string representation of the whole record under point to the
- kill ring.
-
-‘w m’ (‘ebdb-copy-mail-as-kill’)
+ kill ring (‘ebdb-copy-records-as-kill’).
+‘w m’
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.
+ the kill ring (‘ebdb-copy-mail-as-kill’). 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.
-‘?’ (‘ebdb-help’)
+‘g’
+ Redisplay all visible records (‘revert-buffer’).
- Show a very brief help message.
+‘?’
+ Show a very brief help message (‘ebdb-help’).
-‘h’ (‘ebdb-info’)
+‘h’
+ Open this manual (‘ebdb-info’).
- Open this manual.
+‘s’
+ Save all databases (‘ebdb-save’).
-‘s’ (‘ebdb-save’)
-
- Save all databases.
-
-‘q’ (‘quit-window’)
-
- Delete the *EBDB* window.
+‘q’
+ Delete the *EBDB* window (‘quit-window’).
*note Creating Records:: and *note Record Fields:: for more on record
creation and field manipulation.
@@ -1067,9 +1044,9 @@ File: ebdb.info, Node: Marking, Next:
Exporting/Formatting, Prev: The Basics
6.3 Marking
===========
-Records can be marked and acted on in bulk. The “#” key will toggle the
-mark of the record under point. “M-#” will toggle the marks of all the
-records in the buffer, and “C-#” will unmark all records in the buffer.
+Records can be marked and acted on in bulk. The ‘#’ key will toggle the
+mark of the record under point. ‘M-#’ will toggle the marks of all the
+records in the buffer, and ‘C-#’ unmarks all records in the buffer.
Many editing commands can act on multiple marked records.
@@ -1086,16 +1063,14 @@ buffers themselves, but other formats are possible.
imperfect: not all fields can be exported correctly. VCard version 2.1
is unsupported: the only options are version 3.0 and 4.0.
-‘f’ (‘ebdb-format-to-tmp-buffer’)
-
+‘f’
This command prompts for a formatter, and formats the record under
- point to a temporary buffer. Use *note marking: Marking. to format
- multiple records.
-
-‘F’ (‘ebdb-format-all-records’)
+ point to a temporary buffer (‘ebdb-format-to-tmp-buffer’). Use
+ *note marking: Marking. to format multiple records.
+‘F’
Export all records in the database (not only those displayed) to a
- different format.
+ different format (‘ebdb-format-all-records’).
It’s possible to write new formatters, documentation is forthcoming.
@@ -1106,19 +1081,18 @@ File: ebdb.info, Node: Completion, Next: Snarfing,
Prev: EBDB Buffers, Up: T
************
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.
+exist providing EBDB support for helm, counsel, and company. These
+libraries must be loaded from the package repositories, and 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
+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
+ Several native EBDB commands involve choosing 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
@@ -1141,7 +1115,6 @@ that contact.
and nearby names are acted upon, and it often doesn’t work correctly.
-- Command: ebdb-snarf &optional string start end recs
-
Extract record-related information from a piece of text. Find,
update, or create records as necessary, and then display them.
When the region is active, this command snarfs the current region,
@@ -1152,13 +1125,11 @@ and nearby names are acted upon, and it often doesn’t
work correctly.
in STRING.
-- User Option: ebdb-snarf-routines
-
An alist of field class symbols and related regexps. The regexps
are used to collect text that is likely parseable by the
‘ebdb-parse’ method of the field class.
-- User Option: ebdb-snarf-name-re
-
A list of regular expressions used to recognize names for a snarfed
contact. Searching names directly is mostly impossible, so names
are only looked for in close proximity to other field data.
@@ -1167,8 +1138,7 @@ and nearby names are acted upon, and it often doesn’t
work correctly.
This is separate from the updating process, which only examines the
article headers.
- -- Command: ebdb-mua-snarf-article
-
+ -- User Option: Command ebdb-mua-snarf-article &optional arg
Snarf the body of the current article. This will also snarf the
headers of forwarded emails, and the signature. With a prefix
argument, only snarf the signature.
@@ -1206,9 +1176,9 @@ less enthusiastically, are requests for new libraries.
Internationalization libraries do not modify the database, 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.
+searching purposes) in a record’s cache. Loading internationalization
+libraries may slow down initial database loading, though they should not
+significantly impact search or display performance.
Actually, the internationalization library does alter database
storage in one way: address countries can be either stored as a string
@@ -1222,9 +1192,9 @@ alter the display of some country names if they choose.
-- User Option: ebdb-i18n-countries-pref-scripts
This is an alist of conses pairing string country names to symbol
- labels—see the value of ‘ebdb-i18n-countries’ for how to use it,
- and to find the correct symbol label. Values set in this option
- will shadow the values in the variable.
+ labels—see the value of ‘ebdb-i18n-countries’ for the correct
+ format, and to find the correct symbol label. Values set in this
+ option will shadow the values in the variable.
File: ebdb.info, Node: Diary Integration, Next: Mail Aliases, Prev:
Internationalization, Up: Top
@@ -1240,11 +1210,10 @@ actual diary file present at the location indicated by
‘diary-file’,
though the file can be blank.
-- User Option: ebdb-use-diary
-
If non-nil, EBDB fields with date information will attempt to add
that information to the diary.
- When viewing the calendar, you can use the “d” key to see diary
+ When viewing the calendar, you can use the ‘d’ key to see diary
information for that day.
Support for this feature is rudimentary. More customization options
@@ -1260,11 +1229,11 @@ You can give records a mail alias with the “mail alias”
field, available
in the list of choices for inserting new fields. You’ll be prompted for
an alias, and an email address to use for the alias, if the record has
more than one. If multiple records have the same alias, then entering
-that alias in the To: or Cc: field of a message composition buffer will
-expand to a comma-separated list of record addresses.
+that alias in the “To:” or “Cc:” field of a message composition buffer
+will expand to a comma-separated list of record addresses.
At present, it’s necessary to manually parse existing aliases with
-the “A” key in a *EBDB* buffer. This limitation will be removed in the
+the ‘A’ key in a *EBDB* buffer. This limitation will be removed in the
future.
@@ -1288,28 +1257,38 @@ File: ebdb.info, Node: Org Integration, Next: Citing
Records, Prev: vCard Sup
******************
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
+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,
+ 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>”.
+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.
+Completion is offered as expected. *note Tag Field: Tag field.
+
+ This library comes with one other function that allows you to pop up
+an *EBDB* buffer alongside an Org Agenda buffer.
+
+ -- Command: ebdb-org-agenda-popup
+ Pop up an EBDB buffer displaying contacts matching the tags used to
+ create the Agenda buffer. Only does anything in a tags search
+ Agenda buffer.
+
+ This function could also be added to the ‘org-agenda-mode-hook’, to
+pop up a buffer any time relevant records are found.
File: ebdb.info, Node: Citing Records, Next: Hacking EBDB, Prev: Org
Integration, Up: Top
@@ -1323,7 +1302,6 @@ 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,
@@ -1338,7 +1316,7 @@ File: ebdb.info, Node: Hacking EBDB, Next: Index,
Prev: Citing Records, Up:
EBDB is designed to be highly extensible. In addition to the usual
customization options, it provides for subclassing of the three main
-classes – database, record, and field. The behavior of EBDB can be
+classes: database, record, and field. The behavior of EBDB can be
radically changed by creating new classes, or overriding the existing
methods of classes, without touching the original source code. This
manual won’t go into details about Emacs’ object-orientation support:
@@ -1350,34 +1328,28 @@ writing generic functions and methods.
for basic record and field types.
-- User Option: ebdb-default-record-class
-
The default class used for creating records. This class will be
- used when creating records with “c” in ebdb-mode, or when
+ used when creating records with ‘c’ in ebdb-mode, or when
automatically creating records (ie, from snarfing). It’s always
- possible to create a record of a different class by using “C” in
+ possible to create a record of a different class by using ‘C’ in
ebdb-mode.
- -- User Option: ebdb-default-name-class
-
+ -- User Option: ebdb-default-record-class
The default class for complex names. Simple names (used for
- organizations and nicknames) are always plain strings – this option
+ organizations and nicknames) are always plain strings—this option
only governs the class used for articulated names of individuals,
with separate slots for surname, given names, suffixes, etc.
-- User Option: ebdb-default-mail-class
-
The default class for mail fields.
-- User Option: ebdb-default-phone-class
-
The default class for phone fields.
-- User Option: ebdb-default-address-class
-
The default class for address fields.
-- User Option: ebdb-default-notes-class
-
The default class for notes fields.
If, for instance, you’d like to create a custom mail field and have
@@ -1433,10 +1405,10 @@ which returns a string representation of the field
instance. The
simplest field types only need to provide these three methods.
The ‘ebdb-read’ and ‘ebdb-parse’ methods are static (class-level)
-methods. Both take an optional “slots” argument, which a plist of slot
+methods. Both take an optional ‘slots’ argument, which a plist of slot
values that will eventually be fed to ‘make-instance’. If values are
-already present in the plist, these methods should /not/ override them.
-In addition, ‘ebdb-read’ takes an optional “obj” argument, which, if
+already present in the plist, these methods should _not_ override them.
+In addition, ‘ebdb-read’ takes an optional ‘obj’ argument, which, if
present, is an existing field instance that can be used to provide
default values for the new object.
@@ -1464,6 +1436,7 @@ default values for the new object.
* Init and Delete Methods::
* The Labeled Field Class::
+* The Singleton Field Class::
* Actions::
* Custom Field Searching::
* Formatting in the EBDB Buffer::
@@ -1479,37 +1452,35 @@ It’s also very common to define ‘ebdb-init-field’ and
maintain secondary data structures, or set up extra hashing for records,
or do any other supplemental work. The one restriction is that they
must not change the database: they may not edit records or their fields.
-Both methods are called with the field instance as the first argument,
-and the record the instance belongs to as an optional second argument.
-‘ebdb-delete-field’ also accepts an optional third argument, “unload”,
-which is non-nil when the record is being unloaded, rather than deleted.
+
+ -- Method: ebdb-init-field field record
+ Initialize FIELD against RECORD.
+
+ -- Method: ebdb-delete-field field &optional record unload
+ Delete FIELD of record RECORD. If the optional argument UNLOAD is
+ non-nil, it means the record is only being unloaded
Both methods should always end with a call to ‘cl-call-next-method’.
‘ebdb-init-field’ is called:
- • When loading for the first time (records call ‘ebdb-init-field’ on
+ 1. When loading for the first time (records call ‘ebdb-init-field’ on
all of their fields after they’re loaded).
-
- • When adding a new field instance to a record.
-
- • When editing an existing field instance (editing is a
+ 2. When adding a new field instance to a record.
+ 3. When editing an existing field instance (editing is a
delete-and-create operation).
‘ebdb-delete-field’ is called:
- • When deleting a field instance.
-
- • When deleting the record owning the field instance.
-
- • When editing an existing field instance (editing is a
+ 1. When deleting a field instance.
+ 2. When deleting the record owning the field instance.
+ 3. When editing an existing field instance (editing is a
delete-and-create operation).
-
- • When unloading a record from the database (the optional third
- “unload” argument will be non-nil).
+ 4. When unloading a record from the database (the optional third
+ UNLOAD argument will be non-nil).
-File: ebdb.info, Node: The Labeled Field Class, Next: Actions, Prev: Init
and Delete Methods, Up: Field Classes
+File: ebdb.info, Node: The Labeled Field Class, Next: The Singleton Field
Class, Prev: Init and Delete Methods, Up: Field Classes
15.1.2 The Labeled Field Class
------------------------------
@@ -1528,17 +1499,28 @@ used to hold labels, and pointing to it in the
class-allocated
((label-list :initform my-field-label-list)))
-File: ebdb.info, Node: Actions, Next: Custom Field Searching, Prev: The
Labeled Field Class, Up: Field Classes
+File: ebdb.info, Node: The Singleton Field Class, Next: Actions, Prev: The
Labeled Field Class, Up: Field Classes
-15.1.3 Actions
+15.1.3 The Singleton Field Class
+--------------------------------
+
+Another abstract mix-in class is the ‘ebdb-field-singleton’ class. It’s
+only function is to ensure that a record only ever has one instance of
+the class in question. If the user tries to add a second instance, the
+existing instance is deleted.
+
+
+File: ebdb.info, Node: Actions, Next: Custom Field Searching, Prev: The
Singleton Field Class, Up: Field Classes
+
+15.1.4 Actions
--------------
All field classes have a class-allocated slot called “actions”. The
value of this slot is a list of conses, for instance: ‘("Browse URL" .
ebdb-field-url-browse)’. Users can trigger these actions by pressing
-“RET” while point is on the field in the *EBDB* buffer, using a numeric
-prefix arg to select from multiple possible actions, or the 0 prefix arg
-to be prompted for which action to take.
+‘<RET>’“ while point is on the field in the *EBDB* buffer, using a
+numeric prefix arg to select from multiple possible actions, or the 0
+prefix arg to be prompted for which action to take.
The functions in this list should accept two arguments, the record
and the field instance under point.
@@ -1546,7 +1528,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
-15.1.4 Custom Field Searching
+15.1.5 Custom Field Searching
-----------------------------
In most cases, searching the EBDB database is a matter of prompting for
@@ -1579,18 +1561,43 @@ The label string will first be matched against the
label of the
instance, and then other-search-criteria will be passed to the
‘ebdb-field-search’ method as usual.
+ That might sound a bit confusing, here’s an example. These are the
+search methods for the ‘ebdb-field-tags’ class.
+
+ (cl-defmethod ebdb-search-read ((_class (subclass ebdb-field-tags)))
+ (cdr
+ (org-make-tags-matcher
+ (ebdb-read-string
+ "Search for tags (eg +tag1-tag2|tag3): "))))
+
+ (cl-defmethod ebdb-field-search ((field ebdb-field-tags)
+ func)
+ (when (functionp func)
+ (funcall func t (slot-value field 'tags) 1)))
+
+ (cl-defmethod ebdb-field-search ((field ebdb-field-tags)
+ (tag string))
+ (seq-find (lambda (tg) (string-match-p tag tg))
+ (slot-value field 'tags)))
+
+ The ‘ebdb-search-read’ method returns a lambda (the ‘cdr’ of the
+return value of ‘org-make-tags-matcher’. The first ‘ebdb-field-search’
+method handles that lambda, simply by calling it. The second
+‘ebdb-field-search’ method handles a string search criterion; though no
+EBDB code would create this search, external code conceivably might.
+
File: ebdb.info, Node: Formatting in the EBDB Buffer, Prev: Custom Field
Searching, Up: Field Classes
-15.1.5 Formatting in the EBDB Buffer
+15.1.6 Formatting in the EBDB Buffer
------------------------------------
Most fields will be displayed in the *EBDB* buffer simply using
‘ebdb-string’. It’s possible to customize this display by overriding
the ‘ebdb-fmt-field’ method. Without going into too much detail, this
method dispatches on four arguments: the formatter, the field, a “style”
-symbol argument (typically ’normal, ’oneline, ’compact’, ’collapse or
-’expanded), and the record being formatted.
+symbol argument (typically ‘normal’, ‘oneline’, ‘compact’, ‘collapse’ or
+‘expanded’), and the record being formatted.
Specify an ebdb formatter for the first argument to target *EBDB*
formatting. Choices are ‘ebdb-formatter-ebdb’ (for all cases), or one
@@ -1598,15 +1605,16 @@ of ‘ebdb-formatter-ebdb-multiline’ or
‘ebdb-formatter-ebdb-oneline’.
Keep in mind that many field classes are not displayed at all in the
oneline format.
- An example: most fields are output with style set to ’normal, meaning
-that it will use the value of ‘ebdb-string’. By default, formatters
-display address fields in the ’collapse style, which is mapped to the
-’oneline style, which simply drops everything after the first newline.
+ An example: most fields are output with style set to ‘normal’,
+meaning that it will use the value of ‘ebdb-string’. By default,
+formatters display address fields in the ‘collapse’ style, which is
+mapped to the ‘oneline’ style, which simply drops everything after the
+first newline.
Say you still wanted addresses output on a single line, but you
wanted to provide a little more information on that line: the first line
of the street addresses, plus the city, plus the country. You could
-achieve that by overriding the ’collapse style like so:
+achieve that by overriding the ‘collapse’ style like so:
(cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter)
(field ebdb-field-address)
@@ -1656,11 +1664,9 @@ the nationality or locality of the field instance.
316601 alpha 3 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
country codes. These codes can be found in the variable
‘ebdb-i18n-countries’.
-
• Phone fields use the phone number’s numerical country code as a
spec. These codes can be found in the variable
‘ebdb-i18n-phone-codes’.
-
• Name fields are keyed to the symbol representing the script used to
write them. Specifically, the first character CHAR of the name is
tested in this way: ‘(aref char-script-table CHAR)’, which returns
@@ -1680,9 +1686,9 @@ to handle the extra argument, called SPEC.
a string that looks like “+33 05 12 34 56 79”. This is not how they are
stored in the database, but this is how they should be represented to
the user. We need to override the ‘ebdb-string-i18n’ method for the
-phone field class. This method takes two arguments – the field
-instance, and the country-code spec – and needs to specialize on both
-arguments. The method signature will look like this:
+phone field class. This method takes two arguments—the field instance,
+and the country-code spec—and needs to specialize on both arguments.
+The method signature will look like this:
(cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
(_cc (eql 33))))
@@ -1690,10 +1696,10 @@ arguments. The method signature will look like this:
See the manual on generic functions for details; suffice it to say
that this method will only run when the first argument is an instance of
the ‘ebdb-field-phone’ class (or a subclass), and the second argument is
-the number 33.
+‘eql’ to the number 33.
- Now we know that this method will only run for French phone numbers,
-so we can format the number correctly:
+ We know that this method will only run for French phone numbers, so
+we can format the number correctly:
(cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
(_cc (eql 33)))
@@ -1754,7 +1760,6 @@ contents of the appropriate header. For instance, in
Gnus:
(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
@@ -1767,20 +1772,20 @@ 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
+ -- Method: 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
+ -- Method: 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
+ -- Method: 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
@@ -1808,10 +1813,10 @@ 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
+ -- Method: ebdb-mua-article-body
Return the text of the article body, or nil.
- -- Function: ebdb-mua-article-signature
+ -- Method: ebdb-mua-article-signature
Return the text of the article signature, or nil.
@@ -1823,161 +1828,355 @@ Index
[index ]
* Menu:
+* !: Searching. (line 49)
+* ": Interactive Commands.
+ (line 26)
+* ': Interactive Commands.
+ (line 22)
+* / /: Searching. (line 6)
+* :: Interactive Commands.
+ (line 13)
+* ;: Interactive Commands.
+ (line 18)
+* ; <1>: The Basics of ebdb-mode.
+ (line 41)
+* ?: The Basics of ebdb-mode.
+ (line 102)
+* ^: Searching. (line 55)
+* Article snarfing: Snarfing. (line 35)
+* Article snarfing <1>: Article snarfing. (line 6)
+* auto-save of Database: The EBDB Database. (line 24)
+* Automatic Rules: Noticing and Automatic Rules.
+ (line 6)
+* b c: EBDB Buffers. (line 19)
+* b r: EBDB Buffers. (line 23)
+* buffer-char of Database: The EBDB Database. (line 27)
+* c: Creating Records. (line 6)
+* C: Creating Records. (line 14)
+* c <1>: The Basics of ebdb-mode.
+ (line 22)
+* C <1>: The Basics of ebdb-mode.
+ (line 26)
+* C-k: Deleting Records and Fields.
+ (line 6)
+* C-k <1>: The Basics of ebdb-mode.
+ (line 45)
+* Command: Snarfing. (line 39)
* Creating a database: The EBDB Database. (line 11)
* Creating records: Creating Records. (line 6)
-* Deleting records and fields: Deleting Records and Fields.
+* Customizing search: Changing Search Behavior.
+ (line 6)
+* d c: The EBDB Database. (line 61)
+* d d: The EBDB Database. (line 72)
+* d e: The EBDB Database. (line 46)
+* d m: The EBDB Database. (line 57)
+* d r: The EBDB Database. (line 67)
+* Databases: The EBDB Database. (line 11)
+* Deleting fields: Deleting Records and Fields.
+ (line 6)
+* Deleting records: Deleting Records and Fields.
(line 6)
* Diary integration: Diary Integration. (line 6)
+* disabled of Database: The EBDB Database. (line 31)
+* e: Editing Existing Fields.
+ (line 6)
+* E: Editing Existing Fields.
+ (line 9)
+* e <1>: The Basics of ebdb-mode.
+ (line 34)
+* E <1>: The Basics of ebdb-mode.
+ (line 37)
+* ebdb-accept-header-list: Auto-Updating Records.
+ (line 40)
+* ebdb-add-aka: Auto-Updating Records.
+ (line 29)
+* ebdb-add-mails: Auto-Updating Records.
+ (line 33)
+* ebdb-add-name: Auto-Updating Records.
+ (line 25)
+* ebdb-buffer-name: EBDB Buffers. (line 14)
+* ebdb-case-fold-search: Changing Search Behavior.
+ (line 8)
+* ebdb-char-fold-search: Changing Search Behavior.
+ (line 12)
* ebdb-cite-records: Citing Records. (line 11)
* ebdb-cite-records-ebdb: The Basics of ebdb-mode.
- (line 86)
+ (line 76)
* ebdb-clone-buffer: EBDB Buffers. (line 19)
* ebdb-copy-fields-as-kill: The Basics of ebdb-mode.
- (line 93)
+ (line 83)
* ebdb-copy-mail-as-kill: The Basics of ebdb-mode.
- (line 102)
-* ebdb-copy-record record to-db: The EBDB Database. (line 67)
+ (line 92)
* ebdb-copy-records-as-kill: The Basics of ebdb-mode.
- (line 97)
-* 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)
+ (line 88)
+* ebdb-create-record: Creating Records. (line 6)
+* ebdb-create-record <1>: The Basics of ebdb-mode.
+ (line 22)
+* ebdb-create-record-extended: Creating Records. (line 14)
+* ebdb-create-record-extended <1>: The Basics of ebdb-mode.
+ (line 26)
+* ebdb-default-address-class: Hacking EBDB. (line 38)
+* ebdb-default-mail-class: Hacking EBDB. (line 32)
+* ebdb-default-notes-class: Hacking EBDB. (line 41)
+* ebdb-default-phone-class: Hacking EBDB. (line 35)
+* ebdb-default-record-class: Creating Records. (line 10)
+* ebdb-default-record-class <1>: Hacking EBDB. (line 19)
+* ebdb-default-record-class <2>: Hacking EBDB. (line 26)
+* ebdb-delete-field: Init and Delete Methods.
+ (line 15)
* ebdb-delete-field-or-record: The Basics of ebdb-mode.
- (line 51)
-* ebdb-disable-database db: The EBDB Database. (line 78)
+ (line 45)
+* ebdb-delete-record-or-field: Deleting Records and Fields.
+ (line 6)
* 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)
+ (line 65)
+* ebdb-edit-field: Editing Existing Fields.
+ (line 6)
+* ebdb-edit-field <1>: The Basics of ebdb-mode.
+ (line 34)
+* ebdb-edit-field-customize: Editing Existing Fields.
+ (line 9)
+* ebdb-edit-field-customize <1>: The Basics of ebdb-mode.
+ (line 37)
* ebdb-edit-foo: The Basics of ebdb-mode.
- (line 46)
+ (line 41)
+* ebdb-field-search: Custom Field Searching.
+ (line 24)
* ebdb-format-all-records: Exporting/Formatting.
(line 20)
* ebdb-format-to-tmp-buffer: Exporting/Formatting.
- (line 14)
+ (line 15)
* ebdb-help: The Basics of ebdb-mode.
- (line 114)
+ (line 102)
+* ebdb-i18n-countries: Internationalization.
+ (line 44)
+* ebdb-i18n-countries-pref-scripts: Internationalization.
+ (line 47)
+* ebdb-ignore-header-list: Auto-Updating Records.
+ (line 44)
* ebdb-info: The Basics of ebdb-mode.
- (line 118)
-* ebdb-insert-field: The Basics of ebdb-mode.
- (line 33)
+ (line 105)
+* ebdb-init-field: Init and Delete Methods.
+ (line 12)
+* ebdb-insert-field: Inserting New Fields.
+ (line 6)
+* ebdb-insert-field <1>: The Basics of ebdb-mode.
+ (line 30)
* ebdb-mail: The Basics of ebdb-mode.
- (line 63)
-* ebdb-move-record record to-db: The EBDB Database. (line 63)
+ (line 56)
+* ebdb-make-buffer-name: Writing Integration For New MUAs.
+ (line 54)
+* ebdb-message-clean-name-function: Sender name display. (line 14)
+* ebdb-message-mail-as-name: Sender name display. (line 18)
+* ebdb-mua-article-body: Article snarfing. (line 13)
+* ebdb-mua-article-signature: Article snarfing. (line 16)
+* ebdb-mua-auto-update: Writing Integration For New MUAs.
+ (line 11)
+* ebdb-mua-auto-update-p: Auto-Updating Records.
+ (line 10)
* ebdb-mua-display-all-recipients: Interactive Commands.
- (line 63)
+ (line 55)
* ebdb-mua-display-all-records: Interactive Commands.
(line 18)
* ebdb-mua-display-recipients: Interactive Commands.
- (line 59)
+ (line 52)
* ebdb-mua-display-sender: Interactive Commands.
- (line 55)
+ (line 49)
* ebdb-mua-edit-sender-notes: Interactive Commands.
- (line 23)
+ (line 22)
* ebdb-mua-in-ebdb-buffer: Interactive Commands.
- (line 28)
+ (line 26)
+* ebdb-mua-keymap: Writing Integration For New MUAs.
+ (line 67)
+* ebdb-mua-make-summary-mark on ebdb-record: Summary buffer marks.
+ (line 15)
+* ebdb-mua-message-header: Writing Integration For New MUAs.
+ (line 22)
+* ebdb-mua-pop-up: Pop-up Buffers. (line 11)
+* ebdb-mua-prepare-article: Writing Integration For New MUAs.
+ (line 47)
* ebdb-mua-snarf-article: Interactive Commands.
- (line 36)
-* ebdb-mua-snarf-article <1>: Snarfing. (line 42)
+ (line 33)
+* ebdb-mua-summary-mark: Summary buffer marks.
+ (line 11)
+* ebdb-mua-summary-mark-format-letter: Summary buffer marks.
+ (line 25)
+* ebdb-mua-summary-unification-list: Sender name display. (line 22)
+* ebdb-mua-summary-unify-format-letter: Sender name display. (line 26)
* ebdb-mua-update-records: Interactive Commands.
- (line 12)
+ (line 13)
* ebdb-mua-yank-cc: Interactive Commands.
- (line 46)
+ (line 43)
* ebdb-next-field: The Basics of ebdb-mode.
- (line 17)
+ (line 16)
* ebdb-next-record: The Basics of ebdb-mode.
- (line 9)
+ (line 10)
+* ebdb-notice-field: Noticing and Automatic Rules.
+ (line 21)
+* ebdb-notice-mail-hook: Noticing and Automatic Rules.
+ (line 16)
+* ebdb-notice-record-hook: Noticing and Automatic Rules.
+ (line 11)
* ebdb-omit-records: The Basics of ebdb-mode.
- (line 81)
+ (line 72)
+* ebdb-org-agenda-popup: Org Integration. (line 32)
+* ebdb-popup-window: Writing Integration For New MUAs.
+ (line 60)
* ebdb-prev-field: The Basics of ebdb-mode.
- (line 21)
+ (line 19)
* ebdb-prev-record: The Basics of ebdb-mode.
(line 13)
* ebdb-record-action: The Basics of ebdb-mode.
- (line 56)
+ (line 50)
+* ebdb-record-self: Creating Records. (line 21)
* 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)
+ (line 69)
+* ebdb-rename-buffer: EBDB Buffers. (line 23)
* ebdb-save: The Basics of ebdb-mode.
- (line 122)
-* ebdb-search-invert: Searching. (line 46)
-* ebdb-search-pop: Searching. (line 53)
-* ebdb-snarf &optional string start end recs: Snarfing. (line 15)
+ (line 108)
+* ebdb-search-invert: Searching. (line 49)
+* ebdb-search-pop: Searching. (line 55)
+* ebdb-search-read: Custom Field Searching.
+ (line 18)
+* ebdb-search-transform-functions: Changing Search Behavior.
+ (line 16)
+* ebdb-snarf: Snarfing. (line 15)
+* ebdb-snarf-name-re: Snarfing. (line 30)
+* ebdb-snarf-routines: Snarfing. (line 25)
+* ebdb-sources: The EBDB Database. (line 11)
* ebdb-toggle-records-format: The Basics of ebdb-mode.
- (line 69)
+ (line 61)
+* ebdb-use-diary: Diary Integration. (line 13)
+* ebdb-user-name-address-re: Auto-Updating Records.
+ (line 48)
* Editing fields: Editing Existing Fields.
(line 6)
+* f: Exporting/Formatting.
+ (line 15)
+* F: Exporting/Formatting.
+ (line 20)
+* Field actions: The Basics of ebdb-mode.
+ (line 50)
+* Field actions <1>: Actions. (line 6)
+* g: The Basics of ebdb-mode.
+ (line 99)
+* h: The Basics of ebdb-mode.
+ (line 105)
+* i: Inserting New Fields.
+ (line 6)
+* i <1>: The Basics of ebdb-mode.
+ (line 30)
+* I: The Basics of ebdb-mode.
+ (line 76)
* Inserting new fields: Inserting New Fields.
(line 6)
* Internationalization: Internationalization.
(line 6)
+* Inverting searches: Searching. (line 46)
+* m: The Basics of ebdb-mode.
+ (line 56)
* Mail aliases: Mail Aliases. (line 6)
* Migrating from BBDB: Migration from BBDB. (line 6)
+* MUA Display: Display and Updating.
+ (line 6)
+* MUA Updating: Display and Updating.
+ (line 6)
+* n: The Basics of ebdb-mode.
+ (line 10)
+* N: The Basics of ebdb-mode.
+ (line 16)
+* o: The Basics of ebdb-mode.
+ (line 72)
+* p: The Basics of ebdb-mode.
+ (line 13)
+* P: The Basics of ebdb-mode.
+ (line 19)
+* q: The Basics of ebdb-mode.
+ (line 111)
* quit-window: The Basics of ebdb-mode.
- (line 126)
+ (line 111)
+* r: The Basics of ebdb-mode.
+ (line 69)
+* read-only of Database: The EBDB Database. (line 20)
+* record-class of Database: The EBDB Database. (line 37)
+* RET: The Basics of ebdb-mode.
+ (line 50)
* revert-buffer: The Basics of ebdb-mode.
- (line 110)
+ (line 99)
+* s: Interactive Commands.
+ (line 33)
+* s <1>: The Basics of ebdb-mode.
+ (line 108)
+* Search history: Searching. (line 51)
* Searching the EBDB: Searching. (line 6)
* Snarfing text: Snarfing. (line 6)
+* t: The Basics of ebdb-mode.
+ (line 61)
+* T: The Basics of ebdb-mode.
+ (line 65)
+* w f: The Basics of ebdb-mode.
+ (line 83)
+* w m: The Basics of ebdb-mode.
+ (line 92)
+* w r: The Basics of ebdb-mode.
+ (line 88)
Tag Table:
Node: Top806
-Node: Getting Started2320
-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 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: Marking34822
-Node: Exporting/Formatting35250
-Node: Completion36209
-Node: Snarfing37420
-Node: Internationalization39399
-Node: Diary Integration42112
-Node: Mail Aliases42978
-Node: vCard Support43687
-Node: Org Integration44186
-Node: Citing Records45760
-Node: Hacking EBDB46519
-Node: Field Classes48849
-Node: Init and Delete Methods51786
-Node: The Labeled Field Class53342
-Node: Actions54178
-Node: Custom Field Searching54843
-Node: Formatting in the EBDB Buffer56631
-Node: Writing Internationalization Libraries58630
-Node: Writing Integration For New MUAs62981
-Node: Article snarfing66407
-Node: Index67129
+Node: Getting Started2386
+Node: Migration from BBDB3009
+Node: Record Migration3184
+Node: Variables and Options3762
+Node: The EBDB Database4248
+Node: Creating Records7539
+Node: Record classes8620
+Node: Record names8965
+Node: Record Fields9640
+Node: Inserting New Fields9884
+Node: Editing Existing Fields10680
+Node: Deleting Records and Fields11280
+Node: Field Types11676
+Node: Role fields13867
+Node: Tag field15555
+Node: Mail folder field16199
+Node: MUA Interaction16527
+Node: Loading MUA Code17051
+Node: Display and Updating17760
+Node: Pop-up Buffers18526
+Node: Auto-Updating Records19364
+Node: Noticing and Automatic Rules21764
+Node: Interactive Commands23097
+Node: EBDB and MUA summary buffers25459
+Node: Sender name display25945
+Node: Summary buffer marks27172
+Node: EBDB Buffers28351
+Node: Searching29533
+Node: Changing Search Behavior31195
+Node: The Basics of ebdb-mode32442
+Node: Marking36043
+Node: Exporting/Formatting36467
+Node: Completion37416
+Node: Snarfing38614
+Node: Internationalization40615
+Node: Diary Integration43314
+Node: Mail Aliases44179
+Node: vCard Support44900
+Node: Org Integration45399
+Node: Citing Records47297
+Node: Hacking EBDB48055
+Node: Field Classes50376
+Node: Init and Delete Methods53343
+Node: The Labeled Field Class54850
+Node: The Singleton Field Class55704
+Node: Actions56145
+Node: Custom Field Searching56817
+Node: Formatting in the EBDB Buffer59638
+Node: Writing Internationalization Libraries61661
+Node: Writing Integration For New MUAs66014
+Node: Article snarfing69433
+Node: Index70151
End Tag Table
diff --git a/ebdb.org b/ebdb.org
index d3fcb5c..812dcd5 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -1,15 +1,17 @@
# -*- sentence-end-double-space: t -*-
#+TEXINFO_CLASS: info
-#+TEXINFO_HEADER: @syncodeindex pg cp
+#+TEXINFO_HEADER: @syncodeindex vr cp
+#+TEXINFO_HEADER: @syncodeindex fn cp
+#+TEXINFO_HEADER: @syncodeindex ky cp
#+AUTHOR: Eric Abrahamsen <address@hidden>
#+TITLE: EBDB Manual
#+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: kbd @@texinfo:@kbd{$1}@@
* Copying
:PROPERTIES:
@@ -64,110 +66,137 @@ stores its contacts in the same file as the database
itself, though
other database classes may store contacts elsewhere.
#+CINDEX: Creating a database
-- User Option: ebdb-sources
-
- User option specifying one or more databases to load. It can be a
- single element, or a list of elements. Each element can be a
- filename, from which a database is loaded, or it can be an instance
- of a subclass of the ~ebdb-db~ class. The database at the head of
- the list will be considered the default database.
+#+CINDEX: Databases
+#+TEXINFO: @defopt ebdb-sources
+User option specifying one or more databases to load. It can be a
+single element, or a list of elements. Each element can be a
+filename, from which a database is loaded, or it can be an instance of
+a subclass of the ~ebdb-db~ class. The database at the head of the
+list will be considered the default database.
+#+TEXINFO: @end defopt
Databases have a few user-facing settings:
-- User Option: read-only
-
- If t, records can only be read from the database, not edited or
- deleted.
-
-- User Option: auto-save
-
- Set to nil to prevent auto-saving of the database's records.
-
-- User Option: buffer-char
-
- Set to a single character that will be displayed next to records in
- the {{{buf(EBDB)}}} buffer, indicating which database they belong
- to.
-
-- User Option: disabled
-
- When t, the database will essentially be ignored -- no records will
- be read from it. Setting this to t will only take effect on next
- restart; to disable a database immediately, use
- ~ebdb-disable-database~ below.
-
-- User Option: record-class
-
- The default record class to use when creating new records in this
- database. The default is ~ebdb-default-record-class~.
+#+ATTR_TEXINFO: :options Database @code{boolean} read-only
+#+begin_deftypeivar
+If non-nil, records can only be read from the database, not edited or
+deleted.
+#+end_deftypeivar
+
+#+ATTR_TEXINFO: :options Database @code{boolean} auto-save
+#+begin_deftypeivar
+If non-nil, the database's records will not be autosaved.
+#+end_deftypeivar
+
+#+ATTR_TEXINFO: :options Database @code{character} buffer-char
+#+begin_deftypeivar
+A single character that will be displayed next to records in the
+{{{buf(EBDB)}}} buffer, indicating which database they belong to.
+#+end_deftypeivar
+
+#+ATTR_TEXINFO: :options Database @code{boolean} disabled
+#+begin_deftypeivar
+When non-nil , the database will essentially be ignored---no records
+will be read from it. Setting this to t will only take effect on next
+restart; to disable a database immediately, use
+~ebdb-disable-database~ below.
+#+end_deftypeivar
+
+#+ATTR_TEXINFO: :options Database @code{symbol} record-class
+#+begin_deftypeivar
+The default record class to use when creating new records in this
+database. The default is ~ebdb-default-record-class~.
+#+end_deftypeivar
While it's possible to edit database definitions directly in the file,
it's safer to use the customization interface to do so from the
{{{buf(EBDB)}}} buffer.
-- Key: d e, ebdb-customize-database db
+#+attr_texinfo: :indic @kbd
+- d e ::
- Use the customize interface to edit the definition of DB.
+ #+KINDEX: d e
+ Use the customize interface to edit the definition of a database
+ (~ebdb-customize-database~).
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"
+than one database, the two copies are compared using the timestamp
field, and the older copy is discarded. In an {{{buf(EBDB)}}} buffer,
-the following keys can be used to manipulate databases and their records.
+the following keys can be used to manipulate databases and their
+records.
-- Key: d m, ebdb-move-record record to-db
+#+attr_texinfo: :indic @kbd
+- d m ::
- Move RECORD from its existing database to TO-DB.
+ #+KINDEX: d m
+ Move a record from its current database to another
+ (~ebdb-move-record~).
-- Key: d c, ebdb-copy-record record to-db
+- d c ::
- Copy RECORD into TO-DB, leaving it in its existing database(s).
+ #+KINDEX: d c
+ Copy a record into a new database, leaving it in its existing
+ database(s) (~ebdb-copy-record~).
Other database-related commands:
-- Key: d r, ebdb-reload-database db
+#+attr_texinfo: :indic @kbd
+- d r ::
- Reload all records from a database. This also redisplays any of
- those records that were visible in {{{buf(EBDB)}}} buffers.
+ #+KINDEX: d r
+ Reload all records from a database. This also redisplays any of
+ those records that were visible in {{{buf(EBDB)}}} buffers
+ (~ebdb-reload-database~).
-- Key: d d, ebdb-disable-database db
+- d d ::
- This command disables a database, unloading all of its records and
- essentially ignoring it from now on. The disabled state persists
- between restarts. To re-enable a database, edit it using
- ~ebdb-customize-database~, set 'disabled to nil, and then reload it
- with ~ebdb-reload-database~.
+ #+KINDEX: d d
+ This command (~ebdb-disable-database~) disables a database,
+ unloading all of its records and essentially ignoring it from now
+ on. The disabled state persists between restarts. To re-enable
+ a database, edit it using ~ebdb-customize-database~, set
+ ~disabled~ to nil, and then reload it with ~ebdb-reload-database~.
* Creating Records
:PROPERTIES:
:ID: 692cde31-73be-4faf-b436-7eae8a5d02d1
:END:
#+CINDEX: Creating records
-Create a record using "c" (~ebdb-create~) in the {{{buf(EBDB)}}} buffer.
-With no prefix arg, this command will create an instance of the
+#+KINDEX: c
+#+FINDEX: ebdb-create-record
+Create a record using {{{kbd(c)}}} (~ebdb-create-record~) in the
+{{{buf(EBDB)}}} buffer. This command will create an instance of the
default record class, in the database at the head of ~ebdb-sources~.
-- User Option: ebdb-default-record-class
-
- The default record class to use when creating new records.
+#+ATTR_TEXINFO: :options ebdb-default-record-class
+#+begin_defopt
+The default record class to use when creating new records. Defaults
+to ~ebdb-record-person~.
+#+end_defopt
-Alternately create a record using "C" (~ebdb-create-extended~), which
-will prompt for a record class to use, as well as a database to store
-the record in, if there is more than one.
+#+FINDEX: ebdb-create-record-extended
+#+KINDEX: C
+Alternately create a record using {{{kbd(C)}}}
+(~ebdb-create-record-extended~), which will prompt for a record class to use,
+as well as a database to store the record in, if there is more than
+one.
You can also tell EBDB which record represents you:
-- User Option: ebdb-record-self
-
- The value of this option should be the UUID of your own record. You
- can find this by pressing "T" (to show all fields) on your record.
+#+ATTR_TEXINFO: :options ebdb-record-self
+#+begin_defopt
+The value of this option should be the UUID of your own record. You
+can find this by pressing {{{kbd(T)}}} (to show all fields) on your
+record.
+#+end_defopt
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
(~ebdb-record-person~) and organizations (~ebdb-record-organization~).
-Records can have "roles" at organizations
[[id:1398bd78-b380-4f36-ab05-44ea5ca8632f][Role Fields]].
+Records can have "roles" at organizations,
[[id:1398bd78-b380-4f36-ab05-44ea5ca8632f][Role Fields]].
** 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
@@ -185,30 +214,42 @@ class is labeled "alt name".
:END:
** Inserting New Fields
#+CINDEX: Inserting new 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 below for more information about the various kinds of fields.
+#+KINDEX: i
+#+FINDEX: ebdb-insert-field
+Pressing {{{kbd(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 below 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
-current data prompt; the second "C-g" will cancel the creation of the
-field altogether. For instance, when creating address fields, EBDB
-will allow you to create an arbitrary number of street lines. When
-you've added enough, either enter a blank string, or hit "C-g".
+blank string, or by pressing {{{kbd(C-g)}}}. The first {{{kbd(C-g)}}}
+will cancel the current data prompt; the second {{{kbd(C-g)}}} will
+cancel the creation of the field altogether. For instance, when
+creating address fields, EBDB will allow you to create an arbitrary
+number of street lines. When you've added enough, either enter a
+blank string, or hit {{{kbd(C-g)}}}.
** Editing Existing Fields
#+CINDEX: Editing fields
-Pressing "e" (~ebdb-edit-field~) with point on a field will allow you
-to edit an existing field, with the previous values as defaults.
-
-Alternately, press "E" (~ebdb-edit-field-customize~) to edit the
-field's values using the Customize interface. Some fields have slots
-that can only be edited this way; other fields have slots that cannot
-be edited at all once the field is created.
+#+KINDEX: e
+#+FINDEX: ebdb-edit-field
+Pressing {{{kbd(e)}}} (~ebdb-edit-field~) with point on a field will
+allow you to edit an existing field, with the previous values as
+defaults.
+
+#+KINDEX: E
+#+FINDEX: ebdb-edit-field-customize
+Alternately, press {{{kbd(E)}}} (~ebdb-edit-field-customize~) to edit
+the field's values using the Customize interface. Some fields have
+slots that can only be edited this way; other fields have slots that
+cannot be edited at all once the field is created.
** Deleting Records and Fields
-#+CINDEX: Deleting records and fields
-Pressing "C-k" on a field will ask you for confirmation, then delete
-the field. Pressing "C-k" while point is on or before a record's main
-name will instead prompt to delete the whole record.
+#+CINDEX: Deleting records
+#+CINDEX: Deleting fields
+#+KINDEX: C-k
+#+FINDEX: ebdb-delete-record-or-field
+Pressing {{{kbd(C-k)}}} on a field will ask you for confirmation, then
+delete the field. Pressing {{{kbd(C-k)}}} while point is on or before
+a record's main name will instead prompt to delete the whole record.
** Field Types
:PROPERTIES:
:ID: cb2190f4-f2e6-4082-9671-24e11e5cc0c6
@@ -216,34 +257,40 @@ name will instead prompt to delete the whole record.
Fields can be classed in a few different categories. Some are
"plumbing" fields, that are present for all records, but not generally
visible or user-editable: these include the creation date, timestamp,
-and UUID. You can view these fields by hitting "T" on the record.
-Other fields are "built-in": basic fields that get special treatment.
-These include the name, mail, phone, address, and notes fields. EBDB
-comes with default classes for these fields: if you would like to use
-different defaults, you can create new classes (inheriting from the
-existing ones) and use those instead. See
[[id:a58993a8-0631-459f-8bd6-7155bb6df605][Hacking EBDB]] for more
-information.
+and UUID. You can view these fields by hitting {{{kbd(T)}}} on the
+record. Other fields are "built-in": basic fields that get special
+treatment. These include the name, mail, phone, address, and notes
+fields. EBDB comes with default classes for these fields: if you
+would like to use different defaults, you can create new classes
+(inheriting from the existing ones) and use those instead. See
+[[id:a58993a8-0631-459f-8bd6-7155bb6df605][Hacking EBDB]] for more information.
Besides the "plumbing" and "built-in" fields, all other fields are
-"user" fields, and belong to one of two types: ~ebdb-field-user~ and
-~ebdb-field-user-simple~. The former is an abstract class, used to
-build fields with more complicated structures. The latter represents
-a simple field with a string label and a string value, and no special
-behavior.
-
-When adding fields to a record, EBDB offers up all the known labels of
-the simple user field class as possible choices. Typing in an unknown
-string will define a new label, which will be offered as a choice in
-the future.
-
-Fields built from ~ebdb-field-user~ will have their own string name.
-EBDB comes with classes including "anniversary", "url", "id",
-"relation", "role" and more. Many of these fields have their own list
-of labels (for instance, anniversary fields may be labeled "birthday",
-"wedding", etc).
+referred to as "user" fields. These can hold any kind of information
+you want to associate with a record. Some user fields are simple
+string keys and string values; others have more complicated data
+structures and behavior.
+
+When adding a field to a record, you'll be prompted for a field type.
+The list will include the built-in fields, more complicated field
+types, and also all the simple string keys you've defined so far. If
+you enter a string key that EBDB hasn't seen before, it will prompt
+for confirmation, then define that key for future use.
+
+EBDB comes with more complicated classes including "anniversary",
+"url", "id", "relation", "role" and more. Many of these fields have
+their own list of labels: for instance, anniversary fields may be
+labeled "birthday" or "wedding", and URL fields might be labeled
+"homepage" or "file-sharing".
+
+In the case of fields with labels, you'll first choose the general
+field ("anniversary") and then be prompted to choose the label
+("birthday"). Again, if you choose a label that hasn't been seen
+before, EBDB will first prompt for confirmation, then define the label
+for future use.
Loading secondary libraries may make more field types available.
-*** Role Fields
+*** Role fields
:PROPERTIES:
:ID: 1398bd78-b380-4f36-ab05-44ea5ca8632f
:END:
@@ -252,13 +299,13 @@ EBDB records come in two types at present: person and
organization.
People have roles at organizations: jobs, volunteer positions, etc.
People are also likely to have roles at more than one organization.
-When adding a role field to a record, you'll be prompted to choose the
-relevant organization role, prompted for a string label denoting
-eg.@@texinfo:@:@@ a job title, and prompted for a mail address that
-belongs only to this role field (ie.@@texinfo:@:@@ an institutional
-email address). If the organization has a "domain" field type, and
-the person has an existing mail address that matches that domain,
-you'll be prompted to move that address to the role field.
+When adding a role field to a record, you'll be prompted for a string
+label denoting eg.@@texinfo:@:@@ a job title, prompted for an
+organization, and prompted for a mail address that belongs only to
+this role field (ie.@@texinfo:@:@@ an institutional email address).
+If the organization has a "domain" field type, and the person has an
+existing mail address that matches that domain, you'll be prompted to
+move that address to the role field.
When viewing organization records, the role fields for all related
person records are also displayed as part of the organization record.
@@ -266,7 +313,7 @@ person records are also displayed as part of the
organization record.
If a person's role at an organization later comes to an end, the role
field can be deleted, or marked as "defunct", if record keeping is
desired. This can only be done using the customize-based editing
-interface (the "E" key on the role field).
+interface (the {{{kbd(E)}}} key on the role field).
In fact, in addition to a mail field, role fields can contain an
arbitrary number of other fields, representing metadata about the role
@@ -277,7 +324,24 @@ Suggestions are very welcome.
Manipulating role fields is generally a little clunky, at present.
This will be addressed in future.
-
+*** Tag field
+:PROPERTIES:
+:ID: d9073bc7-8731-4919-9fc0-7d1dcf98426e
+:END:
+EBDB comes with a field holding arbitrary tags for records. When
+searching on the tags field (using {{{kbd(/ x)}}} and selecting
+"tags"), EBDB provides the same tag search syntax as Org does,
+eg.@@texinfo:@:@@ "work|laptop+night". @@texinfo:@xref{Matching
+tags and properties,,,org}@@ for more information.
+
+The @@texinfo:@file{@@ebdb-org@@texinfo:}@@ library comes with another
+tagging class, ~ebdb-org-field-tags~, that behaves just like the
+standard class, except the user's Org-file tags are offered for
+completion. [[id:ee6b5ccb-a7a6-4c42-84a5-9eb0bbdc040f][Org Integration]].
+*** Mail folder field
+The "mail folder" field is used to indicate which folder or group
+incoming mail from the contact should be filed into. Currently only
+Gnus supports this; support in other MUAs is forthcoming.
* MUA Interaction
One of EBDB's most important features is the ability to create, update
and display records based on messages received or sent in your mail
@@ -299,9 +363,11 @@ mail, and Message for sending it, you'll want two require
statements:
There are other packages that provide other MUA integration: these 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.
+mu4e, and rmail.
** Display and Updating
+#+CINDEX: MUA Display
+#+CINDEX: MUA Updating
When a message is opened in an MUA, EBDB can do certain things with
the records referenced in that message. It can:
@@ -314,19 +380,19 @@ the records referenced in that message. It can:
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 {{{buf(EBDB-Gnus)}}} or {{{(buf(EBDB-Rmail)}}}. 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.
-
-- User Option: 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 below).
-
-At present, there are *no* user customization options controlling the
+Each MUA creates its own EBDB pop-up buffer, with a name like
+{{{buf(EBDB-Gnus)}}} or {{{buf(EBDB-Rmail)}}}. 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.
+
+#+ATTR_TEXINFO: :options ebdb-mua-pop-up
+#+begin_defopt
+If nil, MUAs will not automatically pop up buffers. It is still
+possible to manually create the buffer using interactive commands (see
+below).
+#+end_defopt
+
+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.
@@ -335,83 +401,95 @@ 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:
-- User Option: 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 '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.
+#+ATTR_TEXINFO: :options ebdb-mua-auto-update-p
+#+begin_defopt
+This option determines how EBDB acts upon mail addresses found in
+incoming messages. If nil, nothing will happen. Other options
+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.
+#+end_defopt
This option only governs what EBDB does automatically, each time a
message is displayed. The same process can be run interactively using
the commands below. When updating records either automatically or
interactively, a few more options come into play:
-- User Option: ebdb-add-name
-
- Whether to automatically change record names. See docstring for
- details.
-
-- User Option: ebdb-add-aka
-
- Whether to automatically add new names as akas. See docstring for
- details.
+#+ATTR_TEXINFO: :options ebdb-add-name
+#+begin_defopt
+Whether to automatically change record names. See docstring for
+details.
+#+end_defopt
-- User Option: ebdb-add-mails
+#+ATTR_TEXINFO: :options ebdb-add-aka
+#+begin_defopt
+Whether to automatically add new names as akas. See docstring for
+details.
+#+end_defopt
- How to handle apparently new mail addresses. See docstring for
- details.
+#+ATTR_TEXINFO: :options ebdb-add-mails
+#+begin_defopt
+How to handle apparently new mail addresses. See docstring for
+details.
+#+end_defopt
There are also options governing whether EBDB will consider a mail
address or not:
-- User Option: ebdb-accept-header-alist
-
- An alist governing which addresses in which headers will be
- accepted. See docstring for details.
-
-- User Option: ebdb-ignore-header-alist
-
- An alist governing which addresses in which headers will be ignored.
- See docstring for details.
-
-- User Option: ebdb-user-mail-address-re
-
- A regular expression matching the user's own mail address(es). In
- addition to a regexp, this can also be the symbol 'message, in which
- case the value will be copied from ~message-alternative-emails~, or
- the symbol 'self, in which case the value will be constructed from
- the record pointed to by the option ~ebdb-record-self~.
+#+ATTR_TEXINFO: :options ebdb-accept-header-list
+#+begin_defopt
+An alist governing which addresses in which headers will be accepted.
+See docstring for details.
+#+end_defopt
+
+#+ATTR_TEXINFO: :options ebdb-ignore-header-list
+#+begin_defopt
+An alist governing which addresses in which headers will be ignored.
+See docstring for details.
+#+end_defopt
+
+#+ATTR_TEXINFO: :options ebdb-user-name-address-re
+#+begin_defopt
+A regular expression matching the user's own mail address(es). In
+addition to a regexp, this can also be the symbol ~message~, in which
+case the value will be copied from ~message-alternative-emails~, or
+the symbol ~self~, in which case the value will be constructed from
+the record pointed to by the option ~ebdb-record-self~.
+#+end_defopt
*** Noticing and Automatic Rules
+#+CINDEX: 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.
-
+#+ATTR_TEXINFO: :options ebdb-notice-record-hook
+#+begin_defopt
+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.
+#+end_defopt
+
+#+ATTR_TEXINFO: :options ebdb-notice-mail-hook
+#+begin_defopt
+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.
+#+end_defopt
+
+#+FINDEX: ebdb-notice-field
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][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.
+a bit of familiarity with @@texinfo:@ref{Generic
+Functions,,,elisp}@@; 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:
@@ -423,60 +501,75 @@ keymap, and binds it to the key ";". The following list
assumes this
binding, and only specifies the further binding. Ie, 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.
-
-- Command: ebdb-mua-yank-cc
-
- Prompt for an existing {{{buf(EBDB)}}} buffer, and add addresses for
- all the records displayed there to the CC: line of the message being
- composed. This command is not bound by default, because the EBDB
- keymap is not bound by default in message composition MUAs.
-
-Other 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.
+#+attr_texinfo: :indic @kbd
+- : ::
+
+ #+KINDEX: :
+ #+FINDEX: ebdb-mua-update-records
+ If the option ~ebdb-mua-auto-update-p~ is nil, this command
+ (~ebdb-mua-update-records~) can be used to do the same thing, and
+ will behave as if that option were set to ~query~.
+
+- ; ::
+
+ #+KINDEX: ;
+ #+FINDEX: ebdb-mua-display-all-records
+ If the option ~ebdb-mua-pop-up~ is nil, this command can be used
+ to do the same thing (~ebdb-mua-display-all-records~).
+
+- ' ::
+
+ #+KINDEX: '
+ #+FINDEX: ebdb-mua-edit-sender-notes
+ Edit the notes field of the message sender
+ (~ebdb-mua-edit-sender-notes~).
+
+- @@texinfo:@quotedblright{}@@ ::
+
+ #+KINDEX: "
+ #+FINDEX: 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
+ {{{kbd(q)}}} will move point back to the previously-selected
+ window, rather than quitting the EBDB buffer.
+
+- s ::
+
+ #+KINDEX: s
+ #+FINDEX: 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.
+
+Other command are not bound by default:
+
+#+attr_texinfo: :options Command ebdb-mua-yank-cc
+#+begin_deffn
+Prompt for an existing {{{buf(EBDB)}}} buffer, and add addresses for
+all the records displayed there to the "CC:" line of the message being
+composed. This command is not bound by default, because the EBDB
+keymap is not bound by default in message composition MUAs.
+#+end_deffn
+
+#+attr_texinfo: :options Command ebdb-mua-display-sender
+#+begin_deffn
+Only display the sender.
+#+end_deffn
+
+#+attr_texinfo: :options Command ebdb-mua-display-recipients
+#+begin_deffn
+Only display the recipients.
+#+end_deffn
+
+#+attr_texinfo: :options Command ebdb-mua-display-all-recipients
+#+begin_deffn
+Only display recipients, using all mail addresses from the message.
+#+end_deffn
** EBDB and MUA summary buffers
@@ -488,61 +581,64 @@ 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. This only works for Gnus and
-VM, which allow for overriding how message senders are displayed. The
+name with information from the database. This only works for Gnus,
+which allows 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
-
- A function used to clean up the name extracted from the headers of a
- message.
-
-- User Option: ebdb-message-mail-as-name
-
- If non-nil, the mail address will be used as a fallback for new
- record names.
-
-- User Option: ebdb-mua-summary-unification-list
-
- A list of fields used by ~ebdb-mua-summary-unify~ to return a value
- for unification. See docstring for details.
-
-- 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".
+~gnus-summary-line-format~ for Gnus (which see).
+
+#+attr_texinfo: :options ebdb-message-clean-name-function
+#+begin_defopt
+A function used to clean up the name extracted from the headers of a
+message.
+#+end_defopt
+
+#+attr_texinfo: :options ebdb-message-mail-as-name
+#+BEGIN_defopt
+If non-nil, the mail address will be used as a fallback for new record
+names.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-mua-summary-unification-list
+#+BEGIN_defopt
+A list of fields used by ~ebdb-mua-summary-unify~ to return a value
+for unification. See docstring for details.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-mua-summary-unify-format-letter
+#+BEGIN_defopt
+Format letter to use for the EBDB-unified sender name in a Gnus
+summary buffer. Defaults to "E".
+#+END_defopt
*** Summary buffer marks
EBDB can display a one-character mark next to the name of senders that
-are in the database -- at present this is only possible in the Gnus
+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:
-- 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
-
- This generic function accepts RECORD as a single argument, and
- returns a single-character string to be used as a mark.
+#+attr_texinfo: :options ebdb-mua-summary-mark
+#+BEGIN_defopt
+Set to a single-character string to use for all senders in the EBDB
+database. Set to nil to not mark senders at all.
+#+END_defopt
-- Field class: ebdb-field-summary-mark
+#+attr_texinfo: :options ebdb-record ebdb-mua-make-summary-mark record
+#+BEGIN_defmethod
+This generic function accepts @@texinfo:@var{record}@@ as a single
+argument, and returns a single-character string to be used as a mark.
+#+END_defmethod
- Give a record an instance of this field class to use a
- specific mark for that record.
+Alternately, give a record an instance of the "summary mark" field
+class to use that specific mark for that record.
Marks are displayed in MUA summary buffers by customizing the format
-string provided by Gnus or VM, and adding the EBDB-specific format
-code:
+string provided by Gnus, and adding the EBDB-specific format code:
-- 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".
+#+attr_texinfo: :options ebdb-mua-summary-mark-format-letter
+#+BEGIN_defopt
+Format letter to use in the summary buffer format string to mark a
+record. Defaults to "e".
+#+END_defopt
* EBDB Buffers
:PROPERTIES:
:ID: 877ca77a-06d6-4fbf-87ec-614d03c37e30
@@ -555,213 +651,300 @@ that won't be interfered with by MUA pop-up action.
Calling the
also possible to create more by using the ~ebdb-clone-buffer~ and
~ebdb-rename-buffer~ commands within existing EBDB buffers.
-- User Option: ebdb-buffer-name
-
- The base string that is used to create EBDB buffers, without
- asterisks. Defaults to "EBDB".
+#+attr_texinfo: :options ebdb-buffer-name
+#+BEGIN_defopt
+The base string that is used to create EBDB buffers, without
+asterisks. Defaults to "EBDB".
+#+END_defopt
-- Key: b c, ebdb-clone-buffer
+#+attr_texinfo: :indic @kbd
+- b c ::
- Prompt for a buffer name, and create a new EBDB buffer displaying
- the same records as the original buffer.
+ #+KINDEX: b c
+ #+FINDEX: ebdb-clone-buffer
+ Prompt for a buffer name, and create a new EBDB buffer displaying
+ the same records as the original buffer (~ebdb-clone-buffer~).
-- Key: b r, ebdb-rename-buffer
+- b r ::
- Rename the current EBDB buffer. If this is done in a MUA pop-up
- buffer, the original buffer will be recreated next time the MUA
- requests another pop up.
+ #+KINDEX: b r
+ #+FINDEX: ebdb-rename-buffer
+ Rename the current EBDB buffer (~ebdb-rename-buffer~). If this
+ is done in a MUA pop-up buffer, the original buffer will be
+ recreated next time the MUA requests another pop up.
** Searching
#+CINDEX: Searching the EBDB
-The most general search is performed with "/ /", which searches on
-many different record fields and displays the results.
+#+KINDEX: / /
+The most general search is performed with {{{kbd(/ /)}}}, which
+searches on many different record fields and displays the results.
The EBDB major mode provides many keys for searching on specific
record fields. Most of these keys are used after one of three prefix
-keys, which change the behavior of the search: "/" clears the buffer
-before displaying the results, "|" searches only among the records
-already displayed, and "+" appends the search results to the records
-already displayed.
-
-For instance, record name search is on the key "n", meaning you can
-use "/ n", "| n", or "+ n". Search keys that work this way are:
-
-- "n": Search names
-- "o": Search organizations
-- "p": Search phones
-- "a": Search addresses
-- "m": Search mails
-- "x": Search user fields (prompts for which field to search on)
-- "c": Search records that have been modified since last save
-- "C": Search by record class
-- "D": Prompt for a database and display all records belonging to that
+keys, which change the behavior of the search: {{{kbd(/)}}} clears the
+buffer before displaying the results, {{{kbd(|)}}} searches only among
+the records already displayed, and {{{kbd(+)}}} appends the search
+results to the records already displayed.
+
+For instance, record name search is on the key {{{kbd(n)}}}, meaning
+you can use {{{kbd(/ n)}}}, {{{kbd(| n)}}}, or {{{kbd(+ n)}}}.
+Search keys that work this way are:
+
+#+attr_texinfo: :indic @kbd
+- n :: Search names
+- o :: Search organizations
+- p :: Search phones
+- a :: Search addresses
+- m :: Search mails
+- x :: Search user fields (prompts for which field to search on)
+- c :: Search records that have been modified since last save
+- C :: Search by record class
+- D :: Prompt for a database and display all records belonging to that
database
-Search commands that currently only work with the "/" prefix are:
+Search commands that currently only work with the {{{kbd(/)}}} prefix
+are:
-- "/ 1": Prompt for a single record, and display it
-- "/ d": Search duplicate records
+#+attr_texinfo: :indic @kbd
+- / 1 :: Prompt for a single record, and display it
+- / d :: Search duplicate records
+#+CINDEX: Inverting searches
Searches can be inverted:
-- Key: !, ebdb-search-invert
-
- Invert the results of the next search.
+#+attr_texinfo: :indic @kbd
+- ! ::
+ #+KINDEX: !
+ #+FINDEX: ebdb-search-invert
+ Invert the results of the next search (~ebdb-search-invert~).
+#+CINDEX: Search history
Each user-created {{{buf(EBDB)}}} buffer keeps track of search history
in that buffer. To pop back to previous searches, use:
-- Key: ^, ebdb-search-pop
+#+attr_texinfo: :indic @kbd
+- ^ ::
+ #+KINDEX: ^
+ #+FINDEX: ebdb-search-pop
+ ~ebdb-search-pop~
*** Changing Search Behavior
-
+#+CINDEX: Customizing search
There are three ways to alter the behavior of EBDB searches.
-- User Option: ebdb-case-fold-search
-
- An equivalent to the regular ~case-fold-search~ variable, which
- see. Defaults to the value of that variable.
-
-- User Option: ebdb-char-fold-search
-
- Controls whether character folding is used when matching search
- strings against record values.
-
-- User Option: ebdb-search-transform-functions
-
- A list of functions that can be used to arbitrarily transform search
- strings. Each function should accept a single string argument, and
- return the transformed string. If the search criterion is not a
- string (some fields produce sexp search criteria) these functions
- will not be used.
+#+attr_texinfo: :options ebdb-case-fold-search
+#+BEGIN_defopt
+An equivalent to the regular ~case-fold-search~ variable, which
+see. Defaults to the value of that variable.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-char-fold-search
+#+BEGIN_defopt
+Controls whether character folding is used when matching search
+strings against record values.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-search-transform-functions
+#+BEGIN_defopt
+A list of functions that can be used to arbitrarily transform search
+strings. Each function should accept a single string argument, and
+return the transformed string. If the search criterion is not a
+string (some fields produce sexp search criteria) these functions
+will not be used.
+#+END_defopt
Be careful of potential interaction between character folding and
transform functions. Character folding works by calling
~char-fold-to-regexp~ on the search string, effectively replacing
foldable characters within the string using regular expressions. This
-process happens /after/ the transform functions have run, so there is
+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
+#+attr_texinfo: :indic @kbd
+- n ::
- Move point to the next record.
+ #+KINDEX: n
+ #+FINDEX: ebdb-next-record
+ Move point to the next record (~ebdb-next-record~).
-- Key: p, ebdb-prev-record
+- p ::
- Move point to the previous record.
+ #+KINDEX: p
+ #+FINDEX: ebdb-prev-record
+ Move point to the previous record (~ebdb-prev-record~).
-- Key: N, ebdb-next-field
+- N ::
- Move point to the next field.
+ #+KINDEX: N
+ #+FINDEX: ebdb-next-field
+ Move point to the next field (~ebdb-next-field~).
-- Key: P, ebdb-prev-field
+- P ::
- Move point to the previous field.
+ #+KINDEX: P
+ #+FINDEX: ebdb-prev-field
+ Move point to the previous field (~ebdb-prev-field~).
-- Key: c, ebdb-create-record
+- c ::
- Create a new person record in the primary database.
+ #+KINDEX: c
+ #+FINDEX: ebdb-create-record
+ Create a new person record in the primary database
+ (~ebdb-create-record~).
-- Key: C, ebdb-create-record-extended
+- C ::
- Prompt for database and record class, then create a new record.
+ #+KINDEX: C
+ #+FINDEX: ebdb-create-record-extended
+ Prompt for database and record class, then create a new record
+ (~ebdb-create-record-extended~).
-- Key: i, ebdb-insert-field
+- i ::
- Insert a new field into the record under point, or the marked records.
+ #+KINDEX: i
+ #+FINDEX: ebdb-insert-field
+ Insert a new field into the record under point, or the marked
+ records (~ebdb-insert-field~).
-- Key: e, ebdb-edit-field
+- e ::
- Edit the field under point.
+ #+KINDEX: e
+ #+FINDEX: ebdb-edit-field
+ Edit the field under point (~ebdb-edit-field~).
-- Key: E, ebdb-edit-field-customize
+- E ::
- Use the extended customize interface to edit the field under point.
+ #+KINDEX: E
+ #+FINDEX: ebdb-edit-field-customize
+ Use the extended customize interface to edit the field under
+ point (~ebdb-edit-field-customize~).
-- 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.
+ #+KINDEX: ;
+ #+FINDEX: ebdb-edit-foo
+ Either insert/edit the record's notes field or, with a prefix
+ arg, prompt for an existing field and edit it (~ebdb-edit-foo~).
-- Key: C-k, ebdb-delete-field-or-record
+- C-k ::
- With point on a record field, offer to delete that field. With
- point on a record header, offer to delete the whole record.
+ #+KINDEX: C-k
+ #+FINDEX: 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. (~ebdb-delete-field-or-record~)
-- Key: RET, ebdb-record-action
+- @@texinfo:@address@hidden@@ ::
- 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
+ #+KINDEX: RET
+ #+FINDEX: ebdb-record-action
+ #+CINDEX: Field actions
+ Run an "action" on the field under point
+ (~ebdb-record-action~). If multiple actions are provided, you'll
+ be prompted to choose one. Not all fields provide actions.
+ {{{kbd(@key{RET})}}} on a mail field will compose a message to
+ that mail address
-- Key: m, ebdb-mail
+- m ::
- 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.
+ #+KINDEX: m
+ #+FINDEX: ebdb-mail
+ Begin composing a message to the record under point
+ (~ebdb-mail~). With a prefix arg, prompt for the mail address to
+ use; otherwise use the record's primary address.
-- Key: t, ebdb-toggle-records-format
+- t ::
- Toggle between a multi-line and one-line display.
+ #+KINDEX: t
+ #+FINDEX: ebdb-toggle-records-format
+ Toggle between a multi-line and one-line display
+ (~ebdb-toggle-records-format~).
-- Key: T, ebdb-display-records-completely
+- T ::
- Display all of a record's fields.
+ #+KINDEX: T
+ #+FINDEX: ebdb-display-records-completely
+ Display all of a record's fields
+ (~ebdb-display-records-completely~).
-- Key: r, ebdb-reformat-records
+- r ::
- Redisplay the record under point.
+ #+KINDEX: r
+ #+FINDEX: ebdb-reformat-records
+ Redisplay the record under point (~ebdb-reformat-records~).
-- Key: o, ebdb-omit-records
+- o ::
- Remove the record under point (or marked records) from the buffer
- (does not delete the records).
+ #+KINDEX: o
+ #+FINDEX: ebdb-omit-records
+ Remove the record under point (or marked records) from the buffer
+ (does not delete the records) (~ebdb-omit-records~).
-- Key: I, ebdb-cite-records-ebdb
+- I ::
- Put a "citation" for the record under point (or marked records) onto
- the kill ring. A "citation" is a name-and-mail string for the
- record. Prompt for a style, meaning a textual mode. With a prefix
- arg, arrange citations in a list, otherwise inline.
+ #+KINDEX: I
+ #+FINDEX: ebdb-cite-records-ebdb
+ Put a "citation" for the record under point (or marked records)
+ onto the kill ring (~ebdb-cite-records-ebdb~). A "citation" is a
+ name-and-mail string for the record. Prompt for a style, meaning
+ a textual mode. With a prefix arg, arrange citations in a list,
+ otherwise inline.
-- Key: w f, ebdb-copy-fields-as-kill
+- w f ::
- Copy the string value of the field under point to the kill ring.
+ #+KINDEX: w f
+ #+FINDEX: ebdb-copy-fields-as-kill
-- Key: w r, ebdb-copy-records-as-kill
+ Copy the string value of the field under point to the kill ring
+ (~ebdb-copy-fields-as-kill~).
- Copy a string representation of the whole record under point to the
- kill ring.
+- w r ::
-- Key: w m, ebdb-copy-mail-as-kill
+ #+KINDEX: w r
+ #+FINDEX: ebdb-copy-records-as-kill
+ Copy a string representation of the whole record under point to
+ the kill ring (~ebdb-copy-records-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.
+- w m ::
-- Key: g, revert-buffer
+ #+KINDEX: w m
+ #+FINDEX: ebdb-copy-mail-as-kill
+ Copy a name-plus-mail string citation for the record under point
+ to the kill ring (~ebdb-copy-mail-as-kill~). 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.
- Redisplay all visible records.
+- g ::
-- Key: ?, ebdb-help
+ #+KINDEX: g
+ #+FINDEX: revert-buffer
+ Redisplay all visible records (~revert-buffer~).
- Show a very brief help message.
+- ? ::
-- Key: h, ebdb-info
+ #+KINDEX: ?
+ #+FINDEX: ebdb-help
+ Show a very brief help message (~ebdb-help~).
- Open this manual.
+- h ::
-- Key: s, ebdb-save
+ #+KINDEX: h
+ #+FINDEX: ebdb-info
+ Open this manual (~ebdb-info~).
- Save all databases.
+- s ::
-- Key: q, quit-window
+ #+KINDEX: s
+ #+FINDEX: ebdb-save
+ Save all databases (~ebdb-save~).
- Delete the {{{buf(EBDB)}}} window.
+- q ::
+
+ #+KINDEX: q
+ #+FINDEX: quit-window
+ Delete the {{{buf(EBDB)}}} window (~quit-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.
@@ -770,11 +953,11 @@ field manipulation.
:PROPERTIES:
:ID: 73462a5d-2ec7-4a83-8b38-f5be8e62b376
:END:
-Records can be marked and acted on in bulk. The "#" key will toggle
-the mark of the record under point. "M-#" will toggle the marks of
-all the records in the buffer, and "C-#" will unmark all records in
-the buffer. Many editing commands can act on multiple marked
-records.
+Records can be marked and acted on in bulk. The {{{kbd(#)}}} key will
+toggle the mark of the record under point. {{{kbd(M-#)}}} will toggle
+the marks of all the records in the buffer, and {{{kbd(C-#)}}} unmarks
+all records in the buffer. Many editing commands can act on multiple
+marked records.
** Exporting/Formatting
:PROPERTIES:
:ID: 0f72cc06-99e4-45b1-aa32-14e909f0765e
@@ -787,34 +970,40 @@ At present, the only other supported format is VCard, and
support is
imperfect: not all fields can be exported correctly. VCard version
2.1 is unsupported: the only options are version 3.0 and 4.0.
-- Key: f, ebdb-format-to-tmp-buffer
+#+attr_texinfo: :indic @kbd
+- f ::
- This command prompts for a formatter, and formats the record under
- point to a temporary buffer. Use
[[id:73462a5d-2ec7-4a83-8b38-f5be8e62b376][marking]] to format multiple
- records.
+ #+KINDEX: f
+ #+FINDEX: ebdb-format-to-tmp-buffer
+ This command prompts for a formatter, and formats the record
+ under point to a temporary buffer (~ebdb-format-to-tmp-buffer~).
+ Use [[id:73462a5d-2ec7-4a83-8b38-f5be8e62b376][marking]] to format
multiple records.
-- Key: F, ebdb-format-all-records
+- F ::
- Export all records in the database (not only those displayed) to a
- different format.
+ #+KINDEX: F
+ #+FINDEX: ebdb-format-all-records
+ Export all records in the database (not only those displayed) to
+ a different format (~ebdb-format-all-records~).
It's possible to write new formatters, documentation is forthcoming.
* Completion
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.
+exist providing EBDB support for helm, counsel, and company. These
+libraries must be loaded from the package repositories, and 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,
@@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~.
+it for {{{kbd(@key{TAB})}}} in ~message-mode~ by calling
+~ebdb-complete-enable~.
-Several native EBDB commands involve selecting a record, or multiple
+Several native EBDB commands involve choosing 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
@@ -831,38 +1020,42 @@ new one, and then display that contact.
Snarfing is a work in progress: at present, only mail addresses, URLs
and nearby names are acted upon, and it often doesn't work correctly.
-- Command: ebdb-snarf &optional string start end recs
-
- Extract record-related information from a piece of text. Find,
- update, or create records as necessary, and then display them. When
- the region is active, this command snarfs the current region,
- otherwise it snarfs the entire current buffer. Called as a
- function, it can accept a string as the first argument and snarfs
- that. The RECS argument, which cannot be passed interactively, is a
- list of records that are assumed to be related to snarfable data in
- STRING.
-
-- User Option: ebdb-snarf-routines
-
- An alist of field class symbols and related regexps. The regexps
- are used to collect text that is likely parseable by the
- ~ebdb-parse~ method of the field class.
-
-- User Option: ebdb-snarf-name-re
-
- A list of regular expressions used to recognize names for a snarfed
- contact. Searching names directly is mostly impossible, so names
- are only looked for in close proximity to other field data.
-
+#+attr_texinfo: :options Command ebdb-snarf &optional string start end recs
+#+BEGIN_deffn
+Extract record-related information from a piece of text. Find,
+update, or create records as necessary, and then display them. When
+the region is active, this command snarfs the current region,
+otherwise it snarfs the entire current buffer. Called as a function,
+it can accept a string as the first argument and snarfs that. The
+RECS argument, which cannot be passed interactively, is a list of
+records that are assumed to be related to snarfable data in STRING.
+#+END_deffn
+
+#+attr_texinfo: :options ebdb-snarf-routines
+#+BEGIN_defopt
+An alist of field class symbols and related regexps. The regexps are
+used to collect text that is likely parseable by the ~ebdb-parse~
+method of the field class.
+#+END_defopt
+
+#+attr_texinfo: :options ebdb-snarf-name-re
+#+BEGIN_defopt
+A list of regular expressions used to recognize names for a snarfed
+contact. Searching names directly is mostly impossible, so names are
+only looked for in close proximity to other field data.
+#+END_defopt
+
+#+CINDEX: Article snarfing
In MUAs, EBDB can also snarf the body of the article being displayed.
This is separate from the updating process, which only examines the
article headers.
-- Command: ebdb-mua-snarf-article
-
- Snarf the body of the current article. This will also snarf the
- headers of forwarded emails, and the signature. With a prefix
- argument, only snarf the signature.
+#+attr_texinfo: :options Command ebdb-mua-snarf-article &optional arg
+#+BEGIN_defopt
+Snarf the body of the current article. This will also snarf the
+headers of forwarded emails, and the signature. With a prefix
+argument, only snarf the signature.
+#+END_defopt
* Internationalization
#+CINDEX: Internationalization
EBDB comes with an internationalization framework that can provide
@@ -895,9 +1088,9 @@ Internationalization libraries do not modify the database,
and can be
safely unloaded. They simply alter the way EBDB reads, parses and
displays field values, and can also store extra information
(eg.@@texinfo:@:@@ 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.
+Loading internationalization libraries may slow down initial database
+loading, though they should not significantly impact search or display
+performance.
Actually, the internationalization library does alter database storage
in one way: address countries can be either stored as a string
@@ -910,12 +1103,13 @@ internationalization library is loaded or not.
Country names are displayed in English by default, but users can alter
the display of some country names if they choose.
-#+TEXINFO: @defopt ebdb-i18n-countries-pref-scripts
+#+ATTR_TEXINFO: :options ebdb-i18n-countries-pref-scripts
+#+BEGIN_defopt
This is an alist of conses pairing string country names to symbol
-labels---see the value of ~ebdb-i18n-countries~ for how to use it, and
-to find the correct symbol label. Values set in this option will
-shadow the values in the variable.
-#+TEXINFO: @end defopt
+labels---see the value of ~ebdb-i18n-countries~ for the correct
+format, and to find the correct symbol label. Values set in this
+option will shadow the values in the variable.
+#+end_defopt
* Diary Integration
#+CINDEX: Diary integration
@@ -926,13 +1120,14 @@ information with Emacs' diary package (and from there to
Org, via the
an actual diary file present at the location indicated by
~diary-file~, though the file can be blank.
-- User Option: ebdb-use-diary
-
- If non-nil, EBDB fields with date information will attempt to add
- that information to the diary.
+#+ATTR_TEXINFO: :options ebdb-use-diary
+#+BEGIN_defopt
+If non-nil, EBDB fields with date information will attempt to add that
+information to the diary.
+#+END_defopt
-When viewing the calendar, you can use the "d" key to see diary
-information for that day.
+When viewing the calendar, you can use the {{{kbd(d)}}} key to see
+diary information for that day.
Support for this feature is rudimentary. More customization options
are forthcoming.
@@ -942,13 +1137,13 @@ You can give records a mail alias with the "mail alias"
field,
available in the list of choices for inserting new fields. You'll be
prompted for an alias, and an email address to use for the alias, if
the record has more than one. If multiple records have the same
-alias, then entering that alias in the To: or Cc: field of a message
-composition buffer will expand to a comma-separated list of record
-addresses.
+alias, then entering that alias in the "To:" or "Cc:" field of a
+message composition buffer will expand to a comma-separated list of
+record addresses.
At present, it's necessary to manually parse existing aliases with the
-"A" key in a {{{buf(EBDB)}}} buffer. This limitation will be removed
-in the future.
+{{{kbd(A)}}} key in a {{{buf(EBDB)}}} buffer. This limitation will be
+removed in the future.
* vCard Support
EBDB has rudimentary support for exporting to vCard format; this
functionality will be expanded in the future. After loading the
@@ -959,50 +1154,68 @@ 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.
* Org Integration
+:PROPERTIES:
+:ID: ee6b5ccb-a7a6-4c42-84a5-9eb0bbdc040f
+:END:
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 {{{buf(EBDB)}}} buffer and display the linked record.
+EBDB records works as expected with {{{kbd(C-c l)}}}, and following a
+link will open an {{{buf(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
+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 "ebdb:phone/206", and to create a link to all records who work at
-Google, use "ebdb:mail/google.com".
+are of the format "ebdb:<field type>/<search string>". The
+@@texinfo:@samp{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
+@@texinfo:@samp{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 "ebdb:phone/206", and to create a link
+to all records who work at Google, use "ebdb:mail/google.com".
The @@texinfo:@file{@@ebdb-org@@texinfo:}@@ 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 {{{buf(EBDB)}}} buffer alongside an
-Org agenda buffer, etc.
+[[id:d9073bc7-8731-4919-9fc0-7d1dcf98426e][Tag Field]].
+
+This library comes with one other function that allows you to pop up
+an {{{buf(EBDB)}}} buffer alongside an Org Agenda buffer.
+
+#+attr_texinfo: :options Command ebdb-org-agenda-popup
+#+BEGIN_deffn
+Pop up an EBDB buffer displaying contacts matching the tags used to
+create the Agenda buffer. Only does anything in a tags search Agenda
+buffer.
+#+END_deffn
+
+This function could also be added to the ~org-agenda-mode-hook~, to
+pop up a buffer any time relevant records are found.
* 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.
+#+attr_texinfo: :options Command ebdb-cite-records
+#+BEGIN_deffn
+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.
+#+END_deffn
* Hacking EBDB
:PROPERTIES:
:ID: a58993a8-0631-459f-8bd6-7155bb6df605
:END:
EBDB is designed to be highly extensible. In addition to the usual
customization options, it provides for subclassing of the three main
-classes -- database, record, and field. The behavior of EBDB can be
+classes: database, record, and field. The behavior of EBDB can be
radically changed by creating new classes, or overriding the existing
methods of classes, without touching the original source code. This
manual won't go into details about Emacs' object-orientation support:
@@ -1012,36 +1225,42 @@ for information on writing generic functions and
methods.
The simplest customization involves changing the default classes used
for basic record and field types.
-- User Option: ebdb-default-record-class
-
- The default class used for creating records. This class will be
- used when creating records with "c" in ebdb-mode, or when
- automatically creating records (ie, from snarfing). It's always
- possible to create a record of a different class by using "C" in
- ebdb-mode.
-
-- User Option: ebdb-default-name-class
-
- The default class for complex names. Simple names (used for
- organizations and nicknames) are always plain strings -- this option
- only governs the class used for articulated names of individuals,
- with separate slots for surname, given names, suffixes, etc.
-
-- User Option: ebdb-default-mail-class
-
- The default class for mail fields.
-
-- User Option: ebdb-default-phone-class
-
- The default class for phone fields.
-
-- User Option: ebdb-default-address-class
-
- The default class for address fields.
-
-- User Option: ebdb-default-notes-class
-
- The default class for notes fields.
+#+ATTR_TEXINFO: :options ebdb-default-record-class
+#+BEGIN_defopt
+The default class used for creating records. This class will be used
+when creating records with {{{kbd(c)}}} in ebdb-mode, or when
+automatically creating records (ie, from snarfing). It's always
+possible to create a record of a different class by using {{{kbd(C)}}}
+in ebdb-mode.
+#+END_defopt
+
+#+ATTR_TEXINFO: :options ebdb-default-record-class
+#+BEGIN_defopt
+The default class for complex names. Simple names (used for
+organizations and nicknames) are always plain strings---this option
+only governs the class used for articulated names of individuals, with
+separate slots for surname, given names, suffixes, etc.
+#+END_defopt
+
+#+ATTR_TEXINFO: :options ebdb-default-mail-class
+#+BEGIN_defopt
+The default class for mail fields.
+#+END_defopt
+
+#+ATTR_TEXINFO: :options ebdb-default-phone-class
+#+BEGIN_defopt
+The default class for phone fields.
+#+END_defopt
+
+#+ATTR_TEXINFO: :options ebdb-default-address-class
+#+BEGIN_defopt
+The default class for address fields.
+#+END_defopt
+
+#+ATTR_TEXINFO: :options ebdb-default-notes-class
+#+BEGIN_defopt
+The default class for notes fields.
+#+END_defopt
If, for instance, you'd like to create a custom mail field and have
all records use that instead of the built-in one:
@@ -1089,10 +1308,10 @@ instance. The simplest field types only need to
provide these three
methods.
The ~ebdb-read~ and ~ebdb-parse~ methods are static (class-level)
-methods. Both take an optional "slots" argument, which a plist of
+methods. Both take an optional ~slots~ argument, which a plist of
slot values that will eventually be fed to ~make-instance~. If values
-are already present in the plist, these methods should /not/ override
-them. In addition, ~ebdb-read~ takes an optional "obj" argument,
+are already present in the plist, these methods should _not_ override
+them. In addition, ~ebdb-read~ takes an optional ~obj~ argument,
which, if present, is an existing field instance that can be used to
provide default values for the new object.
@@ -1123,11 +1342,19 @@ It's also very common to define ~ebdb-init-field~ and
maintain secondary data structures, or set up extra hashing for
records, or do any other supplemental work. The one restriction is
that they must not change the database: they may not edit records or
-their fields. Both methods are called with the field instance as the
-first argument, and the record the instance belongs to as an optional
-second argument. ~ebdb-delete-field~ also accepts an optional third
-argument, "unload", which is non-nil when the record is being
-unloaded, rather than deleted.
+their fields.
+
+#+attr_texinfo: :options Method ebdb-init-field field record
+#+BEGIN_deffn
+Initialize @@texinfo:@var{field}@@ against @@texinfo:@var{record}@@.
+#+END_deffn
+
+#+attr_texinfo: :options Method ebdb-delete-field field &optional record unload
+#+BEGIN_deffn
+Delete @@texinfo:@var{field}@@ of record @@texinfo:@var{record}@@. If
+the optional argument @@texinfo:@var{unload}@@ is non-nil, it means
+the record is only being unloaded
+#+END_deffn
Both methods should always end with a call to ~cl-call-next-method~.
@@ -1146,7 +1373,7 @@ Both methods should always end with a call to
~cl-call-next-method~.
3. When editing an existing field instance (editing is a
delete-and-create operation).
4. When unloading a record from the database (the optional third
- "unload" argument will be non-nil).
+ @@texinfo:@var{unload}@@ argument will be non-nil).
*** The Labeled Field Class
Many field classes maintain their own list of labels: ie, anniversary
fields can be labeled "birthday", "wedding", etc. This functionality
@@ -1162,13 +1389,20 @@ used to hold labels, and pointing to it in the
class-allocated
(defclass my-labeled-field (ebdb-field-user ebdb-field-labeled)
((label-list :initform my-field-label-list)))
#+END_SRC
+*** The Singleton Field Class
+Another abstract mix-in class is the ~ebdb-field-singleton~ class.
+It's only function is to ensure that a record only ever has one
+instance of the class in question. If the user tries to add a second
+instance, the existing instance is deleted.
*** Actions
+#+CINDEX: Field actions
All field classes have a class-allocated slot called "actions". The
value of this slot is a list of conses, for instance: ~("Browse URL"
. ebdb-field-url-browse)~. Users can trigger these actions by
-pressing "RET" while point is on the field in the {{{buf(EBDB)}}}
-buffer, using a numeric prefix arg to select from multiple possible
-actions, or the 0 prefix arg to be prompted for which action to take.
+pressing {{{kbd(@key{RET})}}}" while point is on the field in the
+{{{buf(EBDB)}}} buffer, using a numeric prefix arg to select from
+multiple possible actions, or the 0 prefix arg to be prompted for
+which action to take.
The functions in this list should accept two arguments, the record and
the field instance under point.
@@ -1185,12 +1419,14 @@ chosen, it has the option to prompt for more complex
search criteria.
This is done by overriding two matching methods: ~ebdb-search-read~,
and ~ebdb-field-search~.
+#+FINDEX: ebdb-search-read
~ebdb-search-read~ is a static (class-level) method. Its only
argument is the field class being searched on. It should prompt the
user for whatever search criterion it wants, then return that
criterion. This can be nearly anything, so long as the matching
~ebdb-field-search~ can accept it.
+#+FINDEX: ebdb-field-search
The ~ebdb-field-search~ method accepts a field instance as the first
argument, and the search criterion as the second. It should return
non-nil if the criterion somehow matches the field. Note that it's
@@ -1202,13 +1438,41 @@ search criterion as a cons: ~("label string"
. other-search-criteria)~. The label string will first be matched
against the label of the instance, and then other-search-criteria will
be passed to the ~ebdb-field-search~ method as usual.
+
+That might sound a bit confusing, here's an example. These are the
+search methods for the ~ebdb-field-tags~ class.
+
+#+BEGIN_SRC emacs-lisp
+(cl-defmethod ebdb-search-read ((_class (subclass ebdb-field-tags)))
+ (cdr
+ (org-make-tags-matcher
+ (ebdb-read-string
+ "Search for tags (eg +tag1-tag2|tag3): "))))
+
+(cl-defmethod ebdb-field-search ((field ebdb-field-tags)
+ func)
+ (when (functionp func)
+ (funcall func t (slot-value field 'tags) 1)))
+
+(cl-defmethod ebdb-field-search ((field ebdb-field-tags)
+ (tag string))
+ (seq-find (lambda (tg) (string-match-p tag tg))
+ (slot-value field 'tags)))
+#+END_SRC
+
+The ~ebdb-search-read~ method returns a lambda (the ~cdr~ of the
+return value of ~org-make-tags-matcher~. The first
+~ebdb-field-search~ method handles that lambda, simply by calling it.
+The second ~ebdb-field-search~ method handles a string search
+criterion; though no EBDB code would create this search, external code
+conceivably might.
*** Formatting in the EBDB Buffer
-Most fields will be displayed in the {{{buf(EBDB)}}} buffer simply using
-~ebdb-string~. It's possible to customize this display by overriding
-the ~ebdb-fmt-field~ method. Without going into too much detail, this
-method dispatches on four arguments: the formatter, the field, a
-"style" symbol argument (typically 'normal, 'oneline, 'compact',
-'collapse or 'expanded), and the record being formatted.
+Most fields will be displayed in the {{{buf(EBDB)}}} buffer simply
+using ~ebdb-string~. It's possible to customize this display by
+overriding the ~ebdb-fmt-field~ method. Without going into too much
+detail, this method dispatches on four arguments: the formatter, the
+field, a "style" symbol argument (typically ~normal~, ~oneline~,
+~compact~, ~collapse~ or ~expanded~), and the record being formatted.
Specify an ebdb formatter for the first argument to target
{{{buf(EBDB)}}} formatting. Choices are ~ebdb-formatter-ebdb~ (for
@@ -1216,15 +1480,16 @@ all cases), or one of ~ebdb-formatter-ebdb-multiline~ or
~ebdb-formatter-ebdb-oneline~. Keep in mind that many field classes
are not displayed at all in the oneline format.
-An example: most fields are output with style set to 'normal, meaning
+An example: most fields are output with style set to ~normal~, meaning
that it will use the value of ~ebdb-string~. By default, formatters
-display address fields in the 'collapse style, which is mapped to the
-'oneline style, which simply drops everything after the first newline.
+display address fields in the ~collapse~ style, which is mapped to the
+~oneline~ style, which simply drops everything after the first
+newline.
Say you still wanted addresses output on a single line, but you wanted
to provide a little more information on that line: the first line of
the street addresses, plus the city, plus the country. You could
-achieve that by overriding the 'collapse style like so:
+achieve that by overriding the ~collapse~ style like so:
#+BEGIN_SRC emacs-lisp
(cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter)
@@ -1287,7 +1552,7 @@ able to specialize on. Every country-specific method
should check the
spec to see if it is relevant to that library. If so, it handles the
necessary behavior; if not, it passes by using ~cl-call-next-method~.
See the function signatures of each internationalized method to find
-how to handle the extra argument, called SPEC.
+how to handle the extra argument, called @@texinfo:@var{spec}@@.
Here's a concrete example:
@@ -1295,8 +1560,8 @@ Say we want to make sure all French phone numbers are
represented by a
string that looks like "+33 05 12 34 56 79". This is not how they are
stored in the database, but this is how they should be represented to
the user. We need to override the ~ebdb-string-i18n~ method for the
-phone field class. This method takes two arguments -- the field
-instance, and the country-code spec -- and needs to specialize on both
+phone field class. This method takes two arguments---the field
+instance, and the country-code spec---and needs to specialize on both
arguments. The method signature will look like this:
#+BEGIN_SRC emacs-lisp
@@ -1307,10 +1572,10 @@ arguments. The method signature will look like this:
See the manual on generic functions for details; suffice it to say
that this method will only run when the first argument is an instance
of the ~ebdb-field-phone~ class (or a subclass), and the second
-argument is the number 33.
+argument is ~eql~ to the number 33.
-Now we know that this method will only run for French phone numbers,
-so we can format the number correctly:
+We know that this method will only run for French phone numbers, so we
+can format the number correctly:
#+BEGIN_SRC emacs-lisp
(cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
@@ -1343,6 +1608,7 @@ 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.
+#+FINDEX: ebdb-mua-auto-update
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
@@ -1354,6 +1620,7 @@ generic functions. All MUA-specific generic functions
specialize on
the current major-mode, using the ~&context~ specializer. See below
for examples.
+#+FINDEX: ebdb-mua-message-header
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
@@ -1367,7 +1634,6 @@ return the contents of the appropriate header. For
instance, in Gnus:
"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
@@ -1382,32 +1648,39 @@ 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.
+#+attr_texinfo: :options Method ebdb-mua-prepare-article
+#+BEGIN_deffn
+Called with no argument but the mode specializer, this function
+should do whatever is necessary to prepare the article.
+#+END_deffn
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.
-
+#+attr_texinfo: :options Method ebdb-make-buffer-name
+#+BEGIN_deffn
+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)~.
+#+END_deffn
+
+#+attr_texinfo: :options Method ebdb-popup-window
+#+BEGIN_deffn
+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.
+#+END_deffn
+
+#+VINDEX: ebdb-mua-keymap
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
-
+#+CINDEX: 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
@@ -1416,11 +1689,15 @@ 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.
+#+attr_texinfo: :options Method ebdb-mua-article-body
+#+BEGIN_deffn
+Return the text of the article body, or nil.
+#+END_deffn
-- Function: ebdb-mua-article-signature
- Return the text of the article signature, or nil.
+#+attr_texinfo: :options Method ebdb-mua-article-signature
+#+BEGIN_deffn
+Return the text of the article signature, or nil.
+#+END_deffn
* Index
:PROPERTIES:
:INDEX: cp
diff --git a/ebdb.texi b/ebdb.texi
index e8df91f..69b3aa1 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -4,7 +4,9 @@
@settitle EBDB Manual
@documentencoding UTF-8
@documentlanguage en
address@hidden pg cp
address@hidden vr cp
address@hidden fn cp
address@hidden ky cp
@c %**end of header
@copying
@@ -94,7 +96,9 @@ Record Fields
Field Types
-* Role Fields::
+* Role fields::
+* Tag field::
+* Mail folder field::
MUA Interaction
@@ -145,6 +149,7 @@ Field Classes
* Init and Delete Methods::
* The Labeled Field Class::
+* The Singleton Field Class::
* Actions::
* Custom Field Searching::
* Formatting in the EBDB Buffer::
@@ -211,126 +216,120 @@ stores its contacts in the same file as the database
itself, though
other database classes may store contacts elsewhere.
@cindex Creating a database
address@hidden Databases
@defopt ebdb-sources
-
User option specifying one or more databases to load. It can be a
single element, or a list of elements. Each element can be a
-filename, from which a database is loaded, or it can be an instance
-of a subclass of the @code{ebdb-db} class. The database at the head of
-the list will be considered the default database.
+filename, from which a database is loaded, or it can be an instance of
+a subclass of the @code{ebdb-db} class. The database at the head of the
+list will be considered the default database.
@end defopt
Databases have a few user-facing settings:
address@hidden read-only
-
-If t, records can only be read from the database, not edited or
address@hidden Database @code{boolean} read-only
+If non-nil, records can only be read from the database, not edited or
deleted.
address@hidden defopt
-
address@hidden auto-save
-
-Set to nil to prevent auto-saving of the database's records.
address@hidden defopt
address@hidden deftypeivar
address@hidden buffer-char
address@hidden Database @code{boolean} auto-save
+If non-nil, the database's records will not be autosaved.
address@hidden deftypeivar
-Set to a single character that will be displayed next to records in
-the *EBDB* buffer, indicating which database they belong
-to.
address@hidden defopt
-
address@hidden disabled
address@hidden Database @code{character} buffer-char
+A single character that will be displayed next to records in the
+*EBDB* buffer, indicating which database they belong to.
address@hidden deftypeivar
-When t, the database will essentially be ignored -- no records will
-be read from it. Setting this to t will only take effect on next
address@hidden Database @code{boolean} disabled
+When non-nil , the database will essentially be ignored---no records
+will be read from it. Setting this to t will only take effect on next
restart; to disable a database immediately, use
@code{ebdb-disable-database} below.
address@hidden defopt
-
address@hidden record-class
address@hidden deftypeivar
address@hidden Database @code{symbol} record-class
The default record class to use when creating new records in this
database. The default is @code{ebdb-default-record-class}.
address@hidden defopt
address@hidden deftypeivar
While it's possible to edit database definitions directly in the file,
it's safer to use the customization interface to do so from the
*EBDB* buffer.
address@hidden @asis
address@hidden @kbd
address@hidden d e
@kindex d e
address@hidden ebdb-customize-database db
address@hidden @kbd{d e}
@address@hidden@address@hidden(@code{ebdb-customize-database db})
-
-Use the customize interface to edit the definition of DB.
+Use the customize interface to edit the definition of a database
+(@code{ebdb-customize-database}).
@end table
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''
+than one database, the two copies are compared using the timestamp
field, and the older copy is discarded. In an *EBDB* buffer,
-the following keys can be used to manipulate databases and their records.
+the following keys can be used to manipulate databases and their
+records.
address@hidden @asis
address@hidden @kbd
address@hidden d m
@kindex d m
address@hidden ebdb-move-record record to-db
address@hidden @kbd{d m} @address@hidden@address@hidden(@code{ebdb-move-record
record to-db})
-
-Move RECORD from its existing database to TO-DB.
+Move a record from its current database to another
+(@code{ebdb-move-record}).
address@hidden d c
@kindex d c
address@hidden ebdb-copy-record record to-db
address@hidden @kbd{d c} @address@hidden@address@hidden(@code{ebdb-copy-record
record to-db})
-
-Copy RECORD into TO-DB, leaving it in its existing database(s).
+ Copy a record into a new database, leaving it in its existing
+database(s) (@code{ebdb-copy-record}).
@end table
Other database-related commands:
address@hidden @asis
address@hidden @kbd
address@hidden d r
@kindex d r
address@hidden ebdb-reload-database db
address@hidden @kbd{d r}
@address@hidden@address@hidden(@code{ebdb-reload-database db})
-
Reload all records from a database. This also redisplays any of
-those records that were visible in *EBDB* buffers.
+those records that were visible in *EBDB* buffers
+(@code{ebdb-reload-database}).
address@hidden d d
@kindex d d
address@hidden ebdb-disable-database db
address@hidden @kbd{d d}
@address@hidden@address@hidden(@code{ebdb-disable-database db})
-
-This command disables a database, unloading all of its records and
-essentially ignoring it from now on. The disabled state persists
-between restarts. To re-enable a database, edit it using
address@hidden, set 'disabled to nil, and then reload it
-with @code{ebdb-reload-database}.
+This command (@code{ebdb-disable-database}) disables a database,
+unloading all of its records and essentially ignoring it from now
+on. The disabled state persists between restarts. To re-enable
+a database, edit it using @code{ebdb-customize-database}, set
address@hidden to nil, and then reload it with @code{ebdb-reload-database}.
@end table
@node Creating Records
@chapter Creating Records
@cindex Creating records
-Create a record using ``c'' (@code{ebdb-create}) in the *EBDB* buffer.
-With no prefix arg, this command will create an instance of the
address@hidden c
address@hidden ebdb-create-record
+Create a record using @kbd{c} (@code{ebdb-create-record}) in the
+*EBDB* buffer. This command will create an instance of the
default record class, in the database at the head of @code{ebdb-sources}.
@defopt ebdb-default-record-class
-
-The default record class to use when creating new records.
+The default record class to use when creating new records. Defaults
+to @code{ebdb-record-person}.
@end defopt
-Alternately create a record using ``C'' (@code{ebdb-create-extended}), which
-will prompt for a record class to use, as well as a database to store
-the record in, if there is more than one.
address@hidden ebdb-create-record-extended
address@hidden C
+Alternately create a record using @kbd{C}
+(@code{ebdb-create-record-extended}), which will prompt for a record class to
use,
+as well as a database to store the record in, if there is more than
+one.
You can also tell EBDB which record represents you:
@defopt ebdb-record-self
-
The value of this option should be the UUID of your own record. You
-can find this by pressing ``T'' (to show all fields) on your record.
+can find this by pressing @kbd{T} (to show all fields) on your
+record.
@end defopt
Currently this option's only use is to serve as a source for
@@ -346,7 +345,7 @@ Currently this option's only use is to serve as a source for
EBDB comes with two record classes, representing individuals
(@code{ebdb-record-person}) and organizations
(@code{ebdb-record-organization}).
-Records can have ``roles'' at organizations @ref{Role Fields}.
+Records can have ``roles'' at organizations, @ref{Role fields, , Role Fields}.
@node Record names
@section Record names
@@ -376,36 +375,48 @@ class is labeled ``alt name''.
@section Inserting New Fields
@cindex Inserting new fields
-Pressing ``i'' (@code{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 below for more information about the various kinds of fields.
address@hidden i
address@hidden ebdb-insert-field
+Pressing @kbd{i} (@code{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 below 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
-current data prompt; the second ``C-g'' will cancel the creation of the
-field altogether. For instance, when creating address fields, EBDB
-will allow you to create an arbitrary number of street lines. When
-you've added enough, either enter a blank string, or hit ``C-g''.
+blank string, or by pressing @kbd{C-g}. The first @kbd{C-g}
+will cancel the current data prompt; the second @kbd{C-g} will
+cancel the creation of the field altogether. For instance, when
+creating address fields, EBDB will allow you to create an arbitrary
+number of street lines. When you've added enough, either enter a
+blank string, or hit @kbd{C-g}.
@node Editing Existing Fields
@section Editing Existing Fields
@cindex Editing fields
-Pressing ``e'' (@code{ebdb-edit-field}) with point on a field will allow you
-to edit an existing field, with the previous values as defaults.
address@hidden e
address@hidden ebdb-edit-field
+Pressing @kbd{e} (@code{ebdb-edit-field}) with point on a field will
+allow you to edit an existing field, with the previous values as
+defaults.
-Alternately, press ``E'' (@code{ebdb-edit-field-customize}) to edit the
-field's values using the Customize interface. Some fields have slots
-that can only be edited this way; other fields have slots that cannot
-be edited at all once the field is created.
address@hidden E
address@hidden ebdb-edit-field-customize
+Alternately, press @kbd{E} (@code{ebdb-edit-field-customize}) to edit
+the field's values using the Customize interface. Some fields have
+slots that can only be edited this way; other fields have slots that
+cannot be edited at all once the field is created.
@node Deleting Records and Fields
@section Deleting Records and Fields
address@hidden Deleting records and fields
-Pressing ``C-k'' on a field will ask you for confirmation, then delete
-the field. Pressing ``C-k'' while point is on or before a record's main
-name will instead prompt to delete the whole record.
address@hidden Deleting records
address@hidden Deleting fields
address@hidden C-k
address@hidden ebdb-delete-record-or-field
+Pressing @kbd{C-k} on a field will ask you for confirmation, then
+delete the field. Pressing @kbd{C-k} while point is on or before
+a record's main name will instead prompt to delete the whole record.
@node Field Types
@section Field Types
@@ -413,53 +424,61 @@ name will instead prompt to delete the whole record.
Fields can be classed in a few different categories. Some are
``plumbing'' fields, that are present for all records, but not generally
visible or user-editable: these include the creation date, timestamp,
-and UUID. You can view these fields by hitting ``T'' on the record.
-Other fields are ``built-in'': basic fields that get special treatment.
-These include the name, mail, phone, address, and notes fields. EBDB
-comes with default classes for these fields: if you would like to use
-different defaults, you can create new classes (inheriting from the
-existing ones) and use those instead. See @ref{Hacking EBDB} for more
-information.
+and UUID. You can view these fields by hitting @kbd{T} on the
+record. Other fields are ``built-in'': basic fields that get special
+treatment. These include the name, mail, phone, address, and notes
+fields. EBDB comes with default classes for these fields: if you
+would like to use different defaults, you can create new classes
+(inheriting from the existing ones) and use those instead. See
address@hidden EBDB} for more information.
Besides the ``plumbing'' and ``built-in'' fields, all other fields are
-``user'' fields, and belong to one of two types: @code{ebdb-field-user} and
address@hidden The former is an abstract class, used to
-build fields with more complicated structures. The latter represents
-a simple field with a string label and a string value, and no special
-behavior.
-
-When adding fields to a record, EBDB offers up all the known labels of
-the simple user field class as possible choices. Typing in an unknown
-string will define a new label, which will be offered as a choice in
-the future.
-
-Fields built from @code{ebdb-field-user} will have their own string name.
-EBDB comes with classes including ``anniversary'', ``url'', ``id'',
-``relation'', ``role'' and more. Many of these fields have their own list
-of labels (for instance, anniversary fields may be labeled ``birthday'',
-``wedding'', etc).
+referred to as ``user'' fields. These can hold any kind of information
+you want to associate with a record. Some user fields are simple
+string keys and string values; others have more complicated data
+structures and behavior.
+
+When adding a field to a record, you'll be prompted for a field type.
+The list will include the built-in fields, more complicated field
+types, and also all the simple string keys you've defined so far. If
+you enter a string key that EBDB hasn't seen before, it will prompt
+for confirmation, then define that key for future use.
+
+EBDB comes with more complicated classes including ``anniversary'',
+``url'', ``id'', ``relation'', ``role'' and more. Many of these fields have
+their own list of labels: for instance, anniversary fields may be
+labeled ``birthday'' or ``wedding'', and URL fields might be labeled
+``homepage'' or ``file-sharing''.
+
+In the case of fields with labels, you'll first choose the general
+field (``anniversary'') and then be prompted to choose the label
+(``birthday''). Again, if you choose a label that hasn't been seen
+before, EBDB will first prompt for confirmation, then define the label
+for future use.
Loading secondary libraries may make more field types available.
@menu
-* Role Fields::
+* Role fields::
+* Tag field::
+* Mail folder field::
@end menu
address@hidden Role Fields
address@hidden Role Fields
address@hidden Role fields
address@hidden Role fields
One type of field worth mentioning in particular is the role field.
EBDB records come in two types at present: person and organization.
People have roles at organizations: jobs, volunteer positions, etc.
People are also likely to have roles at more than one organization.
-When adding a role field to a record, you'll be prompted to choose the
-relevant organization role, prompted for a string label denoting
-eg.@: a job title, and prompted for a mail address that
-belongs only to this role field (ie.@: an institutional
-email address). If the organization has a ``domain'' field type, and
-the person has an existing mail address that matches that domain,
-you'll be prompted to move that address to the role field.
+When adding a role field to a record, you'll be prompted for a string
+label denoting eg.@: a job title, prompted for an
+organization, and prompted for a mail address that belongs only to
+this role field (ie.@: an institutional email address).
+If the organization has a ``domain'' field type, and the person has an
+existing mail address that matches that domain, you'll be prompted to
+move that address to the role field.
When viewing organization records, the role fields for all related
person records are also displayed as part of the organization record.
@@ -467,7 +486,7 @@ person records are also displayed as part of the
organization record.
If a person's role at an organization later comes to an end, the role
field can be deleted, or marked as ``defunct'', if record keeping is
desired. This can only be done using the customize-based editing
-interface (the ``E'' key on the role field).
+interface (the @kbd{E} key on the role field).
In fact, in addition to a mail field, role fields can contain an
arbitrary number of other fields, representing metadata about the role
@@ -479,6 +498,27 @@ Suggestions are very welcome.
Manipulating role fields is generally a little clunky, at present.
This will be addressed in future.
address@hidden Tag field
address@hidden Tag field
+
+EBDB comes with a field holding arbitrary tags for records. When
+searching on the tags field (using @kbd{/ x} and selecting
+``tags''), EBDB provides the same tag search syntax as Org does,
+eg.@: ``work|laptop+night''. @xref{Matching
+tags and properties,,,org} for more information.
+
+The @file{ebdb-org} library comes with another
+tagging class, @code{ebdb-org-field-tags}, that behaves just like the
+standard class, except the user's Org-file tags are offered for
+completion. @ref{Org Integration}.
+
address@hidden Mail folder field
address@hidden Mail folder field
+
+The ``mail folder'' field is used to indicate which folder or group
+incoming mail from the contact should be filed into. Currently only
+Gnus supports this; support in other MUAs is forthcoming.
+
@node MUA Interaction
@chapter MUA Interaction
@@ -510,25 +550,24 @@ mail, and Message for sending it, you'll want two require
statements:
There are other packages that provide other MUA integration: these 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.
+mu4e, and rmail.
@node Display and Updating
@section Display and Updating
address@hidden MUA Display
address@hidden MUA Updating
When a message is opened in an MUA, EBDB can do certain things with
the records referenced in that message. It can:
@itemize
@item
Pop up a buffer displaying the records.
-
@item
Create new records, or alter existing records, based on information
provided by the MUA.
-
@item
Run automatic rules to edit the records.
-
@item
Provide keybindings to manually edit the records.
@end itemize
@@ -546,20 +585,18 @@ independently of the others.
@node Pop-up Buffers
@subsection Pop-up Buffers
-Each MUA associated with EBDB creates its own pop-up buffer, with a
-name like *EBDB-Gnus* or @address@hidden@{(buf(EBDB-Rmail)@address@hidden@}.
MUAs will
-re-use their own buffers, and will not interfere with buffers the user
-has created using the @code{ebdb} command, or by cloning or renaming
-existing buffers.
+Each MUA creates its own EBDB pop-up buffer, with a name like
+*EBDB-Gnus* or *EBDB-Rmail*. MUAs will re-use their
+own buffers, and will not interfere with buffers the user has created
+using the @code{ebdb} command, or by cloning or renaming existing buffers.
@defopt 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 below).
+possible to manually create the buffer using interactive commands (see
+below).
@end defopt
-At present, there are *no* user customization options controlling the
+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.
@@ -572,14 +609,13 @@ based on information in an MUA message. The first and
most important
option governing this behavior is:
@defopt 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 '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
+include the symbols @code{update} (only find existing records, and update
+their name and mail fields as necessary), @code{query} (find existing
+records, and query about the editing and creation of new records), and
address@hidden (automatically create new records). A value of @code{t} is
+considered equivalent to @code{create}. The option can also be set to a
function which returns one of the above symbols.
@end defopt
@@ -589,19 +625,16 @@ the commands below. When updating records either
automatically or
interactively, a few more options come into play:
@defopt ebdb-add-name
-
Whether to automatically change record names. See docstring for
details.
@end defopt
@defopt ebdb-add-aka
-
Whether to automatically add new names as akas. See docstring for
details.
@end defopt
@defopt ebdb-add-mails
-
How to handle apparently new mail addresses. See docstring for
details.
@end defopt
@@ -609,55 +642,53 @@ details.
There are also options governing whether EBDB will consider a mail
address or not:
address@hidden ebdb-accept-header-alist
-
-An alist governing which addresses in which headers will be
-accepted. See docstring for details.
address@hidden ebdb-accept-header-list
+An alist governing which addresses in which headers will be accepted.
+See docstring for details.
@end defopt
address@hidden ebdb-ignore-header-alist
-
address@hidden ebdb-ignore-header-list
An alist governing which addresses in which headers will be ignored.
See docstring for details.
@end defopt
address@hidden ebdb-user-mail-address-re
-
address@hidden ebdb-user-name-address-re
A regular expression matching the user's own mail address(es). In
-addition to a regexp, this can also be the symbol 'message, in which
+addition to a regexp, this can also be the symbol @code{message}, in which
case the value will be copied from @code{message-alternative-emails}, or
-the symbol 'self, in which case the value will be constructed from
+the symbol @code{self}, in which case the value will be constructed from
the record pointed to by the option @code{ebdb-record-self}.
@end defopt
@node Noticing and Automatic Rules
@subsection Noticing and Automatic Rules
address@hidden 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:
@defopt 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
+record, and one of the symbols @code{sender} and @code{recipient}, indicating
where in the message headers the record was found.
@end defopt
@defopt 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.
+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.
@end defopt
address@hidden ebdb-notice-field
When a record is noticed, it will also call the method
@code{ebdb-notice-field} on all of its fields. Using this method requires
-a bit of familiarity with @ref{Generic%20Functions,Generic Functions,,elisp,};
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.
+a bit of familiarity with @ref{Generic
+Functions,,,elisp}; suffice it to say that the first argument is the
+field instance being noticed, the second argument is one of the
+symbols @code{sender} or @code{recipient}, and the third argument is the record
+being noticed.
@node Interactive Commands
@subsection Interactive Commands
@@ -668,79 +699,65 @@ keymap, and binds it to the key ``;''. The following
list assumes this
binding, and only specifies the further binding. Ie, press ``;:'' to
call @code{ebdb-mua-display-records}.
address@hidden @asis
address@hidden @kbd
address@hidden :
@kindex :
address@hidden ebdb-mua-update-records
address@hidden @kbd{:}
@address@hidden@address@hidden(@code{ebdb-mua-update-records})
-
-If the option @code{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.
address@hidden ebdb-mua-update-records
+If the option @code{ebdb-mua-auto-update-p} is nil, this command
+(@code{ebdb-mua-update-records}) can be used to do the same thing, and
+will behave as if that option were set to @code{query}.
address@hidden ;
@kindex ;
address@hidden ebdb-mua-display-all-records
address@hidden @kbd{;}
@address@hidden@address@hidden(@code{ebdb-mua-display-all-records})
-
-If the option @code{ebdb-mua-pop-up} is nil, this command can be used to
-do the same thing.
address@hidden ebdb-mua-display-all-records
+If the option @code{ebdb-mua-pop-up} is nil, this command can be used
+to do the same thing (@code{ebdb-mua-display-all-records}).
address@hidden '
@kindex '
address@hidden ebdb-mua-edit-sender-notes
address@hidden @kbd{'}
@address@hidden@address@hidden(@code{ebdb-mua-edit-sender-notes})
-
-This command allows you to edit the notes field of the message
-sender.
-
address@hidden ``
address@hidden ebdb-mua-in-ebdb-buffer
address@hidden @kbd{``}
@address@hidden@address@hidden(@code{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.
-
address@hidden ebdb-mua-edit-sender-notes
+Edit the notes field of the message sender
+(@code{ebdb-mua-edit-sender-notes}).
+
address@hidden @quotedblright{}
address@hidden "
address@hidden 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
address@hidden will move point back to the previously-selected
+window, rather than quitting the EBDB buffer.
+
address@hidden s
@kindex s
address@hidden ebdb-mua-snarf-article
address@hidden @kbd{s}
@address@hidden@address@hidden(@code{ebdb-mua-snarf-article})
-
address@hidden 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.
-
+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.
@end table
address@hidden ebdb-mua-yank-cc
address@hidden Command ebdb-mua-yank-cc
+Other command are not bound by default:
address@hidden Command ebdb-mua-yank-cc
Prompt for an existing *EBDB* buffer, and add addresses for
-all the records displayed there to the CC: line of the message being
+all the records displayed there to the ``CC:'' line of the message being
composed. This command is not bound by default, because the EBDB
keymap is not bound by default in message composition MUAs.
@end deffn
-Other commands that are not bound to any keys by default:
-
address@hidden ebdb-mua-display-sender
@deffn Command ebdb-mua-display-sender
-
Only display the sender.
@end deffn
address@hidden ebdb-mua-display-recipients
@deffn Command ebdb-mua-display-recipients
-
Only display the recipients.
@end deffn
address@hidden ebdb-mua-display-all-recipients
@deffn Command ebdb-mua-display-all-recipients
-
Only display recipients, using all mail addresses from the message.
@end deffn
@@ -763,70 +780,56 @@ 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. This only works for Gnus and
-VM, which allow for overriding how message senders are displayed. The
+name with information from the database. This only works for Gnus,
+which allows for overriding how message senders are displayed. The
format letter (see below) should be added to
address@hidden for Gnus (which see), and
address@hidden for VM (ditto).
address@hidden for Gnus (which see).
@defopt ebdb-message-clean-name-function
-
A function used to clean up the name extracted from the headers of a
message.
@end defopt
@defopt ebdb-message-mail-as-name
-
-If non-nil, the mail address will be used as a fallback for new
-record names.
+If non-nil, the mail address will be used as a fallback for new record
+names.
@end defopt
@defopt ebdb-mua-summary-unification-list
-
A list of fields used by @code{ebdb-mua-summary-unify} to return a value
for unification. See docstring for details.
@end defopt
@defopt 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''.
+Format letter to use for the EBDB-unified sender name in a Gnus
+summary buffer. Defaults to ``E''.
@end defopt
@node Summary buffer marks
@subsection Summary buffer marks
EBDB can display a one-character mark next to the name of senders that
-are in the database -- at present this is only possible in the Gnus
+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:
@defopt 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.
@end defopt
address@hidden ebdb-mua-make-summary-mark record
address@hidden ebdb-record ebdb-mua-make-summary-mark record
+This generic function accepts @var{record} as a single
+argument, and returns a single-character string to be used as a mark.
address@hidden defmethod
-This generic function accepts RECORD as a single argument, and
-returns a single-character string to be used as a mark.
address@hidden defun
-
address@hidden
address@hidden
-Field class: ebdb-field-summary-mark
-
-Give a record an instance of this field class to use a
-specific mark for that record.
address@hidden itemize
+Alternately, give a record an instance of the ``summary mark'' field
+class to use that specific mark for that record.
Marks are displayed in MUA summary buffers by customizing the format
-string provided by Gnus or VM, and adding the EBDB-specific format
-code:
+string provided by Gnus, and adding the EBDB-specific format code:
@defopt ebdb-mua-summary-mark-format-letter
-
Format letter to use in the summary buffer format string to mark a
record. Defaults to ``e''.
@end defopt
@@ -843,26 +846,23 @@ also possible to create more by using the
@code{ebdb-clone-buffer} and
@code{ebdb-rename-buffer} commands within existing EBDB buffers.
@defopt ebdb-buffer-name
-
The base string that is used to create EBDB buffers, without
asterisks. Defaults to ``EBDB''.
@end defopt
address@hidden @asis
address@hidden @kbd
address@hidden b c
@kindex b c
address@hidden ebdb-clone-buffer
address@hidden @kbd{b c}
@address@hidden@address@hidden(@code{ebdb-clone-buffer})
-
address@hidden ebdb-clone-buffer
Prompt for a buffer name, and create a new EBDB buffer displaying
-the same records as the original buffer.
+the same records as the original buffer (@code{ebdb-clone-buffer}).
address@hidden b r
@kindex b r
address@hidden ebdb-rename-buffer
address@hidden @kbd{b r}
@address@hidden@address@hidden(@code{ebdb-rename-buffer})
-
-Rename the current EBDB buffer. If this is done in a MUA pop-up
-buffer, the original buffer will be recreated next time the MUA
-requests another pop up.
address@hidden ebdb-rename-buffer
+Rename the current EBDB buffer (@code{ebdb-rename-buffer}). If this
+is done in a MUA pop-up buffer, the original buffer will be
+recreated next time the MUA requests another pop up.
@end table
@menu
@@ -876,76 +876,72 @@ requests another pop up.
@section Searching
@cindex Searching the EBDB
-The most general search is performed with ``/ /'', which searches on
-many different record fields and displays the results.
address@hidden / /
+The most general search is performed with @kbd{/ /}, which
+searches on many different record fields and displays the results.
The EBDB major mode provides many keys for searching on specific
record fields. Most of these keys are used after one of three prefix
-keys, which change the behavior of the search: ``/'' clears the buffer
-before displaying the results, ``|'' searches only among the records
-already displayed, and ``+'' appends the search results to the records
-already displayed.
-
-For instance, record name search is on the key ``n'', meaning you can
-use ``/ n'', ``| n'', or ``+ n''. Search keys that work this way are:
-
address@hidden
address@hidden
-``n'': Search names
-
address@hidden
-``o'': Search organizations
-
address@hidden
-``p'': Search phones
-
address@hidden
-``a'': Search addresses
-
address@hidden
-``m'': Search mails
-
address@hidden
-``x'': Search user fields (prompts for which field to search on)
-
address@hidden
-``c'': Search records that have been modified since last save
-
address@hidden
-``C'': Search by record class
-
address@hidden
-``D'': Prompt for a database and display all records belonging to that
+keys, which change the behavior of the search: @kbd{/} clears the
+buffer before displaying the results, @kbd{|} searches only among
+the records already displayed, and @kbd{+} appends the search
+results to the records already displayed.
+
+For instance, record name search is on the key @kbd{n}, meaning
+you can use @kbd{/ n}, @kbd{| n}, or @kbd{+ n}.
+Search keys that work this way are:
+
address@hidden @kbd
address@hidden n
+Search names
address@hidden o
+Search organizations
address@hidden p
+Search phones
address@hidden a
+Search addresses
address@hidden m
+Search mails
address@hidden x
+Search user fields (prompts for which field to search on)
address@hidden c
+Search records that have been modified since last save
address@hidden C
+Search by record class
address@hidden D
+Prompt for a database and display all records belonging to that
database
address@hidden itemize
-
-Search commands that currently only work with the ``/'' prefix are:
address@hidden table
address@hidden
address@hidden
-``/ 1'': Prompt for a single record, and display it
+Search commands that currently only work with the @kbd{/} prefix
+are:
address@hidden
-``/ d'': Search duplicate records
address@hidden itemize
address@hidden @kbd
address@hidden / 1
+Prompt for a single record, and display it
address@hidden / d
+Search duplicate records
address@hidden table
address@hidden Inverting searches
Searches can be inverted:
address@hidden @asis
address@hidden @kbd
address@hidden !
@kindex !
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 ebdb-search-invert
+Invert the results of the next search (@code{ebdb-search-invert}).
@end table
address@hidden Search history
Each user-created *EBDB* buffer keeps track of search history
in that buffer. To pop back to previous searches, use:
address@hidden @asis
address@hidden @kbd
address@hidden ^
@kindex ^
address@hidden ebdb-search-pop
address@hidden @kbd{^} @address@hidden@address@hidden(@code{ebdb-search-pop})
address@hidden ebdb-search-pop
address@hidden
@end table
@menu
@@ -955,22 +951,20 @@ in that buffer. To pop back to previous searches, use:
@node Changing Search Behavior
@subsection Changing Search Behavior
address@hidden Customizing search
There are three ways to alter the behavior of EBDB searches.
@defopt ebdb-case-fold-search
-
An equivalent to the regular @code{case-fold-search} variable, which
see. Defaults to the value of that variable.
@end defopt
@defopt ebdb-char-fold-search
-
Controls whether character folding is used when matching search
strings against record values.
@end defopt
@defopt ebdb-search-transform-functions
-
A list of functions that can be used to arbitrarily transform search
strings. Each function should accept a single string argument, and
return the transformed string. If the search criterion is not a
@@ -982,7 +976,7 @@ Be careful of potential interaction between character
folding and
transform functions. Character folding works by calling
@code{char-fold-to-regexp} on the search string, effectively replacing
foldable characters within the string using regular expressions. This
-process happens /after/ the transform functions have run, so there is
+process happens _after_ the transform functions have run, so there is
a possibility for unexpected search behavior.
@node The Basics of ebdb-mode
@@ -991,178 +985,164 @@ a possibility for unexpected search behavior.
EBDB buffers inherit from special-mode, and so the usual special-mode
keybindings apply.
address@hidden @asis
address@hidden @kbd
address@hidden n
@kindex 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 ebdb-next-record
+Move point to the next record (@code{ebdb-next-record}).
address@hidden p
@kindex 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 ebdb-prev-record
+Move point to the previous record (@code{ebdb-prev-record}).
address@hidden N
@kindex 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 ebdb-next-field
+Move point to the next field (@code{ebdb-next-field}).
address@hidden P
@kindex 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 ebdb-prev-field
+Move point to the previous field (@code{ebdb-prev-field}).
address@hidden c
@kindex 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 ebdb-create-record
+Create a new person record in the primary database
+(@code{ebdb-create-record}).
address@hidden C
@kindex 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 ebdb-create-record-extended
+Prompt for database and record class, then create a new record
+(@code{ebdb-create-record-extended}).
address@hidden i
@kindex 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 ebdb-insert-field
+Insert a new field into the record under point, or the marked
+records (@code{ebdb-insert-field}).
address@hidden e
@kindex 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 ebdb-edit-field
+Edit the field under point (@code{ebdb-edit-field}).
address@hidden E
@kindex 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 ebdb-edit-field-customize
+Use the extended customize interface to edit the field under
+point (@code{ebdb-edit-field-customize}).
address@hidden ;
@kindex ;
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 ebdb-edit-foo
+Either insert/edit the record's notes field or, with a prefix
+arg, prompt for an existing field and edit it (@code{ebdb-edit-foo}).
address@hidden C-k
@kindex C-k
address@hidden ebdb-delete-field-or-record
address@hidden @kbd{C-k}
@address@hidden@address@hidden(@code{ebdb-delete-field-or-record})
-
address@hidden 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.
+point on a record header, offer to delete the whole
+record. (@code{ebdb-delete-field-or-record})
address@hidden @address@hidden
@kindex 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 ebdb-record-action
address@hidden Field actions
+Run an ``action'' on the field under point
+(@code{ebdb-record-action}). If multiple actions are provided, you'll
+be prompted to choose one. Not all fields provide actions.
address@hidden@key{RET}} on a mail field will compose a message to
+that mail address
+
address@hidden m
@kindex 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 ebdb-mail
+Begin composing a message to the record under point
+(@code{ebdb-mail}). With a prefix arg, prompt for the mail address to
+use; otherwise use the record's primary address.
address@hidden t
@kindex 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 ebdb-toggle-records-format
+Toggle between a multi-line and one-line display
+(@code{ebdb-toggle-records-format}).
address@hidden T
@kindex 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 ebdb-display-records-completely
+Display all of a record's fields
+(@code{ebdb-display-records-completely}).
address@hidden r
@kindex 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 ebdb-reformat-records
+Redisplay the record under point (@code{ebdb-reformat-records}).
address@hidden o
@kindex o
address@hidden ebdb-omit-records
address@hidden @kbd{o} @address@hidden@address@hidden(@code{ebdb-omit-records})
-
address@hidden ebdb-omit-records
Remove the record under point (or marked records) from the buffer
-(does not delete the records).
+(does not delete the records) (@code{ebdb-omit-records}).
address@hidden I
@kindex I
address@hidden ebdb-cite-records-ebdb
address@hidden @kbd{I}
@address@hidden@address@hidden(@code{ebdb-cite-records-ebdb})
-
-Put a ``citation'' for the record under point (or marked records) onto
-the kill ring. A ``citation'' is a name-and-mail string for the
-record. Prompt for a style, meaning a textual mode. With a prefix
-arg, arrange citations in a list, otherwise inline.
-
address@hidden ebdb-cite-records-ebdb
+Put a ``citation'' for the record under point (or marked records)
+onto the kill ring (@code{ebdb-cite-records-ebdb}). A ``citation'' is a
+name-and-mail string for the record. Prompt for a style, meaning
+a textual mode. With a prefix arg, arrange citations in a list,
+otherwise inline.
+
address@hidden w f
@kindex w f
address@hidden ebdb-copy-fields-as-kill
address@hidden @kbd{w f}
@address@hidden@address@hidden(@code{ebdb-copy-fields-as-kill})
address@hidden ebdb-copy-fields-as-kill
-Copy the string value of the field under point to the kill ring.
+Copy the string value of the field under point to the kill ring
+(@code{ebdb-copy-fields-as-kill}).
address@hidden w r
@kindex 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 ebdb-copy-records-as-kill
+Copy a string representation of the whole record under point to
+the kill ring (@code{ebdb-copy-records-as-kill}).
address@hidden w m
@kindex 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 ebdb-copy-mail-as-kill
+Copy a name-plus-mail string citation for the record under point
+to the kill ring (@code{ebdb-copy-mail-as-kill}). 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
@kindex g
address@hidden revert-buffer
address@hidden @kbd{g} @address@hidden@address@hidden(@code{revert-buffer})
-
-Redisplay all visible records.
address@hidden revert-buffer
+Redisplay all visible records (@code{revert-buffer}).
address@hidden ?
@kindex ?
address@hidden ebdb-help
address@hidden @kbd{?} @address@hidden@address@hidden(@code{ebdb-help})
-
-Show a very brief help message.
address@hidden ebdb-help
+Show a very brief help message (@code{ebdb-help}).
address@hidden h
@kindex h
address@hidden ebdb-info
address@hidden @kbd{h} @address@hidden@address@hidden(@code{ebdb-info})
-
-Open this manual.
address@hidden ebdb-info
+Open this manual (@code{ebdb-info}).
address@hidden s
@kindex s
address@hidden ebdb-save
address@hidden @kbd{s} @address@hidden@address@hidden(@code{ebdb-save})
-
-Save all databases.
address@hidden ebdb-save
+Save all databases (@code{ebdb-save}).
address@hidden q
@kindex q
address@hidden quit-window
address@hidden @kbd{q} @address@hidden@address@hidden(@code{quit-window})
-
-Delete the *EBDB* window.
address@hidden quit-window
+Delete the *EBDB* window (@code{quit-window}).
@end table
@ref{Creating Records} and @ref{Record Fields} for more on record creation and
@@ -1171,11 +1151,11 @@ field manipulation.
@node Marking
@section Marking
-Records can be marked and acted on in bulk. The ``#'' key will toggle
-the mark of the record under point. ``M-#'' will toggle the marks of
-all the records in the buffer, and ``C-#'' will unmark all records in
-the buffer. Many editing commands can act on multiple marked
-records.
+Records can be marked and acted on in bulk. The @kbd{#} key will
+toggle the mark of the record under point. @kbd{M-#} will toggle
+the marks of all the records in the buffer, and @kbd{C-#} unmarks
+all records in the buffer. Many editing commands can act on multiple
+marked records.
@node Exporting/Formatting
@section Exporting/Formatting
@@ -1188,21 +1168,19 @@ At present, the only other supported format is VCard,
and support is
imperfect: not all fields can be exported correctly. VCard version
2.1 is unsupported: the only options are version 3.0 and 4.0.
address@hidden @asis
address@hidden @kbd
address@hidden f
@kindex f
address@hidden ebdb-format-to-tmp-buffer
address@hidden @kbd{f}
@address@hidden@address@hidden(@code{ebdb-format-to-tmp-buffer})
-
-This command prompts for a formatter, and formats the record under
-point to a temporary buffer. Use @ref{Marking, , marking} to format multiple
-records.
address@hidden ebdb-format-to-tmp-buffer
+This command prompts for a formatter, and formats the record
+under point to a temporary buffer (@code{ebdb-format-to-tmp-buffer}).
+Use @ref{Marking, , marking} to format multiple records.
address@hidden F
@kindex F
address@hidden ebdb-format-all-records
address@hidden @kbd{F}
@address@hidden@address@hidden(@code{ebdb-format-all-records})
-
-Export all records in the database (not only those displayed) to a
-different format.
address@hidden ebdb-format-all-records
+Export all records in the database (not only those displayed) to
+a different format (@code{ebdb-format-all-records}).
@end table
It's possible to write new formatters, documentation is forthcoming.
@@ -1211,20 +1189,21 @@ It's possible to write new formatters, documentation is
forthcoming.
@chapter Completion
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
address@hidden, respectively. Counsel and company are made to be
-hooked into Emacs' existing completion frameworks; the helm command
-must be called explicitly.
+exist providing EBDB support for helm, counsel, and company. These
+libraries must be loaded from the package repositories, and 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 built-in 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 @code{ebdb-complete-enable}.
+it for @address@hidden in @code{message-mode} by calling
address@hidden
-Several native EBDB commands involve selecting a record, or multiple
+Several native EBDB commands involve choosing 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
@@ -1244,44 +1223,38 @@ new one, and then display that contact.
Snarfing is a work in progress: at present, only mail addresses, URLs
and nearby names are acted upon, and it often doesn't work correctly.
address@hidden ebdb-snarf &optional string start end recs
@deffn Command ebdb-snarf &optional string start end recs
-
Extract record-related information from a piece of text. Find,
update, or create records as necessary, and then display them. When
the region is active, this command snarfs the current region,
-otherwise it snarfs the entire current buffer. Called as a
-function, it can accept a string as the first argument and snarfs
-that. The RECS argument, which cannot be passed interactively, is a
-list of records that are assumed to be related to snarfable data in
-STRING.
+otherwise it snarfs the entire current buffer. Called as a function,
+it can accept a string as the first argument and snarfs that. The
+RECS argument, which cannot be passed interactively, is a list of
+records that are assumed to be related to snarfable data in STRING.
@end deffn
@defopt ebdb-snarf-routines
-
-An alist of field class symbols and related regexps. The regexps
-are used to collect text that is likely parseable by the
address@hidden method of the field class.
+An alist of field class symbols and related regexps. The regexps are
+used to collect text that is likely parseable by the @code{ebdb-parse}
+method of the field class.
@end defopt
@defopt ebdb-snarf-name-re
-
A list of regular expressions used to recognize names for a snarfed
-contact. Searching names directly is mostly impossible, so names
-are only looked for in close proximity to other field data.
+contact. Searching names directly is mostly impossible, so names are
+only looked for in close proximity to other field data.
@end defopt
address@hidden Article snarfing
In MUAs, EBDB can also snarf the body of the article being displayed.
This is separate from the updating process, which only examines the
article headers.
address@hidden ebdb-mua-snarf-article
address@hidden Command ebdb-mua-snarf-article
-
address@hidden Command ebdb-mua-snarf-article &optional arg
Snarf the body of the current article. This will also snarf the
headers of forwarded emails, and the signature. With a prefix
argument, only snarf the signature.
address@hidden deffn
address@hidden defopt
@node Internationalization
@chapter Internationalization
@@ -1317,9 +1290,9 @@ Internationalization libraries do not modify the
database, 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.
+Loading internationalization libraries may slow down initial database
+loading, though they should not significantly impact search or display
+performance.
Actually, the internationalization library does alter database storage
in one way: address countries can be either stored as a string
@@ -1334,9 +1307,9 @@ the display of some country names if they choose.
@defopt ebdb-i18n-countries-pref-scripts
This is an alist of conses pairing string country names to symbol
-labels---see the value of @code{ebdb-i18n-countries} for how to use it, and
-to find the correct symbol label. Values set in this option will
-shadow the values in the variable.
+labels---see the value of @code{ebdb-i18n-countries} for the correct
+format, and to find the correct symbol label. Values set in this
+option will shadow the values in the variable.
@end defopt
@node Diary Integration
@@ -1351,13 +1324,12 @@ an actual diary file present at the location indicated
by
@code{diary-file}, though the file can be blank.
@defopt ebdb-use-diary
-
-If non-nil, EBDB fields with date information will attempt to add
-that information to the diary.
+If non-nil, EBDB fields with date information will attempt to add that
+information to the diary.
@end defopt
-When viewing the calendar, you can use the ``d'' key to see diary
-information for that day.
+When viewing the calendar, you can use the @kbd{d} key to see
+diary information for that day.
Support for this feature is rudimentary. More customization options
are forthcoming.
@@ -1370,13 +1342,13 @@ You can give records a mail alias with the ``mail
alias'' field,
available in the list of choices for inserting new fields. You'll be
prompted for an alias, and an email address to use for the alias, if
the record has more than one. If multiple records have the same
-alias, then entering that alias in the To: or Cc: field of a message
-composition buffer will expand to a comma-separated list of record
-addresses.
+alias, then entering that alias in the ``To:'' or ``Cc:'' field of a
+message composition buffer will expand to a comma-separated list of
+record addresses.
At present, it's necessary to manually parse existing aliases with the
-``A'' key in a *EBDB* buffer. This limitation will be removed
-in the future.
address@hidden key in a *EBDB* buffer. This limitation will be
+removed in the future.
@node vCard Support
@chapter vCard Support
@@ -1394,29 +1366,42 @@ eventually, support for CardDav servers.
@chapter 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.
+EBDB records works as expected with @kbd{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
+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}''.
+are of the format ``ebdb:<field type>/<search string>''. The
address@hidden 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
address@hidden 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
@code{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.
address@hidden field, , Tag Field}.
+
+This library comes with one other function that allows you to pop up
+an *EBDB* buffer alongside an Org Agenda buffer.
+
address@hidden Command ebdb-org-agenda-popup
+Pop up an EBDB buffer displaying contacts matching the tags used to
+create the Agenda buffer. Only does anything in a tags search Agenda
+buffer.
address@hidden deffn
+
+This function could also be added to the @code{org-agenda-mode-hook}, to
+pop up a buffer any time relevant records are found.
@node Citing Records
@chapter Citing Records
@@ -1426,14 +1411,12 @@ 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
@deffn 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.
+citation looks like ``Some Name <some@@email.com>''. In Org buffers, it
+is a link with a ``mailto:'' prefix.
@end deffn
@node Hacking EBDB
@@ -1441,7 +1424,7 @@ it is a link with a ``mailto:'' prefix.
EBDB is designed to be highly extensible. In addition to the usual
customization options, it provides for subclassing of the three main
-classes -- database, record, and field. The behavior of EBDB can be
+classes: database, record, and field. The behavior of EBDB can be
radically changed by creating new classes, or overriding the existing
methods of classes, without touching the original source code. This
manual won't go into details about Emacs' object-orientation support:
@@ -1452,39 +1435,33 @@ The simplest customization involves changing the
default classes used
for basic record and field types.
@defopt ebdb-default-record-class
-
-The default class used for creating records. This class will be
-used when creating records with ``c'' in ebdb-mode, or when
+The default class used for creating records. This class will be used
+when creating records with @kbd{c} in ebdb-mode, or when
automatically creating records (ie, from snarfing). It's always
-possible to create a record of a different class by using ``C'' in
-ebdb-mode.
+possible to create a record of a different class by using @kbd{C}
+in ebdb-mode.
@end defopt
address@hidden ebdb-default-name-class
-
address@hidden ebdb-default-record-class
The default class for complex names. Simple names (used for
-organizations and nicknames) are always plain strings -- this option
-only governs the class used for articulated names of individuals,
-with separate slots for surname, given names, suffixes, etc.
+organizations and nicknames) are always plain strings---this option
+only governs the class used for articulated names of individuals, with
+separate slots for surname, given names, suffixes, etc.
@end defopt
@defopt ebdb-default-mail-class
-
The default class for mail fields.
@end defopt
@defopt ebdb-default-phone-class
-
The default class for phone fields.
@end defopt
@defopt ebdb-default-address-class
-
The default class for address fields.
@end defopt
@defopt ebdb-default-notes-class
-
The default class for notes fields.
@end defopt
@@ -1543,10 +1520,10 @@ instance. The simplest field types only need to
provide these three
methods.
The @code{ebdb-read} and @code{ebdb-parse} methods are static (class-level)
-methods. Both take an optional ``slots'' argument, which a plist of
+methods. Both take an optional @code{slots} argument, which a plist of
slot values that will eventually be fed to @code{make-instance}. If values
-are already present in the plist, these methods should /not/ override
-them. In addition, @code{ebdb-read} takes an optional ``obj'' argument,
+are already present in the plist, these methods should _not_ override
+them. In addition, @code{ebdb-read} takes an optional @code{obj} argument,
which, if present, is an existing field instance that can be used to
provide default values for the new object.
@@ -1575,6 +1552,7 @@ provide default values for the new object.
@menu
* Init and Delete Methods::
* The Labeled Field Class::
+* The Singleton Field Class::
* Actions::
* Custom Field Searching::
* Formatting in the EBDB Buffer::
@@ -1588,46 +1566,47 @@ It's also very common to define @code{ebdb-init-field}
and
maintain secondary data structures, or set up extra hashing for
records, or do any other supplemental work. The one restriction is
that they must not change the database: they may not edit records or
-their fields. Both methods are called with the field instance as the
-first argument, and the record the instance belongs to as an optional
-second argument. @code{ebdb-delete-field} also accepts an optional third
-argument, ``unload'', which is non-nil when the record is being
-unloaded, rather than deleted.
+their fields.
+
address@hidden Method ebdb-init-field field record
+Initialize @var{field} against @var{record}.
address@hidden deffn
+
address@hidden Method ebdb-delete-field field &optional record unload
+Delete @var{field} of record @var{record}. If
+the optional argument @var{unload} is non-nil, it means
+the record is only being unloaded
address@hidden deffn
Both methods should always end with a call to @code{cl-call-next-method}.
@code{ebdb-init-field} is called:
address@hidden
address@hidden
@item
When loading for the first time (records call @code{ebdb-init-field} on
all of their fields after they're loaded).
-
@item
When adding a new field instance to a record.
-
@item
When editing an existing field instance (editing is a
delete-and-create operation).
address@hidden itemize
address@hidden enumerate
@code{ebdb-delete-field} is called:
address@hidden
address@hidden
@item
When deleting a field instance.
-
@item
When deleting the record owning the field instance.
-
@item
When editing an existing field instance (editing is a
delete-and-create operation).
-
@item
When unloading a record from the database (the optional third
-``unload'' argument will be non-nil).
address@hidden itemize
address@hidden argument will be non-nil).
address@hidden enumerate
@node The Labeled Field Class
@subsection The Labeled Field Class
@@ -1647,15 +1626,25 @@ used to hold labels, and pointing to it in the
class-allocated
((label-list :initform my-field-label-list)))
@end lisp
address@hidden The Singleton Field Class
address@hidden The Singleton Field Class
+
+Another abstract mix-in class is the @code{ebdb-field-singleton} class.
+It's only function is to ensure that a record only ever has one
+instance of the class in question. If the user tries to add a second
+instance, the existing instance is deleted.
+
@node Actions
@subsection Actions
address@hidden Field actions
All field classes have a class-allocated slot called ``actions''. The
value of this slot is a list of conses, for instance: @code{("Browse URL"
. ebdb-field-url-browse)}. Users can trigger these actions by
-pressing ``RET'' while point is on the field in the *EBDB*
-buffer, using a numeric prefix arg to select from multiple possible
-actions, or the 0 prefix arg to be prompted for which action to take.
+pressing @address@hidden while point is on the field in the
+*EBDB* buffer, using a numeric prefix arg to select from
+multiple possible actions, or the 0 prefix arg to be prompted for
+which action to take.
The functions in this list should accept two arguments, the record and
the field instance under point.
@@ -1675,12 +1664,14 @@ chosen, it has the option to prompt for more complex
search criteria.
This is done by overriding two matching methods: @code{ebdb-search-read},
and @code{ebdb-field-search}.
address@hidden ebdb-search-read
@code{ebdb-search-read} is a static (class-level) method. Its only
argument is the field class being searched on. It should prompt the
user for whatever search criterion it wants, then return that
criterion. This can be nearly anything, so long as the matching
@code{ebdb-field-search} can accept it.
address@hidden ebdb-field-search
The @code{ebdb-field-search} method accepts a field instance as the first
argument, and the search criterion as the second. It should return
non-nil if the criterion somehow matches the field. Note that it's
@@ -1693,15 +1684,43 @@ search criterion as a cons: @code{("label string"
against the label of the instance, and then other-search-criteria will
be passed to the @code{ebdb-field-search} method as usual.
+That might sound a bit confusing, here's an example. These are the
+search methods for the @code{ebdb-field-tags} class.
+
address@hidden
+(cl-defmethod ebdb-search-read ((_class (subclass ebdb-field-tags)))
+ (cdr
+ (org-make-tags-matcher
+ (ebdb-read-string
+ "Search for tags (eg +tag1-tag2|tag3): "))))
+
+(cl-defmethod ebdb-field-search ((field ebdb-field-tags)
+ func)
+ (when (functionp func)
+ (funcall func t (slot-value field 'tags) 1)))
+
+(cl-defmethod ebdb-field-search ((field ebdb-field-tags)
+ (tag string))
+ (seq-find (lambda (tg) (string-match-p tag tg))
+ (slot-value field 'tags)))
address@hidden lisp
+
+The @code{ebdb-search-read} method returns a lambda (the @code{cdr} of the
+return value of @code{org-make-tags-matcher}. The first
address@hidden method handles that lambda, simply by calling it.
+The second @code{ebdb-field-search} method handles a string search
+criterion; though no EBDB code would create this search, external code
+conceivably might.
+
@node Formatting in the EBDB Buffer
@subsection Formatting in the EBDB Buffer
-Most fields will be displayed in the *EBDB* buffer simply using
address@hidden It's possible to customize this display by overriding
-the @code{ebdb-fmt-field} method. Without going into too much detail, this
-method dispatches on four arguments: the formatter, the field, a
-``style'' symbol argument (typically 'normal, 'oneline, 'compact',
-'collapse or 'expanded), and the record being formatted.
+Most fields will be displayed in the *EBDB* buffer simply
+using @code{ebdb-string}. It's possible to customize this display by
+overriding the @code{ebdb-fmt-field} method. Without going into too much
+detail, this method dispatches on four arguments: the formatter, the
+field, a ``style'' symbol argument (typically @code{normal}, @code{oneline},
address@hidden, @code{collapse} or @code{expanded}), and the record being
formatted.
Specify an ebdb formatter for the first argument to target
*EBDB* formatting. Choices are @code{ebdb-formatter-ebdb} (for
@@ -1709,15 +1728,16 @@ all cases), or one of
@code{ebdb-formatter-ebdb-multiline} or
@code{ebdb-formatter-ebdb-oneline}. Keep in mind that many field classes
are not displayed at all in the oneline format.
-An example: most fields are output with style set to 'normal, meaning
+An example: most fields are output with style set to @code{normal}, meaning
that it will use the value of @code{ebdb-string}. By default, formatters
-display address fields in the 'collapse style, which is mapped to the
-'oneline style, which simply drops everything after the first newline.
+display address fields in the @code{collapse} style, which is mapped to the
address@hidden style, which simply drops everything after the first
+newline.
Say you still wanted addresses output on a single line, but you wanted
to provide a little more information on that line: the first line of
the street addresses, plus the city, plus the country. You could
-achieve that by overriding the 'collapse style like so:
+achieve that by overriding the @code{collapse} style like so:
@lisp
(cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter)
@@ -1774,12 +1794,10 @@ nationality or locality of the field instance.
Address fields use a three-character symbol derived from the
@uref{https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3, ISO
316601 alpha 3} country codes. These codes can be found in the
variable @code{ebdb-i18n-countries}.
-
@item
Phone fields use the phone number's numerical country code as a
spec. These codes can be found in the variable
@code{ebdb-i18n-phone-codes}.
-
@item
Name fields are keyed to the symbol representing the script used to
write them. Specifically, the first character CHAR of the name is
@@ -1793,7 +1811,7 @@ able to specialize on. Every country-specific method
should check the
spec to see if it is relevant to that library. If so, it handles the
necessary behavior; if not, it passes by using @code{cl-call-next-method}.
See the function signatures of each internationalized method to find
-how to handle the extra argument, called SPEC.
+how to handle the extra argument, called @var{spec}.
Here's a concrete example:
@@ -1801,8 +1819,8 @@ Say we want to make sure all French phone numbers are
represented by a
string that looks like ``+33 05 12 34 56 79''. This is not how they are
stored in the database, but this is how they should be represented to
the user. We need to override the @code{ebdb-string-i18n} method for the
-phone field class. This method takes two arguments -- the field
-instance, and the country-code spec -- and needs to specialize on both
+phone field class. This method takes two arguments---the field
+instance, and the country-code spec---and needs to specialize on both
arguments. The method signature will look like this:
@lisp
@@ -1813,10 +1831,10 @@ arguments. The method signature will look like this:
See the manual on generic functions for details; suffice it to say
that this method will only run when the first argument is an instance
of the @code{ebdb-field-phone} class (or a subclass), and the second
-argument is the number 33.
+argument is @code{eql} to the number 33.
-Now we know that this method will only run for French phone numbers,
-so we can format the number correctly:
+We know that this method will only run for French phone numbers, so we
+can format the number correctly:
@lisp
(cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
@@ -1852,6 +1870,7 @@ 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.
address@hidden ebdb-mua-auto-update
The first step of integration involves hooking the function
@code{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
@@ -1863,6 +1882,7 @@ generic functions. All MUA-specific generic functions
specialize on
the current major-mode, using the @code{&context} specializer. See below
for examples.
address@hidden ebdb-mua-message-header
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
@@ -1876,7 +1896,6 @@ return the contents of the appropriate header. For
instance, in Gnus:
"Return value of HEADER for current Gnus message."
(set-buffer gnus-article-buffer)
(gnus-fetch-original-field header))
-
@end lisp
The first argument is the string header, and the second is the
@@ -1891,29 +1910,30 @@ 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
address@hidden Method 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
address@hidden deffn
Providing *EBDB* buffer pop-up support involves implementing
two separate functions:
address@hidden ebdb-make-buffer-name
address@hidden Method 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:
@code{(format "*%s-<mua>" ebdb-buffer-name)}.
address@hidden defun
address@hidden deffn
address@hidden ebdb-popup-window
address@hidden Method 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
+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 deffn
address@hidden ebdb-mua-keymap
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.
@@ -1925,6 +1945,7 @@ EBDB functions.
@node Article snarfing
@subsection 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
@@ -1933,13 +1954,13 @@ 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
address@hidden Method ebdb-mua-article-body
Return the text of the article body, or nil.
address@hidden defun
address@hidden deffn
address@hidden ebdb-mua-article-signature
address@hidden Method ebdb-mua-article-signature
Return the text of the article signature, or nil.
address@hidden defun
address@hidden deffn
@node Index
@unnumbered Index
- [elpa] externals/ebdb 886c134 27/33: Add new ebdb-field-mail-folder fieldclass, (continued)
- [elpa] externals/ebdb 886c134 27/33: Add new ebdb-field-mail-folder fieldclass, Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb 823a7d4 29/33: Use value of ebdb-mua-folder-list in VM splitting, Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb a5ffda9 33/33: Merge remote-tracking branch 'elpa/externals/ebdb', Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb d6b9b77 06/33: Re-remove ebdb-vm, Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb ea2a149 16/33: Add generic tags field, Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb 7f9aded 20/33: Add to ebdb-db-list in ebdb-test-with-database, Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb a4abcbc 24/33: Fix to internationalized ebdb-read for phones, Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb ff3dec2 28/33: Use value of ebdb-mail-folder-list in Gnus splitting, Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb 2ec37b9 32/33: Bump version to 0.3, Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb b797e85 31/33: Make mail alias updating happen automatically, Eric Abrahamsen, 2017/09/03
- [elpa] externals/ebdb 8868ceb 26/33: Remove texinfo manual dependency on texinfo+,
Eric Abrahamsen <=