branch: externals/excorporate commit bf16ed9e7702abf296206249f615108444a4281f Author: Thomas Fitzsimmons <fitz...@fitzsim.org> Commit: Thomas Fitzsimmons <fitz...@fitzsim.org>
Improve quick start documentation * excorporate.el (Commentary): Improve setup documentation. * excorporate.texi (Configuration): Likewise. * README: Improve quick start section. * NEWS: Mention improvement. --- NEWS | 2 ++ README | 15 +++++++++++++-- excorporate.el | 15 ++++++++++++--- excorporate.texi | 9 +++++---- 4 files changed, 32 insertions(+), 9 deletions(-) diff --git a/NEWS b/NEWS index 583c92f9bc..13f3a5a617 100644 --- a/NEWS +++ b/NEWS @@ -1,5 +1,7 @@ GNU Emacs Excorporate NEWS -- history of user-visible changes. +** Improve quick start documentation + ** Eliminate a warning issued by newer versions of Org Mode `exco-org-insert-meetings' was causing a warning, diff --git a/README b/README index 3f594750ea..0cefba2075 100644 --- a/README +++ b/README @@ -3,6 +3,8 @@ Excorporate provides Exchange integration for Emacs. Most Recent Improvements ------------------------ +** Improve quick start documentation + ** Eliminate a warning issued by newer versions of Org Mode New in Excorporate 1.1.2, released 2024-02-19: @@ -26,9 +28,18 @@ support. Quick Start ----------- +To deal with OAuth 2.0 refresh tokens, `url-http-oauth' needs to +programatically add and rewrite its own entries in netrc files listed +in the `auth-sources' variable (defaults being "~/.authinfo", +"~/.authinfo.gpg", "~/.netrc"). As a precaution please back up files +listed in `auth-sources' before using Excorporate OAuth 2.0 +authentication, in case there are bugs or bad interactions with other +packages. + Customize `excorporate-configuration'. To use OAuth 2.0, at a minimum -you will need to set the "client-identifier" and the "login_hint" -fields. +you will need to modify the "authorization-endpoint", +"access-token-endpoint", "client-identifier" (also known as +"Application ID") and "login_hint" fields. Then: diff --git a/excorporate.el b/excorporate.el index 618073ef4d..652b01380f 100644 --- a/excorporate.el +++ b/excorporate.el @@ -29,9 +29,18 @@ ;; Usage: -;; Customize `excorporate-configuration'. To use OAuth 2.0, at a -;; minimum you will need to set the "client-identifier" and the -;; "login_hint" fields. +;; To deal with OAuth 2.0 refresh tokens, `url-http-oauth' needs to +;; programatically add and rewrite its own entries in netrc files listed +;; in the `auth-sources' variable (defaults being "~/.authinfo", +;; "~/.authinfo.gpg", "~/.netrc"). As a precaution please back up files +;; listed in `auth-sources' before using Excorporate OAuth 2.0 +;; authentication, in case there are bugs or bad interactions with other +;; packages. + +;; Customize `excorporate-configuration'. To use OAuth 2.0, at a minimum +;; you will need to modify the "authorization-endpoint", +;; "access-token-endpoint", "client-identifier" (also known as +;; "Application ID") and "login_hint" fields. ;; Then: diff --git a/excorporate.texi b/excorporate.texi index 922177560e..b8888cf749 100644 --- a/excorporate.texi +++ b/excorporate.texi @@ -124,10 +124,11 @@ out-of-scope for this manual. The fields you @emph{must} change are ``client-identifier'' and ``login_hint''. ``authorization-endpoint'' and ``access-token-endpoint'' contain your organization's tenant identifier. `login_hint'' is the email address you use to sign in to -the server. How to obtain the tenant identifier and client-identifier -is not specified by the OAuth 2.0 specification and is out-of-scope -for this manual, however an excellent overview is provided by the -GNOME Wiki: @uref{https://wiki.gnome.org/Apps/Evolution/EWS/OAuth2}. +the server. How to obtain the tenant identifier and client identifier +(also known as ``Application ID'') is not specified by the OAuth 2.0 +specification and is out-of-scope for this manual, however an +excellent overview is provided by the GNOME Wiki: +@uref{https://wiki.gnome.org/Apps/Evolution/EWS/OAuth2}. @noindent For password authentication, you can try the minibuffer configuration