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