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
