diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index 66867cbc58788e06b5f0a2c3f888f1223b92c069..345e6fa3cdeb74ffab9e0654d816545fcedb34ae 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -85,6 +85,8 @@ LDAP, Lightweight Directory Access Protocol CCSO PH/QI @item BBDB, Big Brother's Insidious Database +@item +macOS Contacts @end itemize The main features of the EUDC interface are: @@ -110,6 +112,7 @@ Interface to BBDB to let you insert server records into your own BBDB database * LDAP:: What is LDAP ? * CCSO PH/QI:: What is CCSO, PH, QI ? * BBDB:: What is BBDB ? +* macOS Contacts:: What is macOS Contacts ? @end menu @@ -175,17 +178,29 @@ and news readers. It is often used as an enhanced email address book. EUDC considers BBDB as a directory server back end just like LDAP or -PH/QI servers, though BBDB has no client/server protocol and thus always -resides locally on your machine. The point in this is not to offer an -alternate way to query your BBDB database (BBDB itself provides much -more flexible ways to do that), but rather to offer an interface to your -local directory that is consistent with the interface to external -directories (LDAP, PH/QI). This is particularly interesting when -performing queries on multiple servers. +PH/QI servers, though BBDB has no client/server protocol and thus +always resides locally on your machine. This is particularly +interesting when performing queries on multiple servers. EUDC also offers a means to insert results from directory queries into your own local BBDB (@pxref{Creating BBDB Records}) + +@node macOS Contacts +@section macOS Contacts + +macOS Contacts is the rolodex-like application that ships with the +macOS operating system@footnote{Apple have changed the names of their +operating system and some applications over time. macOS used to be +called Mac OS X in the past, and the Contacts application was +previously called Address Book.}. + +EUDC considers macOS Contacts as a directory server back end just like +LDAP or PH/QI servers, though the macOS Contacts application always +resides locally on your machine. This is particularly interesting +when performing queries on multiple servers. + + @node Installation @chapter Installation @@ -214,6 +229,7 @@ email composition buffers (@pxref{Inline Query Expansion}) @menu * LDAP Configuration:: EUDC needs external support for LDAP +* macOS Contacts Configuration:: Enable the macOS Contacts backend @end menu @node LDAP Configuration @@ -339,6 +355,39 @@ and the @file{.emacs} expressions become: (customize-set-variable 'ldap-host-parameters-alist '(("" auth-source t))) @end lisp + +@node macOS Contacts Configuration +@section macOS Contacts Configuration + +macOS Contacts support is added by means of @file{eudcb-mab.el}, or +@file{eudcb-macos-contacts.el} which are part of Emacs. + +To enable a macOS Contacts backend, first `require' the respective +library to load it, and then set the `eudc-server' to localhost in +your init file: +@lisp +(require 'eudcb-macos-contacts) +(eudc-macos-contacts-set-server "localhost") +@end lisp + +@file{eudcb-macos-contacts.el} uses the public scripting interfaces +offered by the Contacts app via the macOS Open Scripting Architecture +(OSA). To accomplish this, @file{eudcb-macos-contacts.el} uses an +external command line utility named osascript, which is included with +all macOS versions since 10.0 (which was released 2001). +@file{eudcb-macos-contacts.el} is hence recommended for all new +configurations. + +@file{eudcb-mab.el} reverse engineers the format of the database file +used by the macOS Contacts app, and accesses its contents directly. +While this may promise some performance advantages, it comes at the +cost of using an undocumented interface. Hence, users of +@file{eudcb-mab.el} are recommended to double check the compatibility +of @file{eudcb-mab.el} before upgrading to a new version of macOS. +@file{eudcb-mab.el} is retained for backwards compatibility with +existing configurations, and may be removed in a future release. + + @node Usage @chapter Usage