BBDB User Manual

A phone number and address database program for GNU Emacs

Edition 1.7, September 1992

by Jamie Zawinski

Copyright © 1991, 1992 Jamie Zawinski <jwz@lucid.com>



This is edition 1.7 of the BBDB User Manual for BBDB version 1.47, September 1992.



Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on fnord all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 BBDB

BBDB is a rolodex-like database program for GNU Emacs. BBDB stands for Insidious Big Brother Database, and is not, repeat, not an obscure reference to the Buck Rogers TV series.

It provides the following features:


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Installation

This program consists of eleven files:

Put all of these files in some directory in your load-path, and byte-compile them. (If you don’t compile these files, the BBDB will be so slow as to be virtually unusable.)

You can compile everything with the shell command

make -f bbdb-Makefile all 

but that won’t work if you don’t have VM. In that case, you can instead say

make -f bbdb-Makefile rmail vm mhe gnus

(omitting the names of any packages you don’t want to bother with). You will undoubtedly need to change some of the parameters at the top of the Makefile (see the comments there).

Put the following forms in your ‘.emacs’ file.

(autoload 'bbdb         "bbdb-com" "Insidious Big Brother Database" t)
(autoload 'bbdb-name    "bbdb-com" "Insidious Big Brother Database" t)
(autoload 'bbdb-company "bbdb-com" "Insidious Big Brother Database" t)
(autoload 'bbdb-net     "bbdb-com" "Insidious Big Brother Database" t)
(autoload 'bbdb-notes   "bbdb-com" "Insidious Big Brother Database" t)
(autoload 'bbdb-insinuate-vm       "bbdb-vm"    "Hook BBDB into VM")
(autoload 'bbdb-insinuate-rmail    "bbdb-rmail" "Hook BBDB into VM")
(autoload 'bbdb-insinuate-mh       "bbdb-mhe"   "Hook BBDB into MH-E")
(autoload 'bbdb-insinuate-gnus     "bbdb-gnus"  "Hook BBDB into GNUS")
(autoload 'bbdb-insinuate-sendmail "bbdb"       "Hook BBDB into VM")

If you want to take advantage of the VM features of the BBDB, then add the form (bbdb-insinuate-vm) to your ‘~/.vm’ file.

If you want to take advantage of the RMAIL features of the BBDB, then add the following line to your ‘.emacs’ file:

(setq rmail-mode-hook 'bbdb-insinuate-rmail)

If you want to take advantage of the MH-E features of the BBDB, then add the following line to your ‘.emacs’ file:

(setq mh-folder-mode-hook 'bbdb-insinuate-mh)

If you want to take advantage of the GNUS features of the BBDB, then add the following line to your ‘.emacs’ file:

(setq gnus-Startup-hook 'bbdb-insinuate-gnus)

If you want to take advantage of send-mail-mode features of the BBDB, then add the following line to your ‘.emacs’ file:

(setq mail-setup-hook 'bbdb-insinuate-sendmail)

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Introduction

The database is a set of records, where each record corresponds to one person or organization. Each record has several fields. The built-in fields are:

name

The name of this person, or none if it’s an organization.

AKA

A list of other names of this person.

company

The name of this person’s organization, or none.

net

A list of this person’s network addresses.

address

A list of postal (physical) addresses for this person.

phone

A list of telephone numbers for this person.

notes

Random commentary.

In addition to these fields, you may define your own field-types, with the bbdb-insert-new-field command. (See section BBDB Mode).

The database itself lives in a file which is named by the variable bbdb-file, defaulting to ‘~/.bbdb’. The first time you use one of the BBDB commands, this file is read into an emacs buffer, and remains there. As you make changes to the database, this buffer is changed as well, ensuring that if it is auto-saved, it will be saved in its most current state.

You can list the contents of the database with the command M-x bbdb. You will be prompted for a regular expression, and all records which match that regexp in the name, company, network address, or any notes fields will be displayed.

A narrower search may be made by using the commands bbdb-name, bbdb-company, bbdb-net, or bbdb-notes instead, which limit their searches to the name, company, email address, and notes fields, respectively. If these commands are given a prefix argument, the listing displayed will be one line per entry; otherwise, the full db entry will be shown on multiple lines.

The bbdb-notes command will prompt for the notes field to search (<RET> for all). In this way you can limit you searches to the contents of one particular user-defined notes field. (You can add user-defined fields with the bbdb-insert-new-field command; See section BBDB Mode.)

There are several ways to add new entries to the Insidious Big Brother Database; the most straightforward is to use M-x bbdb-create, which will prompt you for all relevant information. However, the easiest way is to allow them to be added automatically by one of the mail or news-reading interfaces (See section Interfaces).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 BBDB Mode

The ‘*BBDB*’ buffer is in BBDB mode, which has keybindings for manipulating the database. Letters no longer insert themselves. Numbers are prefix arguments. You can move around using the usual cursor motion commands.

e

(bbdb-edit-current-field) Edit the field on the current line. If the cursor is in the middle of a multi-line field, such as an address or comments section, then the entire field is edited, not just the current line.

;

(bbdb-edit-notes) A shortcut for editing the notes field.

d, C-k

(bbdb-delete-current-field-or-record) Delete the field on the current line. If the current line is the first line of a record, then this deletes the entire record from the database (prompting first).

C-o

(bbdb-insert-new-field) Inserts a new field into the current record, as opposed to editing an existing one. You are prompted (with completion) for the type of field to insert (phone, address, will be asked whether to add a new “note” field of that type.

If you are inserting a new phone-number field, you can control whether it is a North American or European phone number by providing a prefix argument. A prefix arg of ^U means it’s to be a euronumber, and any other prefix arg means it’s to be a a structured North American number. Otherwise, which style is used is controlled by the variable bbdb-north-american-phone-numbers-p.

C-x C-t

(bbdb-transpose-fields) This is like the transpose-lines command, but it is for BBDB fields. If the cursor is on a field of a BBDB record, that field and the previous field will be transposed.

With argument ARG, takes previous line and moves it past ARG fields. With argument 0, interchanges the field that point is in with the field that mark is in.

Both fields must be in the same record, and must be of the same basic type (that is, you can use this command to change the order in which phone-number fields are listed, but you can’t use it to make an address appear before a phone number; the order of field types is fixed.)

n, p

(bbdb-next-record, bbdb-prev-record) Move to the next and previous displayed record, respectively.

t

(bbdb-elide-record) Toggles whether the current record is displayed in a one-line listing, or a full multi-line listing. With a numeric argument of 0, the current record will unconditionally be made elided; with any other argument, the current record will unconditionally be shown expanded.

If *t is used instead of simply t, then the state of all records will be changed instead of just the one at point. In this case, a numeric argument of 0 means that all records will unconditionally be made elided; any other numeric argument means that all of the records will unconditionally be shown expanded; and no numeric argument means that the records are made to be in the opposite state of the record under point.

o

(bbdb-omit-record) Removes the current record from the display, but does not delete it from the database; it merely makes it seem as if the most recent search had not matched this record. With a numeric argument, omit the next N records. With a negative argument, go backwards.

m

(bbdb-send-mail) Begin composing mail to the person represented by the current record. The first email address is used. Normally, the mail-sending package which is used is determined by which mail-reading package is loaded; that is, if MH-E is loaded, then mh-send will be used; if VM is loaded, then vm-mail is used; otherwise, mail is used. You can override this by setting the variable bbdb-send-mail-style to one of the symbols vm, mh, or mail.

If *m is used instead of simply m, then mail will be sent to all of the folks listed in the ‘*BBDB*’ buffer instead of just the person under point.

s, C-x C-s

(bbdb-save-db) Saves the BBDB file to disk.

r

(bbdb-refile-record) Merge the current record into some other record; that is, delete the record under point after copying all of the data within it into some other record. this is useful if you realize that somehow a redundant record has gotten into the database, and you want to merge it with another.

If both records have names and/or companies, you are asked which to use. Phone numbers, addresses, and network addresses are simply concatenated. The first record is the record under the point; the second is prompted for. Completion behavior is as dictated by the variable bbdb-completion-type.

M-d

(bbdb-dial) If you are on a Sun SparcStation with the ‘sound’ option installed, this command will play the appropriate tones on the builtin speaker to dial the phone number corresponding to the current line. If the point is at the beginning of a record, dial the first phone number. This does not dial the extension. This also does not dial the area code if it is the same as bbdb-default-area-code, unless a prefix argument is given.

bbdb-dial-local-prefix

Set this to a string of digits if your phone system requires you to dial some code to access an outside line.

bbdb-dial-long-distance-prefix

Set this to a string of digits if your phone system requires you to dial some code before dialing a long-distance number (one not in your local area code.)

f

(bbdb-finger) This command “fingers” the network address of a BBDB record. If this command is executed from the ‘*BBDB*’ buffer, it fingers the network address of the record which is at point; otherwise, it prompts in the minibuffer (with completion) for a user to finger. With a numeric prefix argument, it fingers the Nth network address of the current record; with a prefix argument of ^U, it fingers all of them. The ‘*finger*’ buffer is filled asynchronously, meaning that you don’t have to wait around for it to finish; but fingering another user before the first finger has finished could have unpredictable results.

If this command is executed from the ‘*BBDB*’ buffer, it may be prefixed with * (as in *f instead of simply f), meaning to finger all of the users currently listed instead of just the one under point. The numeric prefix argument has the same interpretation.

q

(bbdb-bury-buffer) Gets the ‘*BBDB*’ buffer out of your face.

?

(bbdb-help) This displays a one-line help message in the minibuffer, showing some of the most common bbdb-mode commands.

i

(bbdb-info) This jumps from the ‘*BBDB*’ buffer to this documentation. If this documentation is installed in the standard place (the directory named by the variable Info-directory) in a file called ‘bbdb’ or ‘bbdb.info’, then no further configuration is necessary to make this work.

bbdb-info-file

If this documentation is not installed in the standard Info directory, then you should set this variable to the name of the texinfo-formatted version of this file; the bbdb-info command will use this file instead.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Interfaces

The BBDB interfaces itself with several message-handling packages, but certain parameters control its behavior depending on whether it is being used from within a mail reader or a news reader.

In all of these packages, two new keybindings will be added:

:

(show-sender) Displays the BBDB entry corresponding to the author of the current message. If there is none, you will be asked whether to create one.

;

(annotate-sender) Lets you edit the ‘notes’ field of the BBDB record corresponding to the sender of the current message. If there is no record for the current author, you will be asked whether to create one.

It is possible to configure BBDB so that it automatically creates a record when it sees a message from a person who is not in the database. It is also possible to have text automatically added to the notes field of the corresponding record depending on the contents of the message headers. See section Customization Hooks

These keybindings (and several other features) will not be available unless you call the appropriate “insinuation” function; See section Installation.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.1 Mail Reading Interfaces

There are BBDB interfaces for the following mail readers:


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.2 News Reading Interfaces

The only news reader which BBDB supports is GNUS, by Masanobu Umeda. If anyone wants to write a BBDB interface to GNEWS (probably quite easy to do), please send it to me.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3 Mail Sending Interfaces

When sending mail, the keystroke M-TAB is bound to the function bbdb-complete-name. This will take the string that you have typed (from point back to the preceding colon, comma, or the beginning of the line) and will complete that against the contents of the database. What you have typed may be an initial subsequence of a person’s full name or network address; if it completes ambiguously, then what you have typed will be replaced with the common portion of the matches. Typing M-<TAB> again will show a list of possible completions. If it completes unambiguously, then an address of the form User Name <email-address> will be inserted. The variable bbdb-completion-type controls whether completion is done on real names, or network addresses, or both.

You must call the function bbdb-insinuate-sendmail to get this key binding. See section Installation

You can control what “real name” is inserted with the mail-alias property: if a record has a mail-alias property, then that is used instead of their name field.

If the variable bbdb-completion-display-record is true (the default) then when you successfully complete an address with M-TAB, the corresponding record will be appended to the ‘*BBDB*’ buffer. The buffer will not be displayed if it is not already visible, but the record will be displayed there.

When sending mail, you can use the command bbdb-yank-addresses to CC the current message to the people currently displayed in the ‘*BBDB*’ buffer. This is useful if you are in the midst of sending or replying to a message, and you decide to add some recipients. You can use one of the M-x bbdb commands to display the set of people that you want to CC the message to, and then execute this command to add them to the list.

If you are using my ‘mail-abbrevs.el’ package, which uses the word-abbrev mechanism for mail aliases, then you can store your mail aliases in the BBDB instead of duplicating the information elsewhere.

If you want a mail alias to be defined for a person, simply add a mail-alias field to their record. You may have multiple aliases for the same person; simply separate them with commas.

If more than one person has the same mail-alias, then that alias expands to the addresses of all of those people; in this way you can maintain mailing lists within the BBDB.

To actually define the aliases which are stored in the BBDB, call the function bbdb-define-all-aliases from your mail-setup-hook. This will search the database, and call define-mail-alias to define each of the resulting aliases.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Options

There are many variables which control the behavior of the Insidious Big Brother Database, and there are many hook-variables which can be used to modify its behavior in more complex ways. Several pieces of functionality are included which use the hooks in this way.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.1 Customization Parameters

bbdb-file

The name of the file which contains your personal database. Default: ‘~/.bbdb’.

bbdb-default-area-code

The default area code to use when prompting for a new phone number. Default: 415. This must be a number, not a string.

bbdb-north-american-phone-numbers-p

Whether syntax-checking of phone numbers should be enforced. Default: t. This only works for Bell-system phone numbers. If this is true, then you can’t enter invalid phone numbers, and all phone numbers are pretty-printed in the same way. European phone numbers don’t have as strict a syntax, however, so this is a harder problem for them (on which I am punting).

You can have both styles of phone number in your database by providing a prefix argument to the bbdb-insert-new-field command.

bbdb-electric-p

Whether bbdb mode should be “electric” like electric-buffer-list. Default: t. Basically this means that when you type space after M-x bbdb, your window configuration will be restored to what it was before you invoked the db list. (The bbdb-mode commands still work as well.)

There are some problems with electric modes; for example, keyboard macros and incremental search don’t work. (This is not a bug in BBDB, but in ‘electric.el’.)

bbdb-case-fold-search

Default: the same as case-fold-search. case-fold-search is bound to this by M-x bbdb and related commands. This variable lets the case-sensitivity of ^S and of the bbdb searching commands be different.

bbdb/mail-auto-create-p

If this is t (the default), then VM, MH, and RMAIL will automatically create new bbdb records for people you receive mail from. If this variable is a function name or lambda expression, then it is called with no arguments to decide whether an entry should be automatically created. You can use this to, for example, not create records for messages which have reached you through a particular mailing list, or to only create records automatically if the mail has a particular subject. See the variables bbdb-ignore-most-messages-alist and bbdb-ignore-some-messages-alist (See section Predefined Hooks)

bbdb/news-auto-create-p

If this is t (default: nil), then GNUS will automatically create new BBDB records for people you read messages by. If this is a function name or lambda expression, then it is called with no arguments to decide whether an entry should be automatically created. You can use this to, for example, create or not create messages which have a particular subject. See the variable bbdb-auto-notes-alist (See section Predefined Hooks).

If you want to autocreate messages based on the current newsgroup, it’s probably a better idea to set this variable to t or nil from your gnus-Select-group-hook instead.

To automatically remember users in certain groups, you can do something like

(setq gnus-Select-group-hook
  '(lambda ()
     (setq bbdb/news-auto-create-p
           (or (string= "some.news.group" gnus-newsgroup-name)
               (string= "other.news.group" gnus-newsgroup-name)))))
bbdb-quiet-about-name-mismatches

If this is false (the default), then BBDB will prompt you when it notices a name change, that is, when the “real name” in a message doesn’t correspond to a record already in the database with the same network address. As in, “John Smith <jqs@frob.com>” versus “John Q. Smith <jqs@frob.com>”. If this is true, then you will not be asked if you want to change it (and it will not be changed.)

bbdb-use-alternate-names

If this is false, then the BBDB will not use the AKA field. Otherwise (the default) then the mail and news interfaces will ask you if you want to add an alternate name when a name-change is noticed, and will ask you whether the new name should be made the primary one. Note that if bbdb-quiet-about-name-mismatches is true, you will not be asked any questions about alternate names.

bbdb-readonly-p

If this is true (default: nil), then nothing will attempt to change the database implicitly, and you will be prevented from doing it explicitly. If you have more than one emacs running at the same time, you might want to arrange for this to be set to t in all but one of them.

bbdb-auto-revert-p

If this variable is true (default: nil) and the BBDB file is noticed to have changed on disk, it will be automatically reverted without prompting you first. Otherwise you will be asked. (But if the file has changed and you have made changes in memory as well, you will always be asked.)

bbdb-notice-auto-save-file

If this is true (default: nil), then the BBDB will notice when its auto-save file is newer than the file is was read from, and will offer to revert.

bbdb-use-pop-up

If true (the default), display a continuously-updating BBDB window while in VM, MH, RMAIL, or GNUS. Each time a new message is selected, the record corresponding to that message’s sender will be displayed in another window. The buffer in this other window will be in bbdb-mode, and all corresponding commands will be available.

This buffer will be positioned on the screen by finding the tallest of the windows present, and splitting it such that the bottom bbdb-pop-up-target-lines lines of the window display the ‘*BBDB*’ buffer. With the default configurations of VM, MH, RMAIL, and GNUS, this means that the bbdb-list buffer will be just below the message-body buffer.

If this is the symbol horiz, then the BBDB window will be stacked horizontally instead of vertically, if there is room to do that tastefully.

bbdb-pop-up-target-lines

Desired number of lines in a VM/MH/RMAIL/GNUS pop-up BBDB window, default 5.

bbdb-completion-type

Controls the behavior of the bbdb-complete-name command. If nil (the default), completion is done across the set of all full-names and user-ids in the database; if the symbol name, completion is done on real-names only; if the symbol net, completion is done on network addresses only; if it is primary, then completion is done only across the set of primary network addresses (the first address in the list of addresses for a given user). If it is primary-or-name, completion is done across primaries and real names.

bbdb-user-mail-names

A regular expression identifying the addresses that belong to you. If a message from an address matching this is seen, the BBDB record for the ‘To:’ line will be shown instead of the one for the ‘From:’ line. If this is nil, it will default to the value of (user-login-name).

bbdb-always-add-addresses

If this is t, then whenever the Insidious Big Brother Database notices a new email address corresponding to a person who is in the database, it will add it to the database. If this is nil (the default), then whenever a new network address is noticed for a person in the database, you will be asked whether to add the address. If this is the symbol never (really if it is not t and not nil) then new network addresses will never be automatically added.

bbdb-new-nets-always-primary

If this is t, then when the Insidious Big Brother Database adds a new address to a record, it will always add it to the front of the list of addresses, making it the primary address. If this is nil (the default), then you will be asked. If this is the symbol never (really if it is not t and not nil) then new network addresses will always be added to the end of the list.

bbdb-message-caching-enabled

Whether caching of the message->bbdb-record association should be used for the interfaces which support it (VM, MH, and RMAIL). This can speed things up a lot. One implication of this variable being true (the default) is that the bbdb-notice-hook will not be called each time a message is selected, but only the first time. Likewise, if selecting a message would generate a question (whether to add an address, change the name, etc) you will only be asked that question the very first time the message is selected.

bbdb-elided-display

Default: nil. Set this to t to make the bbdb-display commands default to displaying one line per record instead of a full listing. Set this to a list of some of the symbols '(address phone net notes) to select those fields to be left out of the listing (you can’t leave out the name field).

This is the default state for M-x bbdb and friends. You can have a different default for when the BBDB buffer is automatically updated by the mail and news interfaces by setting the variable bbdb-pop-up-elided-display. If that variable is unbound, this variable will be consulted instead.

bbdb-pop-up-elided-display

Default: unbound. Set this to t if to make the pop-up BBDB buffer default to displaying one line per record instead of a full listing. Set this to a list of some of the symbols '(address phone net notes) to select those fields to be left out of the listing (you can’t leave out the name field).

The default state for M-x bbdb and friends is controlled by the variable bbdb-elided-display; this variable is the default for when the BBDB buffer is automatically updated by the mail and news interfaces. If bbdb-pop-up-elided-display is unbound, then bbdb-elided-display the former will be consulted instead by mail and news.

bbdb-offer-save

If t (the default), then certain actions will cause the BBDB to ask you whether you wish to save the database. If nil, then the offer to save will never be made. If not t and not nil, then any time it would ask you, it will just save it without asking.

The following variables apply only to the GNUS interface to BBDB. To make use of them, you must add this forms to your ‘.emacs’ file:

(autoload 'bbdb/gnus-lines-and-from "bbdb-gnus")
(setq gnus-optional-headers 'bbdb/gnus-lines-and-from)
bbdb/gnus-mark-known-posters

If t (the default), then the GNUS subject list will contain an indication of those messages posted by people who have entries in the Insidious Big Brother Database (they will be marked with an asterisk.)

bbdb/gnus-header-prefer-real-names

Default: nil. if t, then the GNUS subject list will display real names instead of network addresses.

bbdb/gnus-header-show-bbdb-names

Default: t. If both this variable and the bbdb/gnus-header-prefer-real-names variable are true, then for news messages from people who are in your database, the name displayed will be the primary name from the database, rather than the one from the ‘From:’ line of the message. This doesn’t affect the names of people who aren’t in the database, of course.

bbdb/gnus-lines-and-from-length

Default: 18. The number of characters used to display ‘From:’ info in GNUS, if you have set gnus-optional-headers to bbdb/gnus-lines-and-from.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.2 Customization Hooks

All of the hooks variables described below may be set to a symbol or lambda expression, which will be funcalled; or may be set to a list of symbols or lambda expressions, each of which will be funcalled in turn. Almost all hooks in Emacs work this way. But notice that some of the hooks described below are called with arguments.

bbdb-list-hook

Hook or hooks invoked after the bbdb-list-buffer is filled in. Invoked with no arguments.

bbdb-create-hook

Hook or hooks invoked each time a new bbdb-record is created. Invoked with one argument, the new record. This is called before the record is added to the database. Note that bbdb-change-hook will be called as well.

bbdb-change-hook

Hook or hooks invoked each time a bbdb-record is altered. Invoked with one argument, the record. This is called before the database buffer is modified. Note that if a new bbdb record is created, both this hook and bbdb-create-hook will be called.

bbdb-notice-hook

Hook or hooks invoked each time a bbdb-record is “noticed,” that is, each time it is displayed by the news or mail interfaces. Invoked with one argument, the new record. The record need not have been modified for this to be called - use bbdb-change-hook for that. You can use this to, for example, add something to the notes field based on the subject of the current message. It is up to your hook to determine whether it is running in GNUS, VM, MH, or RMAIL, and to act appropriately.

Also note that bbdb-change-hook will not be called as a result of any modifications you may make to the record inside this hook.

Beware that if the variable bbdb-message-caching-enabled is true (a good idea) then when you are using VM, MH, or RMAIL, this hook will be called only the first time that message is selected. (The GNUS interface does not use caching.) When debugging the value of this hook, it is a good idea to set caching-enabled to nil.

bbdb-after-read-db-hook

Hook or hooks invoked (with no arguments) just after the Insidious Big Brother Database is read in. Note that this can be called more than once if the BBDB is reverted. One possible use for this is to rename the ‘.bbdb’ buffer; for example

(setq bbdb-after-read-db-hook '(lambda () (rename-buffer " bbdb")))

will cause the buffer visiting the bbdb-file to be called " bbdb". The leading space in its name will prevent it from showing up in the buffer list.

bbdb-load-hook

Hook or hooks invoked (with no arguments) when the Insidious Big Brother Database code is first loaded.

bbdb-canonicalize-net-hook

If this is non-nil, it should be a function of one argument: a network address string. (Note that, unlike the other hook-variables described above, this may not be a list of functions.) Whenever the Insidious Big Brother Database “notices” a message, the corresponding network address will be passed to this function first, as a kind of “filter” to do whatever transformations upon it you like before it is compared against or added to the database. For example: it is the case that CS.CMU.EDU is a valid return address for all mail originating at a machine in the .CS.CMU.EDU domain. So, if you wanted all such addresses to be canonically hashed as user@CS.CMU.EDU, instead of as user@somehost.CS.CMU.EDU, you might set this variable to a function like this:

(setq bbdb-canonicalize-net-hook
     '(lambda (addr)
        (cond ((string-match
                 "\\`\\([^@]+@\\).*\\.\\(CS\\.CMU\\.EDU\\)\\'"
                 addr)
               (concat (substring addr
                         (match-beginning 1) (match-end 1))
                       (substring addr
                         (match-beginning 2) (match-end 2))))
              (t addr))))

You could also use this function to rewrite UUCP-style addresses into domain-style addresses, or any number of other things.

This function will be called repeatedly until it returns a value EQ to the value passed in. So multiple rewrite rules might apply to a single address.

There is an example of the use of this variable in the file ‘bbdb-hooks.el’: the function sample-bbdb-canonicalize-net-hook.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.3 Predefined Hooks

If the variable bbdb-change-hook is set to the symbol bbdb-timestamp-hook, then every record in the database will have a field named ‘timestamp’, which will always contain the date and time at which this record was created or last modified.

If the variable bbdb-create-hook is set to the symbol bbdb-creation-date-hook, then every record in the database will have a field named ‘creation-date’, which will contain the date and time at which this record was added to the database.

If the variable bbdb/mail-auto-create-p is set to the symbol bbdb-ignore-most-messages-hook, then the variable bbdb-ignore-most-messages-alist will determine which messages should have records automatically created for them. The format of this alist is

(( HEADER-NAME . REGEXP ) … )

for example,

(("From" . "@.*\\.maximegalon\\.edu")
 ("Subject" . "time travel"))

will cause BBDB entries to be made only for messages sent by people at Maximegalon U., or (that’s or) people posting about time travel.

There may be only one entry per header in this alist: that is,

(("From" . "addr1\\|addr2") … )

is legal, but

(("From" . "addr1") ("From" . "addr2") … )

is not.

If the variable bbdb/mail-auto-create-p is set to the symbol bbdb-ignore-some-messages-hook, then the variable bbdb-ignore-some-messages-alist will determine which messages should have records automatically created for them. This is the exact inverse of the semantics of the bbdb-ignore-most-messages-alist: the alist specifies which messages should not have records automatically created for them, instead of which should. For example,

(("From" . "mailer.daemon")
 ("To" . "mailing-list-1\\|mailing-list-2")
 ("CC" . "mailing-list-1\\|mailing-list-2"))

will cause BBDB entries to not be made for messages from any mailer daemon, or messages sent to or CCed to either of two mailing lists.

The variable bbdb/news-auto-create-p may be set to either of the above-mentioned functions as well, to get this behavior for netnews messages instead of mail messages.

If the variable bbdb-notice-hook is set to the symbol bbdb-auto-notes-hook, then the variable bbdb-auto-notes-alist may be used to automatically add text to the notes fields of the records corresponding to certain messages. The format of this alist is

(( HEADER-NAME
   (REGEXP . STRING) … )
    … )

for example,

(("To" ("-vm@" . "VM mailing list"))
 ("Subject" ("sprocket" . "mail about sprockets")
            ("you bonehead" . "called me a bonehead")))

will cause the text "VM mailing list" to be added to the notes field of the record corresponding to anyone you get mail from via one of the VM mailing lists. If, that is, bbdb/mail-auto-create-p is set such that the record would have been created, or if the record already existed.

The format of elements of this list may also be

(REGEXP FIELD-NAME STRING)

or

(REGEXP FIELD-NAME STRING REPLACE-P)

meaning add the given string to the named field. The field-name may not be ‘name’, ‘aka’, ‘address’, ‘phone’, or ‘net’ (builtin fields) but must be either ‘notes’, ‘company’, or the name of a user-defined note-field.

("pattern" . "string to add")

is equivalent to

("pattern" notes "string to add")

STRING can contain \& or \N escapes like in the function replace-match. For example, to automatically add the contents of the organization field of a message to the company field of a BBDB record, you can use this:

("Organization" (".*" company "\\&"))

(Note you need two \ to get a single \ into a lisp string literal.) If STRING is an integer N, the Nth matching subexpression is used, so the above example could be written more efficiently as

("Organization" (".*" company 0))

If the REPLACE-P flag is true, then the string replaces the old contents instead of being appended to it.

If multiple clauses match the message, all of the corresponding strings will be added.

If the string is being appended (REPLACE-P is false or not provided) then the new string is appended to the end of the existing field value, with an intervening newline. So each piece of text automatically added to this field will go on its own line.

You can control what the separator is by putting a field-separator property on the symbol naming the field. For example, to make text automatically added to a field named newsgroups be separated by commas, you could do

(put 'newsgroups 'field-separator "; ")

This variable works for news as well. You might want to arrange for this to have a different value when in mail as when in news.

There may be only one entry per header in this alist: that is,

 (("Subject" ("\\bfoo\\b" . "Foo!!")
             ("bar" . "Bar!")))

will work, but

 (("Subject" ("\\bfoo\\b" . "Foo!!"))
  ("Subject" ("bar" . "Bar!")))

will not.

bbdb-auto-notes-ignore is an alist of headers and regexps to ignore in bbdb-auto-notes-hook. Each element looks like

(HEADER . REGEXP)

for example,

("Organization" . "^Gatewayed from\\|^Source only")

would exclude the phony Organization: headers in GNU mailing-lists gatewayed to the gnu.* newsgroups. Note that this exclusion applies only to a single field, not to the entire message. For that, use the variable bbdb-auto-notes-ignore-all.

bbdb-auto-notes-ignore-all is an alist of headers and regexps which cause the entire message to be ignored in bbdb-auto-notes-hook. Each element looks like

(HEADER . REGEXP)

for example,

("From" . "BLAT\\.COM")

would exclude any notes recording for message coming from BLAT.COM. Note that this is different from bbdb-auto-notes-ignore, which applies only to a particular header field, rather than the entire message.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 The Mailing List

There is a mailing list for discussing BBDB: ‘info-bbdb@lucid.com’. To join, send mail to ‘info-bbdb-request@lucid.com’ (don’t forget the ‘-request’ part or you’ll look silly in front of lots of people who have the ability to remember it indefinitely...)

There is also a second mailing list, to which only bug fixes and new version announcements are sent; to be added to it, send mail to ‘bbdb-announce-request@lucid.com’. This is a very low volume list, and if you’re using BBDB, you really should be on it.

When joining these lists or reporting bugs, please mention which version you have. You can find out with M-x bbdb-version.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 The Latest Version

The latest version is always available for anonymous FTP from ‘archive.cis.ohio-state.edu:/pub/gnu/emacs/elisp-archive/packages/bbdb.tar.Z’.

If you are on the ‘bbdb-announce’ mailing list, you will receive patches as I release new versions.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 Todo List


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9 Thanks

Thanks to everyone on the info-bbdb mailing list for many useful suggestions. This hack would be far less insidious without their input!

And special thanks to Sebastian Kremer, Joe Wells, Todd Kaufmann, Andy Norman, Ivan Vazquez, Stewart Clamen, Roland McGrath, Dave Brennan, Kimball Collins, Dirk Grunwald, Philippe Queinnec, Boris Putanec, Dave Disser, Francois Felix Ingrand, Sean Owens, Guido Bosch, Lance Brown, Tom Emerson, George Hartzell, Luis Miguel Silveira, Kimmo Suominen, Derek Upham, David Zuhn.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Concept Index

Jump to:   *  
A   B   C   D   E   F   G   I   M   N   O   P   R   S   T   U  
Index Entry  Section

*
*BBDB* buffer 1.3 BBDB Mode

A
Adding new fields 1.3 BBDB Mode
Adding new records 1.2 Introduction
Address completion 1.4.3 Mail Sending Interfaces
Address completion 1.5.1 Customization Parameters
AKA 1.5.1 Customization Parameters
Alternate names 1.5.1 Customization Parameters
Annotating the sender of the current message 1.4 Interfaces
Auto-save files 1.5.1 Customization Parameters
Automatic display of the corresponding record 1.5.1 Customization Parameters
Automatically adding text to records 1.5.3 Predefined Hooks
Automatically creating records 1.5.1 Customization Parameters
Automatically creating records 1.5.3 Predefined Hooks

B
BBDB Mode 1.3 BBDB Mode
Builtin fields 1.2 Introduction

C
Changing fields 1.3 BBDB Mode
Completion 1.5.1 Customization Parameters
Creating new records 1.2 Introduction

D
Deleting fields 1.3 BBDB Mode
Dialing phone numbers 1.3 BBDB Mode

E
Editing fields 1.3 BBDB Mode
Electric display 1.5.1 Customization Parameters
Elided display 1.2 Introduction
European phone numbers 1.3 BBDB Mode
European phone numbers 1.5.1 Customization Parameters

F
Finger interface 1.3 BBDB Mode
Fixing mistakes 1.3 BBDB Mode

G
GNUS Subject-buffer 1.5.1 Customization Parameters

I
Inserting new fields 1.3 BBDB Mode
Installation 1.1 Installation

M
Mail address completion 1.4.3 Mail Sending Interfaces
Mail address completion 1.5.1 Customization Parameters
Mail Aliases 1.4.3 Mail Sending Interfaces
Mailing lists 1.4.3 Mail Sending Interfaces
Makefile 1.1 Installation
Merging records 1.3 BBDB Mode

N
Name completion 1.4.3 Mail Sending Interfaces
Name completion 1.5.1 Customization Parameters
North American phone numbers 1.3 BBDB Mode
North American phone numbers 1.5.1 Customization Parameters

O
One-line display 1.2 Introduction

P
Phone numbers 1.3 BBDB Mode
Phone numbers 1.5.1 Customization Parameters

R
Removing fields 1.3 BBDB Mode
Reordering fields 1.3 BBDB Mode

S
Saving your changes 1.3 BBDB Mode
Searching the database 1.2 Introduction
Sending mail 1.3 BBDB Mode
Sending mail 1.4.3 Mail Sending Interfaces
Showing the sender of the current message 1.4 Interfaces
Sound support 1.3 BBDB Mode

T
Timestamping records 1.5.3 Predefined Hooks
Transposing fields 1.3 BBDB Mode

U
User-defined fields 1.2 Introduction
User-defined fields 1.3 BBDB Mode

Jump to:   *  
A   B   C   D   E   F   G   I   M   N   O   P   R   S   T   U  

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Variable Index

Jump to:   B  
Index Entry  Section

B
bbdb-after-read-db-hook 1.5.2 Customization Hooks
bbdb-always-add-addresses 1.5.1 Customization Parameters
bbdb-auto-notes-alist 1.5.3 Predefined Hooks
bbdb-auto-notes-ignore 1.5.3 Predefined Hooks
bbdb-auto-notes-ignore-all 1.5.3 Predefined Hooks
bbdb-auto-revert-p 1.5.1 Customization Parameters
bbdb-canonicalize-net-hook 1.5.2 Customization Hooks
bbdb-case-fold-search 1.5.1 Customization Parameters
bbdb-change-hook 1.5.2 Customization Hooks
bbdb-completion-display-record 1.4.3 Mail Sending Interfaces
bbdb-completion-type 1.5.1 Customization Parameters
bbdb-create-hook 1.5.2 Customization Hooks
bbdb-default-area-code 1.5.1 Customization Parameters
bbdb-dial-local-prefix 1.3 BBDB Mode
bbdb-dial-long-distance-prefix 1.3 BBDB Mode
bbdb-electric-p 1.5.1 Customization Parameters
bbdb-elided-display 1.5.1 Customization Parameters
bbdb-file 1.5.1 Customization Parameters
bbdb-ignore-most-messages-alist 1.5.3 Predefined Hooks
bbdb-ignore-some-messages-alist 1.5.3 Predefined Hooks
bbdb-info-file 1.3 BBDB Mode
bbdb-list-hook 1.5.2 Customization Hooks
bbdb-load-hook 1.5.2 Customization Hooks
bbdb-message-caching-enabled 1.5.1 Customization Parameters
bbdb-new-nets-always-primary 1.5.1 Customization Parameters
bbdb-north-american-phone-numbers-p 1.5.1 Customization Parameters
bbdb-notice-auto-save-file 1.5.1 Customization Parameters
bbdb-notice-hook 1.5.2 Customization Hooks
bbdb-notice-hook 1.5.3 Predefined Hooks
bbdb-offer-save 1.5.1 Customization Parameters
bbdb-pop-up-elided-display 1.5.1 Customization Parameters
bbdb-pop-up-target-lines 1.5.1 Customization Parameters
bbdb-quiet-about-name-mismatches 1.5.1 Customization Parameters
bbdb-readonly-p 1.5.1 Customization Parameters
bbdb-send-mail-style 1.3 BBDB Mode
bbdb-use-alternate-names 1.5.1 Customization Parameters
bbdb-use-pop-up 1.5.1 Customization Parameters
bbdb-user-mail-names 1.5.1 Customization Parameters
bbdb/gnus-header-prefer-real-names 1.5.1 Customization Parameters
bbdb/gnus-header-show-bbdb-names 1.5.1 Customization Parameters
bbdb/gnus-lines-and-from-length 1.5.1 Customization Parameters
bbdb/gnus-mark-known-posters 1.5.1 Customization Parameters
bbdb/mail-auto-create-p 1.5.1 Customization Parameters
bbdb/mail-auto-create-p 1.5.3 Predefined Hooks
bbdb/news-auto-create-p 1.5.1 Customization Parameters
bbdb/news-auto-create-p 1.5.3 Predefined Hooks

Jump to:   B  

[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on May 19, 2025 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on May 19, 2025 using texi2html 5.0.