[elpa] externals/excorporate bf16ed9e77 2/6: Improve quick start documentation

[Thomas Fitzsimmons]

branch: externals/excorporate
commit bf16ed9e7702abf296206249f615108444a4281f
Author: Thomas Fitzsimmons <fitzsim@fitzsim.org>
Commit: Thomas Fitzsimmons <fitzsim@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