Pull request Compare This branch is 149 commits behind emacsmirror:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
doc
lisp
tex
.gitignore
COPYING
ChangeLog
INSTALL
Makefile.in
README
TODO
aclocal.m4
configure.ac
install-sh

README

Copyright (C) 2010-2012 Roland Winkler <winkler@gnu.org>
See the end of the file for license conditions.

BBDB is the Insidious Big Brother Database for GNU Emacs. It
provides an address book for email and snail mail addresses, phone
numbers and the like. It can be linked with various Emacs mail
clients (Message and Mail mode, Rmail, Gnus, MH-E, and VM).
BBDB is fully customizable.

BBDB is available at
http://savannah.nongnu.org/projects/bbdb/
To check it out, use
git clone git://git.savannah.nongnu.org/bbdb.git

Feedback welcome! --  There is a mailing list for discussion of BBDB:       

       bbdb-info@lists.sourceforge.net

To join, send mail to bbdb-info-request@lists.sourceforge.net

==================================================================
Installation:

See the file INSTALL.

==================================================================
Usage notes

This revised version of BBDB requires GNU Emacs 23 or newer.
Its code is still under development.  While it should work reliably,
users of previous versions of BBDB are advised that the format of
the BBDB database file has changed.  Migration to the new format should
happen automatically.  Yet it is recommended to make a copy of the
old file, in case something unexpected happens or you might want
to go back.

The BBDB info manual is still awaiting a more complete overhaul.

As compared with BBDB v2.xx, many variables, functions, and commands
have changed in BBDB v3.  Most likely you will have to review your
customizations carefully.  You may want to call bbdb-undocumented-variables
to identify outdated (i.e., now usually undocumented) variables in
your init file.  All user variables in BBDB v3 are listed at the beginning
of bbdb.el.


BBDB interface with mail user agents (MUAs)
===========================================

BBDB can interface with various mail user agents (MUAs).
These include Rmail, Gnus, VM, MH-E, Message and Mail mode.
This lets you 

 - display the BBDB records for the sender and/or recipients of a
   message you are viewing

 - create or update the BBDB records for the sender and/or
   recipients of a message

 - add annotations to the BBDB records for the sender and/or
   recipients of a message

There are two ways for BBDB to interface with MUAs:

Interactive commands
--------------------

Call bbdb-initialize (usually in your init file) to initialize
the MUA interfaces based on interactive commands

MUA commands include

  bbdb-mua-display-records, bbdb-mua-display-sender, bbdb-mua-display-recipients
  bbdb-annotate-record, bbdb-mua-annotate-sender, bbdb-mua-annotate-recipients
  bbdb-mua-edit-field, bbdb-mua-edit-field-sender, bbdb-mua-edit-field-recipients

These MUA commands operate either on existing records only. Or they
can create new records.

They are all controlled by bbdb-mua-update-interactive-p.
This is a cons pair (WITHOUT-PREFIX . WITH-PREFIX).
The car is used if the command is called without a prefix.
The cdr is used if the command is called with a prefix (and if the prefix
        is not used for another purpose).

Allowed values are (here ADDRESS is an email address found in a message):
 nil          Do nothing.
 search       Search for existing records matching ADDRESS.
 update       Search for existing records matching ADDRESS;
                update name and mail field if necessary.
 query        Search for existing records matching ADDRESS;
                query for creation of a new record if the record does not exist.
 create or t  Search for existing records matching ADDRESS;
                create a new record if it does not yet exist.
 a function   This functions will be called with no arguments.
                It should return one of the above values (see below).
 read         Read the value interactively.

BBDB v2 also used MUA-specific variables bbdb/MUA-update-records-mode
to control its interfaces with MUAs. In BBDB v3 the variables
bbdb/MUA-update-records-p are only used as fallback if the generic
(MUA-independent) variables bbdb-mua-update-interactive-p,
bbdb-update-records-p or bbdb-mua-auto-update-p result in a value of
nil for the arg UPDATE-P of bbdb-update-records.

Noninteractive functions
------------------------

Call bbdb-mua-auto-update-init (usually in your init file)
to hook BBDB's hook function bbdb-mua-auto-update into the MUAs.

bbdb-mua-auto-update automatically updates the BBDB records for the
sender and/or recipients of a message.  If bbdb-message-pop-up is non-nil,
the matching records are also displayed in a continuously updated BBDB window, 

The behavior of bbdb-mua-auto-update is controlled by bbdb-mua-auto-update-p.
This may take the same values as bbdb-mua-update-interactive-p (except read). 
Binding this to a function is often most helpful for noninteractive use.
For example, you may want to bind bbdb-mua-auto-update-p to the function
bbdb-select-message,  see bbdb-accept-message-alist and
bbdb-ignore-message-alist.  If a message is accepted by bbdb-select-message,
the actual action performed by BBDB (i.e., the return value of
bbdb-select-message) is given by bbdb-mua-update-records-p.

==================================================================

Notes for BBDB lisp hackers:
----------------------------

If you write your own functions and commands to modify BBDB records,
do not call the low-level functions bbdb-record-set-* such as
bbdb-record-set-aka, bbdb-record-set-mail etc. The recommended
sequence of calls is

- one or multiple calls of bbdb-record-set-field for the respective
  fields to be changed. This not only sets the fields, but it also
  ensures the integrity of the database. Also, this makes your code
  more robust with respect to possible future changes of BBDB's
  innermost internals.

- a call of bbdb-change-record which updates the database after a
  change of RECORD.

- If the changed record is displayed in the *BBDB* buffer, call
  bbdb-redisplay-record.

==================================================================

Copyright (C) 2010-2012 Roland Winkler <winkler@gnu.org>

This file is part of the Insidious Big Brother Database (aka BBDB),

BBDB is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

BBDB is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with BBDB.  If not, see <http://www.gnu.org/licenses/>.