EBDB Manual

Copying

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”

Getting Started

EBDB is a contact management package: it records information about people and organizations, and integrates with other Emacs software packages, mostly those concerned with sending and reading mail. The principle parts of EBDB are records, which represent people and organizations; fields, representing detailed data about records; and databases, which hold and persist records.

It’s easiest to install EBDB from the ELPA package repositories, though it’s also possible to clone the package from Github and put it on your load path. Questions and bug reports can be raised on the Github issues page, or on the Emacs bug tracker or mailing lists, provided you cc the maintainer.

There are a large number of configuration options listed in this manual, but the only one you might want to tweak in advance is ebdb-sources (see The EBDB Database), which controls where EBDB stores its records.

EBDB comes with integration for a few other Emacs packages, including Org and a number of mail user agents; see the following sections below for details.

Emergency Escape Hatch: EBDB strives to be bug-free, naturally, but due to the nature of the package, when bugs do arise they can potentially interfere with the reading and sending of email. No one likes it when their email is interfered with. If, God forbid, you do encounter such a bug, you can prevent it from doing harm by running:

(setq ebdb-mua-auto-update-p nil)

That will ensure that EBDB only runs when you explicitly command it to do so; it won’t interpose itself in other MUA operations. If you really need to kill it and make it go away, use M-x ebdb-shutdown.

Starting a New Database

If you have no records you want to migrate from other contact management software, start by calling the command ebdb-open. This will open a new buffer in ebdb-mode, and prompt you to create a database, if one doesn’t already exist. From there, you can use {{{kbd(c)}}} to make new records (see Creating Records). You can also hook EBDB into a mail-user agent (see MUA Interaction) and allow it to create records automatically.

Otherwise, you’ll want to migrate your contact information from other contact management software as described in the sections below. Currently EBDB only knows about migrating from BBDB and Org Contacts.

Migration from BBDB

Record Migration

It’s possible to migrate records from a BBDB database. The bbdb-file variable should point to your current BBDB file; alternately EBDB will look in the default location, found using (locate-user-emacs-file "bbdb" ".bbdb). Then call ebdb-migrate-from-bbdb. You’ll be prompted to create the new database, and upgrade from BBDB. If any records could not be upgraded, they will be displayed in an {{{buf(EBDB Migration Errors)}}} buffer. Migration bug reports are very welcome.

BBDB does not provide a country code field for phone numbers. If you’ve stored your BBDB phone numbers as plain strings, and those strings contain country codes (formatted as “+44”, etc), then migration will parse them correctly. Otherwise, if most of the records you’re migrating have phones in the same country, you can set ebdb-default-phone-country to the (integer) value of that country’s code.

Variables and Options

Many of the old BBDB customization options have been changed or removed entirely in EBDB. It’s probably best to put your BBDB customizations aside, and set new EBDB options as you come across them. The most important options are detailed in this manual, you can also customize the “EBDB” group to see what’s available.

Migration from Org Contacts

EBDB also provides limited support for migrating from Org Contacts: simply call the command ebdb-migrate-from-org-contacts. Your contacts database will be scanned, and all contacts will be migrated. Any field values that could not be migrated will be displayed in a {{{buf(EBDB Migration Errors)}}} buffer.

At present, addresses cannot be migrated automatically. Org Contacts stores addresses as a free-form string, which is simply too difficult to parse accurately. Address values will be inserted into the migration errors buffer, and will have to be added to the records manually.

The EBDB Database

EBDB supports multiple databases, and each database definition is saved in a file on disk. The default database class, ebdb-db-file, stores its contacts in the same file as the database itself, though other database classes may store contacts elsewhere.

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.

Databases have a few user-facing settings:

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.

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 {{{buf(EBDB)}}} buffer, the following keys can be used to manipulate databases and their records.

d m: Move a record from its current database to another (ebdb-move-record).
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: Reload all records from a database. This also redisplays any of those records that were visible in {{{buf(EBDB)}}} buffers (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.

Typically, databases are saved using the {{{kbd(s)}}} binding in ebdb-mode buffers, which runs ebdb-save. If you have open {{{buf(EBDB)}}} buffers and unsaved changes, you’ll also be prompted to save the database when running save-some-buffers. If this isn’t enough, you can also set ebdb-save-on-exit to non-nil to have EBDB saved automatically (and silently) when killing Emacs. Because killing Emacs already runs save-some-buffers, this option is typically redundant and defaults to nil.

Loading and initializing the EBDB can be slow for large databases. If you find yourself annoyed by the wait, try setting ebdb-try-speedups to non-nil. This will disable some checks performed during the object creation process, which theoretically shouldn’t make a difference. If something does go wrong at load-time, however, try setting this back to nil first.

Creating Records

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.

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:

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, 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 into surname, given names, suffix, etc. All records have a single canonical name: person records have a complex name, organization records have a simple name.

In addition, person records can have one or more “aka” names, and these akas can be either simple or complex. When adding fields to a record, the simple name class is labeled “nickname”, and the complex class is labeled “alt name”.

Record Fields

Inserting New Fields

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 {{{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

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.

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

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

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 {{{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 Hacking EBDB for more information.

Besides the “plumbing” and “built-in” fields, all other fields are 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”), then enter the field data, and lastly choose a 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. You can also enter an empty string or hit {{{kbd(C-g)}}} to omit the label altogether.

Loading secondary libraries may make more field types available.

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 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.

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 {{{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 (an employee number, employment start date, etc). The author has yet to come up with a good interface for viewing and manipulating these extra fields, however, so the functionality remains hidden. Suggestions are very welcome.

It can often feel a little clunky creating a new organization to associate with a person, or vice versa. EBDB provides a convenience function to create a new person or organization record, and associate it with the existing record under point, in one step, using {{{kbd(R)}}}. This will create a new organization if point is on a person record, or a new person if point is on an organization.

Lastly, EBDB will try to assist in creating role fields where it seems helpful. When adding mail fields to person records, or domain fields to organization records, it will check if the mail or domain seems to match any existing records, and offer to create the corresponding role fields. This behavior is enabled by default; set ebdb-create-update-roles to nil to disable it.

Tag field

EBDB comes with a field holding arbitrary tags for records. When searching on the tags field (using {{{kbd(/ t)}}} 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 alters the behavior of this class, offering all the user’s Org-file tags for completion. 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 user agent(s). In theory, EBDB can be integrated with any software package, but it’s most common to use it in conjunction with sending and receiving emails.

Loading MUA Code

MUA code is activated simply by loading the relevant library. Keep in mind that mail-reading clients and mail-sending clients are considered separate MUAs. For instance, if you use the Gnus package for reading mail, and Message for sending it, you’ll want two require statements:

(require 'ebdb-gnus)
(require 'ebdb-message)

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, wl, and rmail.

Display and Updating

When a message is opened in an MUA, EBDB can do certain things with the records referenced in that message. It can:

Pop up a buffer displaying the records.
Create new records, or alter existing records, based on information provided by the MUA.
Run automatic rules to edit the records.
Provide keybindings to manually edit the records.

Each of these functionalities is optional, and can be customized independently of the others.

Pop-up Buffers

Each MUA 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.

EBDB can also integrate with atomic windows (@@texinfo:@xref{Atomic Windows,,,elisp}@@).

In addition, each MUA has its own customization option for controlling the window size of pop-up buffers. Each option is named as ebdb-<MUA>-window-size, and each defaults to ebdb-default-window-size.

The Gnus and Message MUAs have their own special window configuration system (@@texinfo:@xref{Window Layout,,,Gnus}@@). If you’re not making special use of that system, EBDB will default to taking up a percentage of the article and message composition windows. If you are using that system for more control, you use the ebdb-gnus-window-configuration and ebdb-message-window-configuration options to do so. They should be set to two arbitrary (but distinct) symbols, which will be added to the gnus-window-to-buffer alist, and can be used in gnus-add-configuration calls, for example:

(gnus-add-configuration
 '(article
   (vertical 1.0
             (summary 0.25 point)
             (horizontal 1.0
                         (article 1.0)
                         (ebdb-gnus 0.4)))))

Because Gnus and Message use separate EBDB buffers for record update and display, the two options must be separate, and used in the appropriate article-display vs message-composition window configurations.

Auto-Updating Records

EBDB can automatically update the name and mail addresses of records based on information in an MUA message. The first and most important option governing this behavior is:

For instance, say you want to automatically create records for addresses you send mail to, but not when sending messages to newsgroups. If you’re using message-mode, you could use the following:

(setq ebdb-message-auto-update-p
      (lambda ()
        (unless (ebdb-mua-message-header "Newsgroups")
          'query)))

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.

In many cases it’s useful to have different auto-update behavior in different MUAs. In particular, you might want to automatically create records for addresses as you send messages to them, but retain manual control over creating records from messages you receive. EBDB provides two more-specific versions of ebdb-mua-auto-update-p:

Even finer-grained control is available using per-MUA versions of the option, all of them named after the pattern ebdb-<MUA>-auto-update-p.

When updating records either automatically or interactively, a few more options come into play:

There are also options governing whether EBDB will consider a mail address or not:

When auto update is set to query, and the user has already told EBDB not to automatically create or update a record for a given mail address, it can be annoying when opening the message a second timed to be prompted again. It is possible to permanently ignore a mail address, by saving it to disk.

When EBDB queries to create or update a record, the {{{kbd(i)}}} key will ignore the mail permanently; the {{{kbd(I)}}} key will ignore the entire domain. If the above option is nil, the mail will be ignored for this session only, otherwise it will be saved to disk the next time EBDB is saved.

It’s also possible to add addresses manually, while EBDB is shut down. The format is one address per line, with no attached name or angle brackets. Domains to be ignored should start with the “@” symbol. The addresses are matched literally (though case-insensitively); it’s not possible to use regexps.

Noticing and Automatic Rules

In addition to updating records’ name and mail fields, it’s possible to run other arbitrary edits on records when they are referenced in a message. This process is called “noticing”. Two hooks are run as a part of noticing:

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 @@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.

A useful function here is ebdb-mua-message-header, which can be used to extract the value of arbitrary headers from the current message. The header should be provided as a string, for example (ebdb-mua-message-header "Subject"). There is currently no shortcut for extracting the text of the message body; code to do this will have to be written per-MUA.

For functions that can be used to edit a record’s field data, Manipulating Field Data Programmatically.

Interactive Commands

Some interactive commands are also provided for operating on the relevant EBDB records. In message-reading MUAs, EBDB creates its own keymap, and binds it to the key “;”. The following list assumes this binding, and only specifies the further binding. Ie, press “;:” to call 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.
;: If the option ebdb-mua-pop-up is nil, this command can be used to do the same thing (ebdb-mua-display-all-records).
‘: Edit the notes field of the message sender (ebdb-mua-edit-sender-notes).
@@texinfo:@quotedblright{}@@: 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: 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.
t: This command toggles the displayed records between the multiline and oneline display formats.

Other command are not bound by default:

EBDB and MUA summary buffers

EBDB can affect the way message senders are displayed in your MUA’s summary buffer. It can do this in two ways: 1) by changing the way the contact name is displayed, and 2) by optionally displaying a one-character mark next to the contact’s name.

Sender name display

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, 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).

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 and VM MUAs. This can be done in one of three ways. From most general to most specific:

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, and adding the EBDB-specific format code:

Mail Address Completion

Emacs’ two message-composition modes are message-mode and mail-mode, the former having somewhat obsoleted the latter – EBDB supports both.

The main use of EBDB in message composition is to complete email addresses of contacts, obviously. The following options govern this behavior:

A Note on Completion

As mentioned above, EBDB completion can be done either using the completion at point framework, or its own ebdb-complete-mail function. The two don’t behave exactly the same, however: completion at point works from a pre-constructed list of strings, while ebdb-complete-mail conducts an actual search of the database. This means that the former is faster, but the latter will find more records, particularly if search options like ebdb-case-fold-search are in effect.

Specific MUAs

Gnus

EBDB has a little more support for Gnus than the other MUAs, for no other reason than that Gnus is what the author uses.

Posting Styles

Gnus provides a “posting styles” mechanism which allows the user to set up specific mail composition styles (custom headers and signatures, etc) when writing mails to certain recipients. The mechanism examines Gnus group names to determine which styles to use. EBDB can fake this mechanism so that different styles are used when composing messages to different records.

When writing this function, functions such as ebdb-record-field and ebdb-record-current-fields may come in handy. Here’s a less-obvious example that dispatches styles depending on which database the record belongs to:

(setq ebdb-gnus-post-style-function
      (lambda (rec _mail)
        (let ((dbs (ebdb-record-databases rec)))
          (if (object-assoc "File: work.dat" 'label dbs)
              "nnimap+WorkAccount:INBOX"
            "nnimap+PersonalAccount:INBOX"))))

A current limitation of this functionality is that it only works when composing a mail to a single recipient. If you mark several records in a {{{buf(EBDB)}}} buffer and compose a mail to them collectively, the mechanism will be bypassed.

EBDB Buffers

EBDB can create several separate buffers for displaying contacts. Typically, each MUA creates its own buffer, with names like {{{buf(EBDB-Gnus)}}}, etc. Users can also create their own buffers that won’t be interfered with by MUA pop-up action. Calling the ebdb command directly will create such a “user-owned” buffer; it’s also possible to create more by using the ebdb-clone-buffer and ebdb-rename-buffer commands within existing EBDB buffers.

b c: Prompt for a buffer name, and create a new EBDB buffer displaying the same records as the original buffer (ebdb-clone-buffer).
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.

Searching

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: {{{kbd(/)}}} clears the buffer and searches the whole database, {{{kbd(|)}}} searches only among the records already displayed, and {{{kbd(+)}}} searches the whole database and appends the 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:

n: Search names
o: Search organizations
p: Search phones
a: Search addresses
m: Search mails
t: Search tags
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 {{{kbd(/)}}} prefix are:

/ 1: Prompt for a single record, and display it
/ d: Search duplicate records

Searches can be inverted:

!: Invert the results of the next search (ebdb-search-invert).

Each user-created {{{buf(EBDB)}}} buffer keeps track of search history in that buffer. To pop back to previous searches, use:

^: ebdb-search-pop

Changing Search Behavior

There are three ways to alter the behavior of EBDB searches.

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 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.

n

Move point to the next record (ebdb-next-record).

p

Move point to the previous record (ebdb-prev-record).

N

Move point to the next field (ebdb-next-field).

P

Move point to the previous field (ebdb-prev-field).

c

Create a new person record in the primary database (ebdb-create-record).

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 (ebdb-insert-field).

e

Edit the field under point (ebdb-edit-field).

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 (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).

@@texinfo:@kbd{@key{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. {{{kbd(@key{RET})}}} on a mail field will compose a message to that mail address.

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.

M

Begin composing a separate message to each marked record in the current {{{buf(EBDB)}}} buffer, or all records in the buffer if none are marked. In addition, prompt for a common subject header line to use for each message, as well as records to add to the “Cc” and “Bcc” headers. Then optionally prompt for a character, interpreted as the name of a register. If that register contains text, insert the text as the body of each message.

This function works as a sort of poor-man’s mail merge; it lacks the ability to interpolate variables in the body text.

t

Toggle between a multi-line, one-line, and full display (see Customizing Record Display) (ebdb-toggle-records-format).

T

Toggle the display of all the records in the current {{{buf(EBDB)}}} buffer. (ebdb-toggle-all-records-format).

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) (ebdb-omit-records).

I

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.

w f

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 (ebdb-copy-records-as-kill).

w m

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 <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.

g

Redisplay all visible records (revert-buffer).

?

Show a very brief help message (ebdb-help).

h

Open this manual (ebdb-info).

s

Save all databases (ebdb-save).

q

Delete the {{{buf(EBDB)}}} window (quit-window).

Creating Records and Record Fields for more on record creation and field manipulation.

Customizing Record Display

The appearance of records in {{{buf(EBDB)}}} buffers can be customized. The display of records is controlled by objects called formatters, and two such objects are provided by default, one creating a multi-line display of records (the value of ebdb-default-multiline-formatter), and another creating a single-line display (ebdb-default-oneline-formatter). Some customization options are provided to influence the behavior of these formatters (see the ebdb-record-display group), but users familiar with EIEIO objects can also manipulate formatter slot-values directly, override display methods, or write entirely new formatters. Any formatter that inherits from ebdb-formatter-ebdb will be made available for cycling with the {{{kbd(t)}}} key in {{{buf(EBDB)}}} buffers.

The following options affect how various fields are displayed in {{{buf(EBDB)}}} buffers. The values of these options are always lists of field types as symbols: either the actual names of the field classes (ebdb-field-*), or one of the following shortcuts:

mail
phone
address
notes
tags
role
mail-primary
mail-defunct
mail-not-defunct
role-defunct
role-not-defunct

There are also a number of faces that can be manipulated; see the ebdb-faces group.

Users who wish for more fine-grained control over output can override the formatting methods ebdb-fmt-record, ebdb-fmt-field-label, and ebdb-fmt-field. It may be necessary to poke around in the source code to get things exactly right, but the general signature looks like:

(cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter-ebdb)
                              (field ebdb-field)
                              _style
                              (_record ebdb-record))
  (ebdb-string field))

Possible values for the “style” argument are nil, oneline, compact, and collapse.

Marking

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.

Image Display

Records can have an image associated with them, by adding an instance of ebdb-field-image. The actual image is not stored in the database, but in some external location which the field instance points to. This pointer can be:

An absolute file path
A relative file path, in which case the function locate-file will be used to find the image, in conjunction with ebdb-image-path and ebdb-image-suffixes
One of the symbols name, lf-name, or fl-name, in which case the record’s name will be used to construct a relative file path, to be used as above.
Any other value, in which case the function ebdb-field-image-function will be called with the image field and record as arguments. This function is a generic method, and is unimplemented by default.

The option ebdb-image controls which of these methods to use by default, though separate methods can be chosen for each field instance.

Lastly, display of the image can be controlled with the option ebdb-image-addition-plist. The value should be a plist suitable for merging with Emacs’ image data, see Image Descriptors for more information.

Exporting/Formatting

It is possible to export (referred to as “formatting”) records in various ways. The most common export format is that of the {{{buf(EBDB)}}} buffers themselves, but other formats are possible.

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.

f: This command prompts for a formatter, and formats the record under point to a temporary buffer (ebdb-format-to-tmp-buffer). Use marking to format multiple records.
F: Export all records in the current EBDB buffer to a different format (ebdb-format-these-records).

It’s possible to write new formatters, documentation is forthcoming.

Completion

There are many Emacs completion frameworks out there, and EBDB provides custom commands for a few of them: ebdb-helm, ebdb-counsel, and ebdb-company. Counsel and company are made to be hooked into Emacs’ existing completion frameworks; the helm command must be called explicitly. For information about completion in mail composition buffers, see Mail Address Completion.

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 {{{kbd(@key{TAB})}}} in message-mode by calling ebdb-complete-enable.

Snarfing

“Snarfing” refers to scanning free-form text and extracting information related to EBDB records from it. For example, calling ebdb-snarf while the region contains the text “John Doe <j.doe@email.com>” will find an existing contact or prompt to create a new one, and then display that contact.

Snarfing is a work in progress: at present, only mail addresses, phone numbers, URLs, and nearby names are acted upon, and it often doesn’t work correctly.

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.

Internationalization

EBDB comes with an internationalization framework that can provide country- and region-specific behavior for certain fields. This functionality is initialized by loading the @@texinfo:@file{@@ebdb-i18n@@texinfo:}@@ library. This library does nothing by itself, it simply provides hooks for other country-specific libraries.

Country libraries that do not depend on other external libraries may live within the EBDB codebase, in which case they will be loaded automatically when ebdb-i18n is loaded. Libraries with external dependencies may be installed from the package repositories. Because function autoloading doesn’t work with generic methods, you’ll need to require the libraries in addition to simply installing them.

There is currently only one country library written for EBDB, @@texinfo:@file{@@ebdb-i18n-chn@@texinfo:}@@, for Chinese-related fields. It parses and displays phone numbers and names correctly, and also allows users to search on Chinese names using pinyin. It can be installed from ELPA, and requires the pyim package, available on MELPA.

The present dearth of libraries is a result of the author scratching his own itch. Contributions of new libraries are very welcome (see Writing Internationalization Libraries). Also welcome, though 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.@@texinfo:@:@@ for 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 (non-international-aware), or a three-letter symbol representing the country code (international-aware). EBDB will correctly display the country name for either type of storage, regardless of whether the 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.

Diary Integration

Some EBDB fields hold dates or anniversaries (most notably the ebdb-field-anniversary field). It’s possible to integrate this information with Emacs’ diary package. To activate this, add the following line to your diary file:

%%(ebdb-diary-anniversaries)

To integrate this with the Org Agenda, either set org-agenda-include-diary non-nil, or the above line can be inserted directly in an Org file (instead of the diary file).

Support for this feature is rudimentary. More customization options are forthcoming.

Mail Aliases

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.

Mail aliases are updated every time an EBDB buffer is created. It’s also possible to force an update using the {{{kbd(A)}}} key in a {{{buf(EBDB)}}} buffer.

vCard Support

EBDB has rudimentary support for exporting to vCard format; this functionality will be expanded in the future. After loading the @@texinfo:@file{@@ebdb-vcard@@texinfo:}@@ library, a vCard formatter will be available when formatting EBDB records (see Exporting/Formatting).

Support for importing vCard files is on the EBDB roadmap, as is, eventually, support for CardDav servers.

Org Integration

EBDB has standard support for Org functionality: creating links to 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 that initiate an EBDB search, and return multiple records. EBDB links 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. Tag Field.

This library comes with one other function that allows you to pop up an {{{buf(EBDB)}}} buffer alongside an Org 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.

It’s also possible to have EBDB anniversaries and other date notifications show up in the Org Agenda. Diary Integration.

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:

Hacking EBDB

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 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: see EIEIO for information on defining classes, and Generic Functions for information on writing generic functions and methods.

Some information about EBDB’s various classes can had from Emacs’ built-in help system: examining the function definition of a class symbol like ebdb-field-anniversary will show a documentation string, and details of the class’s slot and method definitions.

The simplest customization involves changing the default classes used for basic record and field types.

If, for instance, you’d like to create a custom mail field and have all records use that instead of the built-in one:

(defclass my-mail-field (ebdb-field-mail)
  ;; custom slots
  )

(setq ebdb-default-mail-class my-mail-field)

Note that there are currently no facilities for changing the class of existing objects. This may be addressed in the future.

Field Classes

It’s fairly easy to create your own custom field classes in EBDB. All such fields should subclass the ebdb-field-user class, which sets up basic behavior. That base class provides for no slots at all, so your class must define the slots where the field data will be held. It should also provide a class option holding a human-readable string for the class type. As an example:

(defclass ebdb-field-gender (ebdb-field-user)
  ((gender
    :initarg :gender
    :initform unknown
    :type symbol
    :custom (choice
	       (const :tag "Female" female)
	       (const :tag "Male" male)
	       (const :tag "Other" other)
	       (const :tag "Unknown" unknown)
	       (const :tag "None/Not Applicable" none))))
  :human-readable "gender"
  :documentation "A field holding gender information about this record.")

Once the class itself is defined, there are three basic methods which must be provided: ebdb-read, which prompts the user for values used to create a new field instance, ebdb-parse, which accepts a string or other data and creates a new field instance from it, and ebdb-string, 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 is 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 present, is an existing field instance that can be used to provide default values for the new object.

(cl-defmethod ebdb-read ((class (subclass ebdb-field-gender))
                         &optional slots obj)
  (unless (plist-get slots :gender)
    (let ((gender (intern (completing-read
                           "Gender: " '(female male other unknown none)
                           nil t
                           (when obj (symbol-name (slot-value obj 'gender)))))))
      (setq slots (plist-put slots :gender gender))))
  (cl-call-next-method class slots obj))

(cl-defmethod ebdb-parse ((class (subclass ebdb-field-gender))
                          str &optional slots)
  (when (and (null (plist-get slots :gender))
             (member str '("female" "male" "other" "unknown" "none")))
    (setq slots (plist-put slots :gender (intern str)))
  (cl-call-next-method class str slots))

(cl-defmethod ebdb-string ((field ebdb-field-gender))
  (symbol-name (slot-value field 'gender)))

Init and Delete Methods

It’s also very common to define ebdb-init-field and ebdb-delete-field methods for classes. These methods can be used to 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 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 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 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 delete-and-create operation).
When unloading a record from the database (the optional third @@texinfo:@var{unload}@@ argument will be non-nil).

Manipulating Field Data Programmatically

While ebdb-mode provides interactive commands for editing record data in an {{{buf(EBDB)}}} buffer, it can also be useful to do this inside Elisp functions, especially as a part of Noticing and Automatic Rules. Instead of manipulating field data directly, it’s important to go through accessors that give a record’s database(s) a chance to handle, persist, or update the field data. There are three functions for doing this:

The optional SLOT argument to the first two functions can almost always be omitted.

Two convenience functions are provided for common editing operations:

The Labeled Field Class

Many field classes maintain their own list of labels: ie, anniversary fields can be labeled “birthday”, “wedding”, etc. This functionality can be added to fields by additionally subclassing the ebdb-field-labeled class, and then defining a variable that will be used to hold labels, and pointing to it in the class-allocated “label-list” slot. Everything else is taken care of automatically.

(defvar my-field-label-list '("default1" "default2")
  "A list of labels for the my-labeled-field class.")

(defclass my-labeled-field (ebdb-field-user ebdb-field-labeled)
  ((label-list :initform my-field-label-list)))

The Singleton Field Class

Another abstract mix-in class is the ebdb-field-singleton class. Its 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

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 {{{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.

Custom Field Searching

In most cases, searching the EBDB database is a matter of prompting for a regular expression, then matching that regexp against the result of ebdb-string called on a field instance.

However, it is possible for field classes to provide more sophisticated searching behavior, if desired. When the user calls ebdb-search-user-fields in the {{{buf(EBDB)}}} buffer, he or she will be prompted for a field class to search on. When a field class is 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.

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.

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 perfectly possible to write several ebdb-field-search methods, dispatching on different criterion types, if that makes things easier.

In addition, fields that subclass ebdb-field-labeled can accept 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.

(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.

Fast Lookups

Usually, searches of the database are conducted by looping over all the records and testing each search clause against each record. Theoretically, this could be a slow process.

By contrast, “fast lookups” use a central hashtable, the ebdb-hashtable, to look up search strings quickly. By default, records names, email addresses, and tags are indexed in this central hashtable. To short-circuit the usual slow lookup and use the fast hashtable lookup, specify one of those three field names as the car of the search criteria, and prefix the string cdr of the criteria with a “^” (the behavior of all-completions requires a string prefix):

(ebdb-search (ebdb-records) '((ebdb-field-tag "^client")))

It’s possible to use these fast lookups in interactive searches, when selecting a specific field type to search on, but the time spent typing a “^” will undoubtedly outweigh the time saved in the search. This is mostly useful in non-interactive searches.

It’s also possible to specify additional field types which can be used with fast lookups. The first step is to write ebdb-init-field and ebdb-delete-field methods that hash and unhash the record against the field string in the ebdb-hashtable.

Next, add an element to the ebdb-hash-extra-predicates variable. The element should be a cons cell where the car is the field class name, as a symbol, and the cdr is a lambda which accepts the search string and a record, and returns t if the search string does indeed match the instance of that field (and not some other field string).

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.

Specify an ebdb formatter for the first argument to target {{{buf(EBDB)}}} formatting. Choices are ebdb-formatter-ebdb (for 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 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:

(cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter)
				(field ebdb-field-address)
				(_style (eql collapse))
				(_record ebdb-record))
  "Give address fields a special 'collapse formatting."
  (with-slots (streets locality country) field
   (format "%s (%s, %s)" (car streets) locality country)))

The leading underscores on parameters are there to keep the compiler quiet: the arguments are necessary for dispatch, but aren’t actually used in the body of the method.

Writing Internationalization Libraries

Writing new internationalization libraries involves using generic functions. Generic Functions. It will also require a bit of familiarity with EBDB’s internals.

Internationalization affects three different field types: addresses, phone numbers, and names. It works by providing “i18n” versions of common methods for those three fields:

Regular method	Internationalized method
ebdb-read	ebdb-read-i18n
ebdb-parse	ebdb-parse-i18n
ebdb-string	ebdb-string-i18n
ebdb-init-field	ebdb-init-field-i18n
ebdb-delete-field	ebdb-delete-field-i18n

When the “ebdb-i18n” library is loaded and the left-column (“vanilla”) versions of field methods are called, EBDB first checks to see if a valid “internationalized” (right-column) method exists. If it does, that method is used instead of the vanilla one.

What is a “valid internationalized method”? That depends on the field type. Each field type uses a different key or “spec” to determine the nationality or locality of the field instance.

Address fields use a three-character symbol derived from the ISO 316601 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 a symbol.

How are these “specs” used? Each internationalized version of the above methods accepts the spec as an additional argument, which it is 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 @@texinfo:@var{spec}@@.

Here’s a concrete example:

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 arguments. The method signature will look like this:

(cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
                                (_cc (eql 33))))

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 eql to the number 33.

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)))
  (with-slots (area-code number extension) phone
    (concat
     "+33 "
     (when area-code
       (format "%02d" area-code))
     (format "%s%s %s%s %s%s %s%s"
             (split-string number "" t))
     (when extension
       (format "X%d" extension)))))

Again this only affects the display of numbers, not how they are stored in the database.

Note that, while phone numbers themselves are stored as strings (they do not represent a quantity, after all), the country and area codes are stored as numbers, precisely so that they can be specialized on using eql.

See the signatures of the other internationalized methods for how to use them. The symbol specs for country codes and script names can also be specialized on with the eql specializer.

Writing Integration For New MUAs

Theoretically EBDB can be incorporated into any Emacs package, but it’s most commonly used in conjunction with a mail user agent. It comes with support for a few MUAs out of the box, but integration with a new one can be written fairly easily.

The first step of integration involves hooking the function ebdb-mua-auto-update somewhere into the MUA’s operation. For most MUAs, the appropriate place is when a message or article is opened for viewing by the user. This allows EBDB to act on the information found in that message.

The second step requires providing new versions of a handful of generic functions. All MUA-specific generic functions specialize on the current major-mode, using the &context specializer. See below for examples.

When ebdb-mua-auto-update runs, it scans the headers of the current article/message for name/mail data, and uses that data to locate, create, edit, and display records. It does this by calling the generic function ebdb-mua-message-header with the string header name; it is the responsibility of the MUA to implement this function, and return the contents of the appropriate header. For instance, in Gnus:

(cl-defmethod ebdb-mua-message-header ((header string)
                                   &context (major-mode gnus-summary-mode))
  "Return value of HEADER for current Gnus message."
  (set-buffer gnus-article-buffer)
  (gnus-fetch-original-field header))

The first argument is the string header, and the second is the specializer on the current major-mode. Possible header values include those found in ebdb-message-headers. Note that if you expect this function to be called in more than one major-mode, you’ll have to provide multiple versions of the function. The &context specializer uses derived-mode-p behind the scenes, though, so if all the modes derive from a single parent mode (and the behavior should be the same in all derived modes) it is enough to specialize on the parent mode.

Some MUAs might need to do a bit of work to ensure that the article in question is opened and set up properly:

Providing {{{buf(EBDB)}}} buffer pop-up support involves implementing two separate functions:

In addition, it might be nice to bind the ebdb-mua-keymap in the MUA’s mode-map. This map provides bindings for some commonly-used EBDB functions.

Article snarfing

EBDB can scan articles or messages for likely field information, and prompt the user to add the fields to new or existing records—this is done by the user with the interactive command ebdb-mua-snarf-article. In order to work, the MUA must be able to provide that function with the text of the message body, and the text of the message signature (if any). This is done with two generic functions:

Files

ebdb.org

Latest commit

History