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

[Alexander Adolf]

Thomas, Emacs Developers,

Thomas Fitzsimmons <fitzsim@fitzsim.org> writes:

> [...]
> I had already followed up a while ago:
>
>    https://lists.gnu.org/archive/html/emacs-devel/2020-06/msg00360.html
> 
> Did you see that?
> [...]

Oops, my bad; apparently that one slipped by me.

Thomas Fitzsimmons <fitzsim@fitzsim.org> writes:

> [...]
>> +
>> +@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.

Good point; probably want to remain as neutral as possible.

>> [...] 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?

No strong feelings about this text; happy to remove. I was attempting to
roughly duplicate what pre-existed for BBDB (but which was talking about
"tight integration with the Emacs mail and news readers", not 3rd party
stuff).

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

Agree; happy to drop.

Again, this is copy/paste/adapt from the corresponding BBDB section. In
the revised version (diff attached) I have hence also removed the
corresponding, almost identical, sentence from the BBDB section.

>> [...] 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.
> [...]

Done.

The attached diff incorporates all you suggestions.


Many thanks for your support, and looking forward to your thoughts,

  --alexander

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