Re: [Proposal] New EUDC backend for macOS address book

[Thomas Fitzsimmons <fitzsim@fitzsim.org>]

Hi Alexander,

Alexander Adolf <alexander.adolf@condition-alpha.com> writes:

> Hello Thomas, Emacs Developers,
>
> Thomas Fitzsimmons <fitzsim@fitzsim.org> writes:
>
>>>> [...]
>>>> You can make the changes to eudc.texi, create a patch, then reply to
>>>> this message with the patch attached.
>>>> [...]
>
> Apologies for the delay! Please kindly find the patch attached.
>
> What I did:
>
> • Under "Overview", I added a new @section, paralleling what already
>   existed for BBDB.
>
> • Since the backend is not enabled by default, I have also added a new
>   @section under "Installation". That new section, besides telling how
>   to enable the macOS Contacts backend, also describes the two available
>   backends, and how they differ. The text also deprecates the
>   pre-existing eudcb-mab.el, and recommends the new
>   eudcb-macos-contacts.el for new configurations.

Thanks for writing this.

> diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi
> index 66867cbc58..0cea3126a0 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
>  
>  
> @@ -186,6 +189,31 @@ 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
> +
> +@url{https://support.apple.com/guide/contacts/welcome/mac,, 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.}.

Probably leave out the links to apple.com throughout.

> [...] It is tightly integrated with the
> +other Apple applications (Mail, Calendar, etc.), and can synchronise
> +contacts information between Apple devices via CardDAV servers (such
> +as e.g. iCloud).

Can you remove the above sentence, since it's not relevant to the Emacs
integration?

> +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.

Looks good.

> [...] The point in this is not to offer an
> +alternate way to query your macOS Contacts database (the macOS
> +Contacts application 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).

I would leave this sentence out.  I expect some users will find it
useful as an alternate way of querying macOS Contacts, so as not to need
to switch to the other application, and for other reasons.  I don't want
the manual to imply that it's not worth extending your EUDC backend in
that direction, e.g., allowing writing complex queries in Elisp.  I
think the long term goal should be to make EUDC/Emacs better than these
external tools at managing contact information.

> [...] This is particularly interesting when performing queries on
> +multiple servers.
>
> +
> +
>  @node Installation
>  @chapter Installation
>  
> @@ -214,6 +242,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 +368,42 @@ 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.
> +
> +@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.

Nice summary.

> +@file{eudcb-macos-contacts.el} uses the public scripting interfaces
> +offered by the Contacts app via the macOS
> +@url{https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptX/Concepts/osa.html,,
> +Open Scripting Architecture (OSA)}.  To accomplish this,
> +@file{eudcb-macos-contacts.el} uses an external command line utility
> +named
> +@url{https://developer.apple.com/library/archive/documentation/OpenSource/Conceptual/ShellScripting/AdvancedTechniques/AdvancedTechniques.html#//apple_ref/doc/uid/TP40004268-TP40003521-SW44,,
> +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.
> +
> +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

I think you should move this how-to paragraph to just under the one that
begins "Contacts support is added [...]".  Users interested in the
history can read on.  You can probably list/describe
eudcb-macos-contacts.el before eudcb-mab.el, since it's the more
recommended option.

Thomas