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] | [ ? ] |
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:
1.1 Installation | ||
1.2 Introduction | ||
1.3 BBDB Mode | ||
1.4 Interfaces | ||
1.5 Options | ||
1.6 The Mailing List | info-bbdb-request@lucid.com | |
1.7 The Latest Version | Where to Get It | |
1.8 Todo List | ||
• Thanks | to the Ministry of Bugs | |
Concept Index | ||
Variable Index |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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:
The name of this person, or none if it’s an organization.
A list of other names of this person.
The name of this person’s organization, or none.
A list of this person’s network addresses.
A list of postal (physical) addresses for this person.
A list of telephone numbers for this person.
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] | [ ? ] |
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.
(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.
(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).
(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
.
(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.)
(bbdb-next-record
, bbdb-prev-record
) Move to the next and
previous displayed record, respectively.
(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.
(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.
(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.
(bbdb-save-db
) Saves the BBDB file to disk.
(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
.
(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.)
(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.
(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.
(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] | [ ? ] |
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.
1.4.1 Mail Reading Interfaces | ||
1.4.2 News Reading Interfaces | ||
1.4.3 Mail Sending Interfaces |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are BBDB interfaces for the following mail readers:
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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.
1.5.1 Customization Parameters | ||
1.5.2 Customization Hooks | ||
1.5.3 Predefined Hooks |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
bbdb-create-internal
function should be more
forgiving.
vm-select-message-hook
and yell at Kyle
until he puts it in. :-)
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
Jump to: | *
A B C D E F G I M N O P R S T U |
---|
Jump to: | *
A B C D E F G I M N O P R S T U |
---|
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Jump to: | B |
---|
Jump to: | B |
---|
[Top] | [Contents] | [Index] | [ ? ] |
[Top] | [Contents] | [Index] | [ ? ] |
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.