From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Alexander Adolf Newsgroups: gmane.emacs.devel Subject: Re: [Proposal] New EUDC backend for macOS address book Date: Thu, 09 Jul 2020 17:12:38 +0200 Message-ID: <6b3f662271587fae0f88a5130e55d02e@condition-alpha.com> References: <8da7df5281e91d8a351f97c0837d79b7@condition-alpha.com> <298df6a619aa45393b0ae9250123faef@condition-alpha.com> <866ca4b62cf30015aa28bfb9a2566dff@condition-alpha.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="5145"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Jean-Christophe Helary , emacs-devel@gnu.org To: Thomas Fitzsimmons Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Jul 09 17:15:05 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jtYGO-0001BC-Bb for ged-emacs-devel@m.gmane-mx.org; Thu, 09 Jul 2020 17:15:04 +0200 Original-Received: from localhost ([::1]:53234 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jtYGN-0000Tf-Dv for ged-emacs-devel@m.gmane-mx.org; Thu, 09 Jul 2020 11:15:03 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:43160) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jtYEB-0006vP-OL for emacs-devel@gnu.org; Thu, 09 Jul 2020 11:12:51 -0400 Original-Received: from smtprelay05.ispgateway.de ([80.67.31.93]:48614) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jtYE8-0000MM-HX for emacs-devel@gnu.org; Thu, 09 Jul 2020 11:12:47 -0400 Original-Received: from [46.244.218.218] (helo=condition-alpha.com) by smtprelay05.ispgateway.de with esmtpsa (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.92.3) (envelope-from ) id 1jtYE2-0000da-Pd; Thu, 09 Jul 2020 17:12:38 +0200 In-Reply-To: <866ca4b62cf30015aa28bfb9a2566dff@condition-alpha.com> X-Df-Sender: YWxleGFuZGVyLmFkb2xmQGNvbmRpdGlvbi1hbHBoYS5jb20= Received-SPF: pass client-ip=80.67.31.93; envelope-from=alexander.adolf@condition-alpha.com; helo=smtprelay05.ispgateway.de X-detected-operating-system: by eggs.gnu.org: First seen = 2020/07/09 11:12:40 X-ACL-Warn: Detected OS = Linux 3.11 and newer [fuzzy] X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:252796 Archived-At: --=-=-= Content-Type: text/plain 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 --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=eudc.texi.patch 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 --=-=-=--