Thomas, Emacs Developers, Thomas Fitzsimmons 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 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