git.shemshak.org - ~bandali/configs/blob - lisp/bbdb/README

   1 Copyright (C) 2010-2017 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, Mu4e, VM, and
   8 Wanderlust).  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-user@nongnu.org.
  17 To subscribe to this list, go to
  18 https://lists.nongnu.org/mailman/listinfo/bbdb-user.
  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 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
  53 2) 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
  60 3) 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
  74 4) 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 ===============================================================================
  88 Usage notes
  89
  90 BBDB 3 is the first release of BBDB after a long time.
  91 Up to BBDB 3.1.2 it requires GNU Emacs 23 or newer.
  92 More recent versions require GNU Emacs 24 or newer.
  93
  94 The code of BBDB 3 is still under development.
  95 While it should work reliably, users of previous versions of BBDB
  96 are advised that the format of the BBDB database file has changed.
  97 Migration to the new format should happen automatically.
  98 Yet it is recommended to make a copy of the old file, in case
  99 something unexpected happens or you might want to go back.
 100
 101 As compared with BBDB 2.xx, many variables, functions, and commands
 102 have changed in BBDB 3.  Most likely you will have to review your
 103 customizations carefully.  You may want to call bbdb-undocumented-variables
 104 to identify outdated (i.e., now usually undocumented) variables in
 105 your init file.  Those upgrading from BBDB 2.xx may also find this
 106 Emacs wiki page helpful: https://www.emacswiki.org/emacs/UpgradeBBDB
 107 All user variables for the core of BBDB 3 are listed at the beginning
 108 of bbdb.el.  Some extensions of BBDB 3 define their user variables
 109 at the beginning of the respective files.
 110
 111 Generally the default values for user variables are chosen such that they make
 112 BBDB the least aggressive.  You can customize this behavior in many ways.
 113 See below for an overview.
 114
 115 The BBDB info manual is still awaiting a more complete overhaul.
 116
 117
 118 BBDB interface with mail user agents (MUAs)
 119 ===========================================
 120
 121 BBDB can interface with various mail user agents (MUAs).
 122 These include Rmail, Gnus, VM, MH-E, Mu4e, Wanderlust, Message and Mail mode.
 123 This 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
 134 There are two ways for BBDB to interface with MUAs:
 135
 136 Interactive commands
 137 --------------------
 138
 139 Call bbdb-initialize (usually in your init file) to initialize
 140 the MUA interfaces based on interactive commands
 141
 142 MUA 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
 148 These MUA commands operate either on existing records only.  Or they
 149 can create new records.
 150
 151 They are all controlled by bbdb-mua-update-interactive-p.
 152 This is a cons pair (WITHOUT-PREFIX . WITH-PREFIX).
 153 The car is used if the command is called without a prefix.
 154 The cdr is used if the command is called with a prefix (and if the prefix
 155         is not used for another purpose).
 156
 157 WITHOUT-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
 171 BBDB 2 also used MUA-specific variables bbdb/MUA-update-records-mode
 172 to control its interfaces with MUAs.  Use function bbdb-mua to define
 173 your own function to get MUA-specific values.
 174
 175 Noninteractive functions
 176 ------------------------
 177
 178 Call bbdb-mua-auto-update-init (usually in your init file)
 179 to hook BBDB's hook function bbdb-mua-auto-update into the MUAs.
 180
 181 bbdb-mua-auto-update automatically updates the BBDB records for the
 182 sender and/or recipients of a message.  If bbdb-mua-pop-up is non-nil,
 183 the matching records are also displayed in a continuously updated BBDB window,
 184
 185 The behavior of bbdb-mua-auto-update is controlled by bbdb-mua-auto-update-p.
 186 This may take the same values as bbdb-mua-update-interactive-p (except read).
 187 Binding this to a function is often most helpful for noninteractive use.
 188 For example, you may want to bind bbdb-mua-auto-update-p to the function
 189 bbdb-select-message,  see bbdb-accept-message-alist and
 190 bbdb-ignore-message-alist.  If a message is accepted by bbdb-select-message,
 191 the actual action performed by BBDB (i.e., the return value of
 192 bbdb-select-message) is given by bbdb-update-records-p.
 193
 194 ==================================================================
 195
 196 Notes for BBDB lisp hackers:
 197 ----------------------------
 198
 199 If you write your own functions and commands to modify BBDB records,
 200 do not call the low-level functions bbdb-record-set-* such as
 201 bbdb-record-set-aka, bbdb-record-set-mail etc.  The recommended
 202 sequence 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
 217 Copyright (C) 2010-2017 Roland Winkler <winkler@gnu.org>
 218
 219 This file is part of the Insidious Big Brother Database (aka BBDB),
 220
 221 BBDB is free software: you can redistribute it and/or modify
 222 it under the terms of the GNU General Public License as published by
 223 the Free Software Foundation, either version 3 of the License, or
 224 (at your option) any later version.
 225
 226 BBDB is distributed in the hope that it will be useful,
 227 but WITHOUT ANY WARRANTY; without even the implied warranty of
 228 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 229 GNU General Public License for more details.
 230
 231 You should have received a copy of the GNU General Public License
 232 along with BBDB.  If not, see <http://www.gnu.org/licenses/>.