From 5f160cfbe843992ef1eb6aac5fb3e03a7e320fd2 Mon Sep 17 00:00:00 2001
From: Kevin McCarthy <kevin@8t8.us>
Date: Wed, 7 Nov 2018 13:38:53 -0800
Subject: [PATCH] Add some brief documentation on OAUTH support

These are just pulled from Brandon's commit message.
---
 doc/manual.xml.head | 33 +++++++++++++++++++++++++++++++++
 init.h              |  6 +++---
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 088fe1a79..7b077c226 100644
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -10822,6 +10822,39 @@ set timeout=15
       </para>
     </sect1>
 
+    <sect1 id="oauth">
+      <title>OAUTHBEARER Support</title>
+      <para>
+        Preliminary OAUTH support for IMAP, POP, and SMTP is provided via external scripts.
+      </para>
+      <para>
+        At least for Gmail, you can use the <literal>oauth2.py</literal>script
+        from Google's gmail-oauth2-tools:
+        <ulink url="https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py">https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py</ulink>
+      </para>
+      <para>
+        You'll need to get your own oauth client credentials for Gmail here: 
+        <ulink url="https://console.developers.google.com/apis/credentials">https://console.developers.google.com/apis/credentials</ulink>
+      </para>
+      <para>
+        Then, you'd use <literal>oauth2.py</literal> with
+        <literal>--generate_oauth2_token</literal> to get a refresh token, and
+        configure mutt with:
+      </para>
+
+<screen>
+set imap_authenticators="oauthbearer"
+set imap_oauth_refresh_command="/path/to/oauth2.py --quiet --user=[email_address]\
+    --client_id=[client_id] --client_secret=[client_secret]\
+    --refresh_token=[refresh_token]"
+</screen>
+
+      <para>
+        Substitute pop or smtp for imap in the above example to configure for
+        those.
+      </para>
+    </sect1>
+
     <sect1 id="account-hook">
       <title>Managing Multiple Accounts</title>
       <para>
diff --git a/init.h b/init.h
index a8e5f3c14..380d04339 100644
--- a/init.h
+++ b/init.h
@@ -1495,7 +1495,7 @@ struct ConfigDef MuttVars[] = {
   ** The command to run to generate an OAUTH refresh token for
   ** authorizing your connection to your IMAP server.  This command will be
   ** run on every connection attempt that uses the OAUTHBEARER authentication
-  ** mechanism.
+  ** mechanism.  See ``$oauth'' for details.
   */
   { "imap_pass",        DT_STRING,  R_NONE|F_SENSITIVE, &ImapPass, 0 },
   /*
@@ -2817,7 +2817,7 @@ struct ConfigDef MuttVars[] = {
   ** The command to run to generate an OAUTH refresh token for
   ** authorizing your connection to your POP server.  This command will be
   ** run on every connection attempt that uses the OAUTHBEARER authentication
-  ** mechanism.
+  ** mechanism.  See ``$oauth'' for details.
   */
   { "pop_pass",         DT_STRING,  R_NONE|F_SENSITIVE, &PopPass, 0 },
   /*
@@ -3872,7 +3872,7 @@ struct ConfigDef MuttVars[] = {
   ** The command to run to generate an OAUTH refresh token for
   ** authorizing your connection to your SMTP server.  This command will be
   ** run on every connection attempt that uses the OAUTHBEARER authentication
-  ** mechanism.
+  ** mechanism.  See ``$oauth'' for details.
   */
   { "smtp_pass",        DT_STRING,  R_NONE|F_SENSITIVE, &SmtpPass, 0 },
   /*
-- 
2.40.0