[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/ebdb 534d3b7 298/350: Start tracking manual texi and in
|
From: |
Eric Abrahamsen |
|
Subject: |
[elpa] externals/ebdb 534d3b7 298/350: Start tracking manual texi and info files |
|
Date: |
Mon, 14 Aug 2017 11:46:58 -0400 (EDT) |
branch: externals/ebdb
commit 534d3b73634c3bf49d544183da6f433a1b4e710c
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>
Start tracking manual texi and info files
* ebdb.info:
* ebdb.texi: Track new files
---
ebdb.info | 1415 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ebdb.texi | 1390 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 2805 insertions(+)
diff --git a/ebdb.info b/ebdb.info
new file mode 100644
index 0000000..7da1454
--- /dev/null
+++ b/ebdb.info
@@ -0,0 +1,1415 @@
+This is ebdb.info, produced by makeinfo version 6.4 from ebdb.texi.
+
+Copyright © 2016 Free Software Foundation, Inc.
+
+ 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.”
+INFO-DIR-SECTION Emacs
+START-INFO-DIR-ENTRY
+* EBDB: (ebdb). Contact management package.
+END-INFO-DIR-ENTRY
+
+
+File: ebdb.info, Node: Top, Next: Getting Started, Up: (dir)
+
+EBDB Manual
+***********
+
+* Menu:
+
+* Getting Started::
+* The EBDB Database::
+* Creating Records::
+* Record Fields::
+* MUA Interaction::
+* *EBDB* Buffers::
+* Snarfing::
+* Internationalization::
+* Diary Integration::
+* Mail Aliases::
+* vCard Support::
+* Hacking EBDB::
+* Index::
+
+— The Detailed Node Listing —
+
+Getting Started
+
+* Migration from BBDB::
+
+Migration from BBDB
+
+* Record Migration::
+* Variables and Options::
+
+
+Creating Records
+
+* Record classes::
+* Record names::
+
+
+
+Record Fields
+
+* Inserting new fields::
+* Editing existing fields::
+* Deleting records and fields::
+* Field types::
+
+
+
+MUA Interaction
+
+* Loading MUA Code::
+* Display and Updating::
+* EBDB and MUA summary buffers::
+
+
+Display and Updating
+
+* Pop-up Buffers::
+* Auto-Updating Records::
+* Noticing and Automatic Rules::
+* Interactive Commands::
+
+
+EBDB and MUA summary buffers
+
+* Sender name display::
+* Summary buffer marks::
+
+*EBDB* Buffers
+
+* Searching::
+* Marking::
+* Exporting/Formatting::
+
+Searching
+
+* Changing Search Behavior::
+
+
+
+
+
+
+Hacking EBDB
+
+* Field Classes::
+
+Field Classes
+
+* Init and Delete Methods::
+* The Labeled Field Class::
+* Actions::
+* Custom Field Searching::
+* Formatting in the EBDB Buffer::
+
+
+File: ebdb.info, Node: Getting Started, Next: The EBDB Database, Prev: Top,
Up: Top
+
+1 Getting Started
+*****************
+
+Assuming you have no records you want to migrate from other contact
+management software, it is enough to call the top-level ‘ebdb’ command.
+This will create a new database at the location specified by
+‘ebdb-sources’ (see *note The EBDB Database::), prompt you for a search
+string, fail to find anything (because you don’t have any records yet),
+and lastly open a *EBDB* buffer where you can start to make new records
+(see *note Creating Records::).
+
+* Menu:
+
+* Migration from BBDB::
+
+
+File: ebdb.info, Node: Migration from BBDB, Up: Getting Started
+
+1.1 Migration from BBDB
+=======================
+
+* Menu:
+
+* Record Migration::
+* Variables and Options::
+
+
+File: ebdb.info, Node: Record Migration, Next: Variables and Options, Up:
Migration from BBDB
+
+1.1.1 Record Migration
+----------------------
+
+It’s possible to migrate records from a BBDB file. With your BBDB
+customizations still in place, set ‘ebdb-sources’ to a non-existent file
+name, and then run ‘ebdb-load’ (or any of the other EBDB entry
+commands). You’ll be prompted to create the new database, and upgrade
+from BBDB. If any records could not be upgraded, they will be displayed
+in an *EBDB Migration* buffer.
+
+
+File: ebdb.info, Node: Variables and Options, Prev: Record Migration, Up:
Migration from BBDB
+
+1.1.2 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.
+
+
+File: ebdb.info, Node: The EBDB Database, Next: Creating Records, Prev:
Getting Started, Up: Top
+
+2 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: 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.
+
+ 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 *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’.
+
+ 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.
+
+‘d e’ (‘ebdb-customize-database db’)
+
+ Use the customize interface to edit the definition of DB.
+
+ 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.
+
+‘d m’ (‘ebdb-move-record record to-db’)
+
+ Move RECORD from its existing database to TO-DB.
+
+‘d c’ (‘ebdb-copy-record record to-db’)
+
+ Copy RECORD into TO-DB, leaving it in its existing database(s).
+
+ Other database-related commands:
+
+‘d r’ (‘ebdb-reload-database db’)
+
+ 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’)
+
+ 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’.
+
+
+File: ebdb.info, Node: Creating Records, Next: Record Fields, Prev: The
EBDB Database, Up: Top
+
+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’.
+
+ -- User Option: ebdb-default-record-class
+
+ The default record class to use when creating new records.
+
+ 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.
+
+ 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.
+
+ Currently this option’s only use is to serve as a source for
+‘ebdb-user-mail-address-re’.
+
+* Menu:
+
+* Record classes::
+* Record names::
+
+
+File: ebdb.info, Node: Record classes, Next: Record names, Up: Creating
Records
+
+3.1 Record classes
+==================
+
+EBDB comes with two record classes, representing individuals
+(‘ebdb-record-person’) and organizations (‘ebdb-record-organization’).
+
+
+File: ebdb.info, Node: Record names, Prev: Record classes, Up: Creating
Records
+
+3.2 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”.
+
+
+File: ebdb.info, Node: Record Fields, Next: MUA Interaction, Prev: Creating
Records, Up: Top
+
+4 Record Fields
+***************
+
+* Menu:
+
+* Inserting new fields::
+* Editing existing fields::
+* Deleting records and fields::
+* Field types::
+
+
+File: ebdb.info, Node: Inserting new fields, Next: Editing existing fields,
Up: Record Fields
+
+4.1 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.
+
+ 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”.
+
+
+File: ebdb.info, Node: Editing existing fields, Next: Deleting records and
fields, Prev: Inserting new fields, Up: Record Fields
+
+4.2 Editing existing 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.
+
+
+File: ebdb.info, Node: Deleting records and fields, Next: Field types,
Prev: Editing existing fields, Up: Record Fields
+
+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
+will instead prompt to delete the whole record.
+
+
+File: ebdb.info, Node: Field types, Prev: Deleting records and fields, Up:
Record Fields
+
+4.4 Field types
+===============
+
+:ID: cb2190f4-f2e6-4082-9671-24e11e5cc0c6 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
+*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
+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).
+
+ Loading secondary libraries may make more field types available.
+
+
+File: ebdb.info, Node: MUA Interaction, Next: *EBDB* Buffers, Prev: Record
Fields, Up: Top
+
+5 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.
+
+* Menu:
+
+* Loading MUA Code::
+* Display and Updating::
+* EBDB and MUA summary buffers::
+
+
+File: ebdb.info, Node: Loading MUA Code, Next: Display and Updating, Up:
MUA Interaction
+
+5.1 Loading MUA Code
+====================
+
+:ORDERED: t 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.
+
+
+File: ebdb.info, Node: Display and Updating, Next: EBDB and MUA summary
buffers, Prev: Loading MUA Code, Up: MUA Interaction
+
+5.2 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.
+
+* Menu:
+
+* Pop-up Buffers::
+* Auto-Updating Records::
+* Noticing and Automatic Rules::
+* Interactive Commands::
+
+
+File: ebdb.info, Node: Pop-up Buffers, Next: Auto-Updating Records, Up:
Display and Updating
+
+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.
+
+ -- 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
+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.
+
+
+File: ebdb.info, Node: Auto-Updating Records, Next: Noticing and Automatic
Rules, Prev: Pop-up Buffers, Up: Display and Updating
+
+5.2.2 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:
+
+ -- 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.
+
+ 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.
+
+ -- 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
+
+ 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’.
+
+
+File: ebdb.info, Node: Noticing and Automatic Rules, Next: Interactive
Commands, Prev: Auto-Updating Records, Up: Display and Updating
+
+5.2.3 Noticing and Automatic Rules
+----------------------------------
+
+In addition to updating records’ name and mail fields, it’s possible to
+run other arbitrary edits on records when they are referenced in a
+message. This process is called “noticing”. Two hooks are run as a
+part of noticing:
+
+ -- User Option: ebdb-notice-record-hook
+
+ This hook is run once per record noticed, with two arguments: the
+ record, and one of the symbols ’sender and ’recipient, indicating
+ where in the message headers the record was found.
+
+ -- User Option: ebdb-notice-mail-hook
+
+ This hook is run once per mail message noticed: if multiple
+ addresses belong to a single record, it will be called once per
+ address. The hook is run with one argument: the record.
+
+ When a record is noticed, it will also call the method
+‘ebdb-notice-field’ on all of its fields. Using this method requires a
+bit of familiarity with *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.
+
+
+File: ebdb.info, Node: Interactive Commands, Prev: Noticing and Automatic
Rules, Up: Display and Updating
+
+5.2.4 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-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-pop-up’ is nil, this command can be used to
+ do the same thing.
+
+‘'’ (‘ebdb-mua-edit-sender-notes’)
+
+ This command allows you to edit the notes field of the message
+ sender.
+
+‘``’ (‘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.
+
+‘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 *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.
+
+
+File: ebdb.info, Node: EBDB and MUA summary buffers, Prev: Display and
Updating, Up: MUA Interaction
+
+5.3 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.
+
+* Menu:
+
+* Sender name display::
+* Summary buffer marks::
+
+
+File: ebdb.info, Node: Sender name display, Next: Summary buffer marks, Up:
EBDB and MUA summary buffers
+
+5.3.1 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 and
+VM, which allow for overriding how message senders are displayed. The
+format letter (see below) should be added to ‘gnus-summary-line-format’
+for Gnus (which see), and ‘vm-summary-format’ for VM (ditto).
+
+ -- User Option: ebdb-message-clean-name-function
+
+ 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”.
+
+
+File: ebdb.info, Node: Summary buffer marks, Prev: Sender name display, Up:
EBDB and MUA summary buffers
+
+5.3.2 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:
+
+ -- 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.
+
+ • Field class: ebdb-field-summary-mark
+
+ Give a record an instance of this field class to use a 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:
+
+ -- 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”.
+
+
+File: ebdb.info, Node: *EBDB* Buffers, Next: Snarfing, Prev: MUA
Interaction, Up: Top
+
+6 *EBDB* Buffers
+****************
+
+EBDB buffers inherit from special-mode, and so the usual special-mode
+keybindings apply.
+
+ EBDB can create several separate buffers for displaying contacts.
+Typically, each MUA creates its own buffer, with names like *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.
+
+ -- 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’)
+
+ Prompt for a buffer name, and create a new EBDB buffer displaying
+ the same records as the original buffer.
+
+‘b r’ (‘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.
+
+* Menu:
+
+* Searching::
+* Marking::
+* Exporting/Formatting::
+
+
+File: ebdb.info, Node: Searching, Next: Marking, Up: *EBDB* Buffers
+
+6.1 Searching
+=============
+
+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
+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
+
+ Each user-created *EBDB* buffer keeps track of search history in that
+buffer. To pop back to previous searches, use:
+
+‘^’ (‘ebdb-search-pop’)
+
+* Menu:
+
+* Changing Search Behavior::
+
+
+File: ebdb.info, Node: Changing Search Behavior, Up: Searching
+
+6.1.1 Changing Search Behavior
+------------------------------
+
+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.
+
+ 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.
+
+
+File: ebdb.info, Node: Marking, Next: Exporting/Formatting, Prev:
Searching, Up: *EBDB* Buffers
+
+6.2 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.
+
+
+File: ebdb.info, Node: Exporting/Formatting, Prev: Marking, Up: *EBDB*
Buffers
+
+6.3 Exporting/Formatting
+========================
+
+It is possible to export (referred to as “formatting”) records in
+various ways. The most common export format is that of the *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’ (‘ebdb-format-to-tmp-buffer’)
+
+ 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’)
+
+ Export all records in the database (not only those displayed) to a
+ different format.
+
+ It’s possible to write new formatters, documentation is forthcoming.
+
+
+File: ebdb.info, Node: Snarfing, Next: Internationalization, Prev: *EBDB*
Buffers, Up: Top
+
+7 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 <address@hidden>” will
+find an existing matching contact, or prompt to create a new contact,
+and then display it.
+
+ Snarfing is a work in progress: at present, only mail addresses (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.
+
+ 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.
+
+
+File: ebdb.info, Node: Internationalization, Next: Diary Integration, Prev:
Snarfing, Up: Top
+
+8 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 ‘ebdb-i10n’ library. This
+library does nothing by itself, it simply provides hooks for other
+country-specific libraries, which must be loaded separately.
+
+ At present, EBDB comes with only one country-specific library,
+‘ebdb-chn’, 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 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. Also
+welcome, though less enthusiastically, are requests for new libraries.
+
+ Internationalization libraries do not modify the database in any way,
+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.
+
+
+File: ebdb.info, Node: Diary Integration, Next: Mail Aliases, Prev:
Internationalization, Up: Top
+
+9 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 (and from there to Org, via the
+‘org-agenda-include-diary’ option). At present, you’ll need to have 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.
+
+ 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
+are forthcoming.
+
+
+File: ebdb.info, Node: Mail Aliases, Next: vCard Support, Prev: Diary
Integration, Up: Top
+
+10 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.
+
+ 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.
+
+
+File: ebdb.info, Node: vCard Support, Next: Hacking EBDB, Prev: Mail
Aliases, Up: Top
+
+11 vCard Support
+****************
+
+EBDB has rudimentary support for exporting to vCard format; this
+functionality will be expanded in the future. After loading the
+‘ebdb-vcard’ library, a vCard formatter will be available when
+formatting EBDB records (see *note Exporting/Formatting::).
+
+ Support for importing vCard files is on the EBDB roadmap, as is,
+eventually, support for CardDav servers.
+
+
+File: ebdb.info, Node: Hacking EBDB, Next: Index, Prev: vCard Support, Up:
Top
+
+12 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 *note EIEIO: (eieio)Top. for information on defining classes, and
+*note Generic Functions: (elisp)Generic%20Functions. 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.
+
+ 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.
+
+* Menu:
+
+* Field Classes::
+
+
+File: ebdb.info, Node: Field Classes, Up: Hacking EBDB
+
+12.1 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 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)))
+
+* Menu:
+
+* Init and Delete Methods::
+* The Labeled Field Class::
+* Actions::
+* Custom Field Searching::
+* Formatting in the EBDB Buffer::
+
+
+File: ebdb.info, Node: Init and Delete Methods, Next: The Labeled Field
Class, Up: Field Classes
+
+12.1.1 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 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.
+
+ 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
+ “unload” argument will be non-nil).
+
+
+File: ebdb.info, Node: The Labeled Field Class, Next: Actions, Prev: Init
and Delete Methods, Up: Field Classes
+
+12.1.2 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)))
+
+
+File: ebdb.info, Node: Actions, Next: Custom Field Searching, Prev: The
Labeled Field Class, Up: Field Classes
+
+12.1.3 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.
+
+ The functions in this list should accept two arguments, the record
+and the field instance under point.
+
+
+File: ebdb.info, Node: Custom Field Searching, Next: Formatting in the EBDB
Buffer, Prev: Actions, Up: Field Classes
+
+12.1.4 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 *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.
+
+
+File: ebdb.info, Node: Formatting in the EBDB Buffer, Prev: Custom Field
Searching, Up: Field Classes
+
+12.1.5 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.
+
+ Specify an ebdb formatter for the first argument to target *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.
+
+
+File: ebdb.info, Node: Index, Prev: Hacking EBDB, Up: Top
+
+Index
+*****
+
+ [index ]
+* Menu:
+
+* Creating a database: The EBDB Database. (line 11)
+* Creating records: Creating Records. (line 6)
+* Deleting records and fields: Deleting records and fields.
+ (line 6)
+* Diary integration: Diary Integration. (line 6)
+* ebdb-clone-buffer: *EBDB* Buffers. (line 22)
+* ebdb-copy-record record to-db: The EBDB Database. (line 65)
+* ebdb-customize-database db: The EBDB Database. (line 51)
+* ebdb-disable-database db: The EBDB Database. (line 76)
+* ebdb-format-all-records: Exporting/Formatting. (line 20)
+* ebdb-format-to-tmp-buffer: Exporting/Formatting. (line 14)
+* ebdb-move-record record to-db: The EBDB Database. (line 61)
+* ebdb-mua-display-all-recipients: Interactive Commands. (line 63)
+* ebdb-mua-display-all-records: Interactive Commands. (line 18)
+* ebdb-mua-display-recipients: Interactive Commands. (line 59)
+* ebdb-mua-display-sender: Interactive Commands. (line 55)
+* ebdb-mua-edit-sender-notes: Interactive Commands. (line 23)
+* ebdb-mua-in-ebdb-buffer: Interactive Commands. (line 28)
+* ebdb-mua-snarf-article: Interactive Commands. (line 36)
+* ebdb-mua-snarf-article <1>: Snarfing. (line 42)
+* ebdb-mua-update-records: Interactive Commands. (line 12)
+* ebdb-mua-yank-cc: Interactive Commands. (line 46)
+* ebdb-reload-database db: The EBDB Database. (line 71)
+* ebdb-rename-buffer: *EBDB* Buffers. (line 27)
+* ebdb-search-pop: Searching. (line 47)
+* ebdb-snarf &optional string start end recs: Snarfing. (line 15)
+* Editing fields: Editing existing fields.
+ (line 6)
+* Inserting new fields: Inserting new fields. (line 6)
+* Internationalization: Internationalization. (line 6)
+* Mail aliases: Mail Aliases. (line 6)
+* Migrating from BBDB: Migration from BBDB. (line 6)
+* Searching the EBDB: Searching. (line 6)
+* Snarfing text: Snarfing. (line 6)
+
+
+
+Tag Table:
+Node: Top806
+Node: Getting Started2070
+Node: Migration from BBDB2692
+Node: Record Migration2867
+Node: Variables and Options3404
+Node: The EBDB Database3890
+Node: Creating Records6950
+Node: Record classes7997
+Node: Record names8263
+Node: Record Fields8938
+Node: Inserting new fields9182
+Node: Editing existing fields9978
+Node: Deleting records and fields10578
+Node: Field types10974
+Node: MUA Interaction12793
+Node: Loading MUA Code13319
+Node: Display and Updating13946
+Node: Pop-up Buffers14715
+Node: Auto-Updating Records15580
+Node: Noticing and Automatic Rules17965
+Node: Interactive Commands19308
+Node: EBDB and MUA summary buffers21797
+Node: Sender name display22283
+Node: Summary buffer marks23571
+Node: *EBDB* Buffers24766
+Node: Searching26028
+Node: Changing Search Behavior27609
+Node: Marking28859
+Node: Exporting/Formatting29275
+Node: Snarfing30236
+Node: Internationalization32144
+Node: Diary Integration33569
+Node: Mail Aliases34433
+Node: vCard Support35142
+Node: Hacking EBDB35638
+Node: Field Classes37887
+Node: Init and Delete Methods40777
+Node: The Labeled Field Class42333
+Node: Actions43169
+Node: Custom Field Searching43834
+Node: Formatting in the EBDB Buffer45622
+Node: Index47621
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End:
diff --git a/ebdb.texi b/ebdb.texi
new file mode 100644
index 0000000..b3d9673
--- /dev/null
+++ b/ebdb.texi
@@ -0,0 +1,1390 @@
+\input texinfo @c -*- texinfo -*-
address@hidden %**start of header
address@hidden ./ebdb.info
address@hidden EBDB Manual
address@hidden UTF-8
address@hidden en
address@hidden pg cp
address@hidden %**end of header
+
address@hidden
+Copyright @copyright{} 2016 Free Software Foundation, Inc.
+
address@hidden
+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.”
address@hidden quotation
address@hidden copying
+
address@hidden Emacs
address@hidden
+* EBDB: (ebdb). Contact management package.
address@hidden direntry
+
address@hidden
address@hidden
address@hidden EBDB Manual
address@hidden This manual is for version 0.2, updated 28 July, 2017
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top
address@hidden EBDB Manual
address@hidden ifnottex
+
address@hidden
+* Getting Started::
+* The EBDB Database::
+* Creating Records::
+* Record Fields::
+* MUA Interaction::
+* *EBDB* Buffers::
+* Snarfing::
+* Internationalization::
+* Diary Integration::
+* Mail Aliases::
+* vCard Support::
+* Hacking EBDB::
+* Index::
+
address@hidden
+--- The Detailed Node Listing ---
+
+Getting Started
+
+* Migration from BBDB::
+
+Migration from BBDB
+
+* Record Migration::
+* Variables and Options::
+
+
+Creating Records
+
+* Record classes::
+* Record names::
+
+
+
+Record Fields
+
+* Inserting new fields::
+* Editing existing fields::
+* Deleting records and fields::
+* Field types::
+
+
+
+MUA Interaction
+
+* Loading MUA Code::
+* Display and Updating::
+* EBDB and MUA summary buffers::
+
+
+Display and Updating
+
+* Pop-up Buffers::
+* Auto-Updating Records::
+* Noticing and Automatic Rules::
+* Interactive Commands::
+
+
+EBDB and MUA summary buffers
+
+* Sender name display::
+* Summary buffer marks::
+
+*EBDB* Buffers
+
+* Searching::
+* Marking::
+* Exporting/Formatting::
+
+Searching
+
+* Changing Search Behavior::
+
+
+
+
+
+
+Hacking EBDB
+
+* Field Classes::
+
+Field Classes
+
+* Init and Delete Methods::
+* The Labeled Field Class::
+* Actions::
+* Custom Field Searching::
+* Formatting in the EBDB Buffer::
address@hidden detailmenu
address@hidden menu
+
address@hidden Getting Started
address@hidden Getting Started
+
+Assuming you have no records you want to migrate from other contact
+management software, it is enough to call the top-level @code{ebdb}
+command. This will create a new database at the location specified by
address@hidden (see @ref{The EBDB Database}), prompt you for a search
+string, fail to find anything (because you don't have any records
+yet), and lastly open a *EBDB* buffer where you can start to
+make new records (see @ref{Creating Records}).
+
address@hidden
+* Migration from BBDB::
address@hidden menu
+
address@hidden Migration from BBDB
address@hidden Migration from BBDB
+
address@hidden Migrating from BBDB
+
address@hidden
+* Record Migration::
+* Variables and Options::
address@hidden menu
+
address@hidden Record Migration
address@hidden Record Migration
+
+It's possible to migrate records from a BBDB file. With your BBDB
+customizations still in place, set @code{ebdb-sources} to a non-existent
+file name, and then run @code{ebdb-load} (or any of the other EBDB entry
+commands). You'll be prompted to create the new database, and upgrade
+from BBDB. If any records could not be upgraded, they will be
+displayed in an *EBDB Migration* buffer.
+
address@hidden Variables and Options
address@hidden 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.
+
address@hidden The EBDB Database
address@hidden The EBDB Database
+
+EBDB supports multiple databases, and each database definition is
+saved in a file on disk. The default database class, @code{ebdb-db-file},
+stores its contacts in the same file as the database itself, though
+other database classes may store contacts elsewhere.
+
address@hidden Creating a database
address@hidden 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.
address@hidden 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
+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 buffer-char
+
+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
+
+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
address@hidden below.
address@hidden defopt
+
address@hidden 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
+
+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 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.
address@hidden 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''
+field, and the older copy is discarded.
+
address@hidden @asis
address@hidden 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.
+
address@hidden 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).
address@hidden table
+
+Other database-related commands:
+
address@hidden @asis
address@hidden 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.
+
address@hidden 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}.
address@hidden table
+
address@hidden Creating Records
address@hidden Creating Records
+
address@hidden 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
+default record class, in the database at the head of @code{ebdb-sources}.
+
address@hidden ebdb-default-record-class
+
+The default record class to use when creating new records.
address@hidden 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.
+
+You can also tell EBDB which record represents you:
+
address@hidden 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.
address@hidden defopt
+
+Currently this option's only use is to serve as a source for
address@hidden
+
address@hidden
+* Record classes::
+* Record names::
address@hidden menu
+
address@hidden Record classes
address@hidden Record classes
+
+EBDB comes with two record classes, representing individuals
+(@code{ebdb-record-person}) and organizations
(@code{ebdb-record-organization}).
+
address@hidden Record names
address@hidden 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''.
+
address@hidden Record Fields
address@hidden Record Fields
+
address@hidden
+* Inserting new fields::
+* Editing existing fields::
+* Deleting records and fields::
+* Field types::
address@hidden menu
+
address@hidden Inserting new fields
address@hidden Inserting new fields
+
address@hidden 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.
+
+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''.
+
address@hidden Editing existing fields
address@hidden Editing existing fields
+
address@hidden 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.
+
+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 Deleting records and fields
address@hidden 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 Field types
address@hidden Field types
+
+:ID: cb2190f4-f2e6-4082-9671-24e11e5cc0c6
+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.
+
+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).
+
+Loading secondary libraries may make more field types available.
+
address@hidden MUA Interaction
address@hidden 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.
+
address@hidden
+* Loading MUA Code::
+* Display and Updating::
+* EBDB and MUA summary buffers::
address@hidden menu
+
address@hidden Loading MUA Code
address@hidden Loading MUA Code
+
+:ORDERED: t
+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:
+
address@hidden
+(require 'ebdb-gnus)
+(require 'ebdb-message)
address@hidden lisp
+
+There are other packages that provide other MUA integration: these are
+likewise activated simply by requiring the relevant library.
+
address@hidden Display and Updating
address@hidden 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:
+
address@hidden
address@hidden
+Pop up a buffer displaying the records.
+
address@hidden
+Create new records, or alter existing records, based on information
+provided by the MUA.
+
address@hidden
+Run automatic rules to edit the records.
+
address@hidden
+Provide keybindings to manually edit the records.
address@hidden itemize
+
+Each of these functionalities is optional, and can be customized
+independently of the others.
+
address@hidden
+* Pop-up Buffers::
+* Auto-Updating Records::
+* Noticing and Automatic Rules::
+* Interactive Commands::
address@hidden menu
+
address@hidden Pop-up Buffers
address@hidden 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.
+
address@hidden 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).
address@hidden 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.
+
address@hidden Auto-Updating Records
address@hidden 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:
+
address@hidden 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.
address@hidden 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:
+
address@hidden ebdb-add-name
+
+Whether to automatically change record names. See docstring for
+details.
address@hidden defopt
+
address@hidden ebdb-add-aka
+
+Whether to automatically add new names as akas. See docstring for
+details.
address@hidden defopt
+
address@hidden ebdb-add-mails
+
+How to handle apparently new mail addresses. See docstring for
+details.
address@hidden defopt
+
+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 defopt
+
address@hidden ebdb-ignore-header-alist
+
+An alist governing which addresses in which headers will be ignored.
+See docstring for details.
address@hidden defopt
+
address@hidden 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 @code{message-alternative-emails}, or
+the symbol 'self, in which case the value will be constructed from
+the record pointed to by the option @code{ebdb-record-self}.
address@hidden defopt
+
address@hidden Noticing and Automatic Rules
address@hidden 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:
+
address@hidden 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.
address@hidden defopt
+
address@hidden 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.
address@hidden defopt
+
+When a record is noticed, it will also call the method
address@hidden 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.
+
address@hidden Interactive Commands
address@hidden 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 @code{ebdb-mua-display-records}.
+
address@hidden @asis
address@hidden :
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 ;
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 '
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 s
address@hidden ebdb-mua-snarf-article
address@hidden @kbd{s}
@address@hidden@address@hidden(@code{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.
+
address@hidden table
+
address@hidden ebdb-mua-yank-cc
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
+composed. This command is not bound by default, because the EBDB
+keymap is not bound by default in message composition MUAs.
address@hidden deffn
+
+Other commands that are not bound to any keys by default:
+
address@hidden ebdb-mua-display-sender
address@hidden Command ebdb-mua-display-sender
+
+Only display the sender.
address@hidden deffn
+
address@hidden ebdb-mua-display-recipients
address@hidden Command ebdb-mua-display-recipients
+
+Only display the recipients.
address@hidden deffn
+
address@hidden ebdb-mua-display-all-recipients
address@hidden Command ebdb-mua-display-all-recipients
+
+Only display recipients, using all mail addresses from the message.
address@hidden deffn
+
address@hidden EBDB and MUA summary buffers
address@hidden 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.
+
address@hidden
+* Sender name display::
+* Summary buffer marks::
address@hidden menu
+
address@hidden Sender name display
address@hidden 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 and
+VM, which allow 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 ebdb-message-clean-name-function
+
+A function used to clean up the name extracted from the headers of a
+message.
address@hidden defopt
+
address@hidden ebdb-message-mail-as-name
+
+If non-nil, the mail address will be used as a fallback for new
+record names.
address@hidden defopt
+
address@hidden 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.
address@hidden defopt
+
address@hidden 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''.
address@hidden defopt
+
address@hidden Summary buffer marks
address@hidden 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:
+
address@hidden 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.
address@hidden defopt
+
address@hidden 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.
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
+
+Marks are displayed in MUA summary buffers by customizing the format
+string provided by Gnus or VM, and adding the EBDB-specific format
+code:
+
address@hidden ebdb-mua-summary-mark-format-letter
+
+Format letter to use in the summary buffer format string to mark a
+record. Defaults to ``e''.
address@hidden defopt
+
address@hidden *EBDB* Buffers
address@hidden *EBDB* Buffers
+
+EBDB buffers inherit from special-mode, and so the usual special-mode
+keybindings apply.
+
+EBDB can create several separate buffers for displaying contacts.
+Typically, each MUA creates its own buffer, with names like
+*EBDB-Gnus*, etc. Users can also create their own buffers
+that won't be interfered with by MUA pop-up action. Calling the
address@hidden command directly will create such a ``user-owned'' buffer; it's
+also possible to create more by using the @code{ebdb-clone-buffer} and
address@hidden commands within existing EBDB buffers.
+
address@hidden ebdb-buffer-name
+
+The base string that is used to create EBDB buffers, without
+asterisks. Defaults to ``EBDB''.
address@hidden defopt
+
address@hidden @asis
address@hidden b c
address@hidden ebdb-clone-buffer
address@hidden @kbd{b c}
@address@hidden@address@hidden(@code{ebdb-clone-buffer})
+
+Prompt for a buffer name, and create a new EBDB buffer displaying
+the same records as the original buffer.
+
address@hidden 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 table
+
address@hidden
+* Searching::
+* Marking::
+* Exporting/Formatting::
address@hidden menu
+
address@hidden Searching
address@hidden Searching
+
address@hidden Searching the EBDB
+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
+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
+database
address@hidden itemize
+
+Search commands that currently only work with the ``/'' prefix are:
+
address@hidden
address@hidden
+``/ 1'': Prompt for a single record, and display it
+
address@hidden
+``/ d'': Search duplicate records
address@hidden itemize
+
+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 ^
address@hidden ebdb-search-pop
address@hidden @kbd{^} @address@hidden@address@hidden(@code{ebdb-search-pop})
address@hidden table
+
address@hidden
+* Changing Search Behavior::
address@hidden menu
+
address@hidden Changing Search Behavior
address@hidden Changing Search Behavior
+
+There are three ways to alter the behavior of EBDB searches.
+
address@hidden ebdb-case-fold-search
+
+An equivalent to the regular @code{case-fold-search} variable, which
+see. Defaults to the value of that variable.
address@hidden defopt
+
address@hidden ebdb-char-fold-search
+
+Controls whether character folding is used when matching search
+strings against record values.
address@hidden defopt
+
address@hidden 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.
address@hidden defopt
+
+Be careful of potential interaction between character folding and
+transform functions. Character folding works by calling
address@hidden 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.
+
address@hidden Marking
address@hidden 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.
+
address@hidden Exporting/Formatting
address@hidden Exporting/Formatting
+
+It is possible to export (referred to as ``formatting'') records in
+various ways. The most common export format is that of the
+*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.
+
address@hidden @asis
address@hidden 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 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 table
+
+It's possible to write new formatters, documentation is forthcoming.
+
address@hidden Snarfing
address@hidden Snarfing
+
address@hidden Snarfing text
+``Snarfing'' refers to scanning free-form text and extracting
+information related to EBDB records from it. For example, calling
address@hidden while the region contains the text ``John Doe
+<j.doe@@email.com>'' will find an existing matching contact, or prompt
+to create a new contact, and then display it.
+
+Snarfing is a work in progress: at present, only mail addresses (and
+nearby names) are acted upon, and it often doesn't work correctly.
+
address@hidden ebdb-snarf &optional string start end recs
address@hidden 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.
address@hidden deffn
+
address@hidden 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.
address@hidden defopt
+
address@hidden 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.
address@hidden defopt
+
+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
+
+Snarf the body of the current article. This will also snarf the
+headers of forwarded emails.
address@hidden deffn
+
address@hidden Internationalization
address@hidden Internationalization
+
address@hidden 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
address@hidden library. This library does
+nothing by itself, it simply provides hooks for other country-specific
+libraries, which must be loaded separately.
+
+At present, EBDB comes with only one country-specific library,
address@hidden, 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 requires the
address@hidden 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. Also
+welcome, though less enthusiastically, are requests for new libraries.
+
+Internationalization libraries do not modify the database in any way,
+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.
+
address@hidden Diary Integration
address@hidden Diary Integration
+
address@hidden Diary integration
+Some EBDB fields hold dates or anniversaries (most notably the
address@hidden field). It's possible to integrate this
+information with Emacs' diary package (and from there to Org, via the
address@hidden option). At present, you'll need to have
+an actual diary file present at the location indicated by
address@hidden, though the file can be blank.
+
address@hidden ebdb-use-diary
+
+If non-nil, EBDB fields with date information will attempt to add
+that information to the diary.
address@hidden defopt
+
+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
+are forthcoming.
+
address@hidden Mail Aliases
address@hidden Mail Aliases
+
address@hidden 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.
+
+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 vCard Support
address@hidden vCard Support
+
+EBDB has rudimentary support for exporting to vCard format; this
+functionality will be expanded in the future. After loading the
address@hidden library, a vCard formatter
+will be available when formatting EBDB records (see
address@hidden/Formatting}).
+
+Support for importing vCard files is on the EBDB roadmap, as is,
+eventually, support for CardDav servers.
+
address@hidden Hacking EBDB
address@hidden 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 @ref{Top,EIEIO,,eieio,} for information on defining classes, and
@ref{Generic%20Functions,Generic Functions,,elisp,}
+for information on writing generic functions and methods.
+
+The simplest customization involves changing the default classes used
+for basic record and field types.
+
address@hidden 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.
address@hidden defopt
+
address@hidden 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.
address@hidden defopt
+
address@hidden ebdb-default-mail-class
+
+The default class for mail fields.
address@hidden defopt
+
address@hidden ebdb-default-phone-class
+
+The default class for phone fields.
address@hidden defopt
+
address@hidden ebdb-default-address-class
+
+The default class for address fields.
address@hidden defopt
+
address@hidden ebdb-default-notes-class
+
+The default class for notes fields.
address@hidden 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:
+
address@hidden
+(defclass my-mail-field (ebdb-field-mail)
+ ;; custom slots
+ )
+
+(setq ebdb-default-mail-class my-mail-field)
address@hidden lisp
+
+Note that there are currently no facilities for changing the class of
+existing objects. This may be addressed in the future.
+
address@hidden
+* Field Classes::
address@hidden menu
+
address@hidden Field Classes
address@hidden Field Classes
+
+It's fairly easy to create your own custom field classes in EBDB. All
+such fields should subclass the @code{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:
+
address@hidden
+(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.")
address@hidden lisp
+
+Once the class itself is defined, there are three basic methods which
+must be provided: @code{ebdb-read}, which prompts the user for values used
+to create a new field instance, @code{ebdb-parse}, which accepts a string
+or other data and creates a new field instance from it, and
address@hidden, which returns a string representation of the field
+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
+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,
+which, if present, is an existing field instance that can be used to
+provide default values for the new object.
+
address@hidden
+(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)))
address@hidden lisp
+
address@hidden
+* Init and Delete Methods::
+* The Labeled Field Class::
+* Actions::
+* Custom Field Searching::
+* Formatting in the EBDB Buffer::
address@hidden menu
+
address@hidden Init and Delete Methods
address@hidden Init and Delete Methods
+
+It's also very common to define @code{ebdb-init-field} and
address@hidden 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 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.
+
+Both methods should always end with a call to @code{cl-call-next-method}.
+
address@hidden is called:
+
address@hidden
address@hidden
+When loading for the first time (records call @code{ebdb-init-field} on
+all of their fields after they're loaded).
+
address@hidden
+When adding a new field instance to a record.
+
address@hidden
+When editing an existing field instance (editing is a
+delete-and-create operation).
address@hidden itemize
+
address@hidden is called:
+
address@hidden
address@hidden
+When deleting a field instance.
+
address@hidden
+When deleting the record owning the field instance.
+
address@hidden
+When editing an existing field instance (editing is a
+delete-and-create operation).
+
address@hidden
+When unloading a record from the database (the optional third
+``unload'' argument will be non-nil).
address@hidden itemize
+
address@hidden The Labeled Field Class
address@hidden 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
address@hidden 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.
+
address@hidden
+(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)))
address@hidden lisp
+
address@hidden Actions
address@hidden 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.
+
+The functions in this list should accept two arguments, the record and
+the field instance under point.
+
address@hidden Custom Field Searching
address@hidden 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 @code{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
address@hidden in the *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: @code{ebdb-search-read},
+and @code{ebdb-field-search}.
+
address@hidden 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
address@hidden can accept it.
+
+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
+perfectly possible to write several @code{ebdb-field-search} methods,
+dispatching on different criterion types, if that makes things easier.
+
+In addition, fields that subclass @code{ebdb-field-labeled} can accept
+search criterion as a cons: @code{("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 @code{ebdb-field-search} method as usual.
+
address@hidden Formatting in the EBDB Buffer
address@hidden 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.
+
+Specify an ebdb formatter for the first argument to target
+*EBDB* formatting. Choices are @code{ebdb-formatter-ebdb} (for
+all cases), or one of @code{ebdb-formatter-ebdb-multiline} or
address@hidden 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 @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.
+
+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:
+
address@hidden
+(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)))
+
address@hidden lisp
+
+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.
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
\ No newline at end of file
- [elpa] externals/ebdb 761dc23 346/350: Fix bug in searching by database, (continued)
- [elpa] externals/ebdb 761dc23 346/350: Fix bug in searching by database, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 6c13763 335/350: Don't require ebdb-chn from ebdb-i18n, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb f64c791 347/350: Add internationalized version of ebdb-string for addresses, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 2d74de4 345/350: Use autoload cookies on defclass statements, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb a035748 318/350: Mention role fields in the manual, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 5e25f5b 344/350: Remove Brian Edmonds' code until copyright resolved, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb e555044 294/350: Expand manual, and edit for use of ox-texinfo-plus, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb b9ac670 333/350: Add new manual section about writing MUA integration, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 5fbc902 343/350: New option ebdb-i18n-countries-pref-scripts, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 84b348e 311/350: Basic finished version of manual, Eric Abrahamsen, 2017/08/14
- [elpa] externals/ebdb 534d3b7 298/350: Start tracking manual texi and info files,
Eric Abrahamsen <=