[emacs] update table of contents
[~bandali/configs] / lisp / bbdb / README
... / ...
CommitLineData
1Copyright (C) 2010-2017 Roland Winkler <winkler@gnu.org>
2See the end of the file for license conditions.
3
4BBDB is the Insidious Big Brother Database for GNU Emacs.
5It provides an address book for email and snail mail addresses,
6phone numbers and the like. It can be linked with various Emacs mail
7clients (Message and Mail mode, Rmail, Gnus, MH-E, Mu4e, VM, and
8Wanderlust). BBDB is fully customizable.
9
10BBDB is available at
11http://savannah.nongnu.org/projects/bbdb/
12To check it out, use
13git clone git://git.savannah.nongnu.org/bbdb.git
14
15Questions, comments, suggestions, and bug reports may be directed to
16the BBDB mailing list at bbdb-user@nongnu.org.
17To subscribe to this list, go to
18https://lists.nongnu.org/mailman/listinfo/bbdb-user.
19
20==================================================================
21Installation: (see also the generic file INSTALL)
22
23To compile and install BBDB with `make':
24
250) (BBDB development version only)
26
27 Configure the configure process:
28
29 Run `autogen.sh' in the top directory of the BBDB code.
30 This creates the `configure' script required for step 1).
31
321) Configure the build process:
33
34 Run the `configure' script in the top directory of the BBDB code.
35 This performs a number of checks on your system and generates the
36 Makefiles accordingly. You need at least GNU Emacs 24.
37
38 The `configure' script comes with various options:
39
40 `--with-mu4e-dir=DIR' specifies the path where Mu4e can be found.
41 Without this option the resulting BBDB build does not support Mu4e.
42
43 `--with-vm-dir=DIR' specifies the path where VM can be found.
44 Without this option the resulting BBDB build does not support VM.
45
46 `--with-wl-dir=DIR' specifies the path where Wanderlust can be found.
47 Without this option the resulting BBDB build does not support WL.
48
49 `--with-lispdir=DIR' specifies where to install the lisp files.
50
51 Use `configure --help' to see all available options.
52
532) Build BBDB:
54
55 To build BBDB type 'make'.
56
57 If you use the BBDB development version, but you do not have autoconf,
58 go to the lisp directory and type 'make --makefile=./makefile-temp'.
59
603) Install BBDB:
61
62 To install BBDB type `make install'.
63 This installs all files in their usual system directories.
64 You can override these defaults via respective options
65 for the configure script.
66
67 The TeX files in the tex directories are installed in ${datadir}
68 which defaults to /usr/local/share/bbdb/. These files are only
69 used by BBDB. They need not be made known to your local TeX
70 installation. See the user variable bbdb-print-tex-path below.
71
72 `make install' is not required to run BBDB.
73
744) Activate BBDB:
75
76 i) If the BBDB lisp files are in a directory
77 "/path/to/bbdb/lisp" you can use in your emacs init file
78
79 (require 'bbdb-loaddefs "/path/to/bbdb/lisp/bbdb-loaddefs.el")
80
81 This adds "/path/to/bbdb/lisp" to the load-path; so it is all
82 you need to make BBDB known to your Emacs.
83
84 ii) The user variable bbdb-print-tex-path should point to the directory
85 where the BBDB TeX files reside (default /usr/local/share/bbdb).
86
87===============================================================================
88Usage notes
89
90BBDB 3 is the first release of BBDB after a long time.
91Up to BBDB 3.1.2 it requires GNU Emacs 23 or newer.
92More recent versions require GNU Emacs 24 or newer.
93
94The code of BBDB 3 is still under development.
95While it should work reliably, users of previous versions of BBDB
96are advised that the format of the BBDB database file has changed.
97Migration to the new format should happen automatically.
98Yet it is recommended to make a copy of the old file, in case
99something unexpected happens or you might want to go back.
100
101As compared with BBDB 2.xx, many variables, functions, and commands
102have changed in BBDB 3. Most likely you will have to review your
103customizations carefully. You may want to call bbdb-undocumented-variables
104to identify outdated (i.e., now usually undocumented) variables in
105your init file. Those upgrading from BBDB 2.xx may also find this
106Emacs wiki page helpful: https://www.emacswiki.org/emacs/UpgradeBBDB
107All user variables for the core of BBDB 3 are listed at the beginning
108of bbdb.el. Some extensions of BBDB 3 define their user variables
109at the beginning of the respective files.
110
111Generally the default values for user variables are chosen such that they make
112BBDB the least aggressive. You can customize this behavior in many ways.
113See below for an overview.
114
115The BBDB info manual is still awaiting a more complete overhaul.
116
117
118BBDB interface with mail user agents (MUAs)
119===========================================
120
121BBDB can interface with various mail user agents (MUAs).
122These include Rmail, Gnus, VM, MH-E, Mu4e, Wanderlust, Message and Mail mode.
123This lets you
124
125 - display the BBDB records for the sender and/or recipients of a
126 message you are viewing
127
128 - create or update the BBDB records for the sender and/or
129 recipients of a message
130
131 - add annotations to the BBDB records for the sender and/or
132 recipients of a message
133
134There are two ways for BBDB to interface with MUAs:
135
136Interactive commands
137--------------------
138
139Call bbdb-initialize (usually in your init file) to initialize
140the MUA interfaces based on interactive commands
141
142MUA commands include
143
144 bbdb-mua-display-records, bbdb-mua-display-sender, bbdb-mua-display-recipients
145 bbdb-annotate-record, bbdb-mua-annotate-sender, bbdb-mua-annotate-recipients
146 bbdb-mua-edit-field, bbdb-mua-edit-field-sender, bbdb-mua-edit-field-recipients
147
148These MUA commands operate either on existing records only. Or they
149can create new records.
150
151They are all controlled by bbdb-mua-update-interactive-p.
152This is a cons pair (WITHOUT-PREFIX . WITH-PREFIX).
153The car is used if the command is called without a prefix.
154The cdr is used if the command is called with a prefix (and if the prefix
155 is not used for another purpose).
156
157WITHOUT-PREFIX and WITH-PREFIX may take the values
158(here ADDRESS is an email address found in a message):
159 nil Do nothing.
160 search Search for existing records matching ADDRESS.
161 update Search for existing records matching ADDRESS;
162 update name and mail field if necessary.
163 query Search for existing records matching ADDRESS;
164 query for creation of a new record if the record does not exist.
165 create or t Search for existing records matching ADDRESS;
166 create a new record if it does not yet exist.
167 a function This functions will be called with no arguments.
168 It should return one of the above values (see below).
169 read Read the value interactively.
170
171BBDB 2 also used MUA-specific variables bbdb/MUA-update-records-mode
172to control its interfaces with MUAs. Use function bbdb-mua to define
173your own function to get MUA-specific values.
174
175Noninteractive functions
176------------------------
177
178Call bbdb-mua-auto-update-init (usually in your init file)
179to hook BBDB's hook function bbdb-mua-auto-update into the MUAs.
180
181bbdb-mua-auto-update automatically updates the BBDB records for the
182sender and/or recipients of a message. If bbdb-mua-pop-up is non-nil,
183the matching records are also displayed in a continuously updated BBDB window,
184
185The behavior of bbdb-mua-auto-update is controlled by bbdb-mua-auto-update-p.
186This may take the same values as bbdb-mua-update-interactive-p (except read).
187Binding this to a function is often most helpful for noninteractive use.
188For example, you may want to bind bbdb-mua-auto-update-p to the function
189bbdb-select-message, see bbdb-accept-message-alist and
190bbdb-ignore-message-alist. If a message is accepted by bbdb-select-message,
191the actual action performed by BBDB (i.e., the return value of
192bbdb-select-message) is given by bbdb-update-records-p.
193
194==================================================================
195
196Notes for BBDB lisp hackers:
197----------------------------
198
199If you write your own functions and commands to modify BBDB records,
200do not call the low-level functions bbdb-record-set-* such as
201bbdb-record-set-aka, bbdb-record-set-mail etc. The recommended
202sequence of calls is
203
204- one or multiple calls of bbdb-record-set-field for the respective
205 fields to be changed. This not only sets the fields, but it also
206 ensures the integrity of the database. Also, this makes your code
207 more robust with respect to possible future changes of BBDB's
208 innermost internals.
209
210- a call of bbdb-change-record which updates the database after a
211 change of record and redisplays the records.
212
213- To display newly created records call bbdb-display-records.
214
215==================================================================
216
217Copyright (C) 2010-2017 Roland Winkler <winkler@gnu.org>
218
219This file is part of the Insidious Big Brother Database (aka BBDB),
220
221BBDB is free software: you can redistribute it and/or modify
222it under the terms of the GNU General Public License as published by
223the Free Software Foundation, either version 3 of the License, or
224(at your option) any later version.
225
226BBDB is distributed in the hope that it will be useful,
227but WITHOUT ANY WARRANTY; without even the implied warranty of
228MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
229GNU General Public License for more details.
230
231You should have received a copy of the GNU General Public License
232along with BBDB. If not, see <http://www.gnu.org/licenses/>.