Re: [PATCH v4 2/3] docs: improve send-email documentation

[Junio C Hamano <gitster@pobox.com>]

> -EXAMPLES
> ---------
> -Use gmail as the smtp server
> +EXAMPLES OF SMTP SERVERS
> +------------------------
> +Use Gmail as the SMTP Server

Nice to see that you got the capitalization got right while at it.

>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -To use 'git send-email' to send your patches through the GMail SMTP server,
> -edit ~/.gitconfig to specify your account settings:
> +To use 'git send-email' to send your patches through the Gmail SMTP server,
> +edit '~/.gitconfig' to specify your account settings:

The four single quotes above should probably be changed to back
quotes, to match the "You can also use OAuth2.0..." below.

> @@ -528,6 +528,37 @@ If you have multi-factor authentication set up on your Gmail account, you can
>  generate an app-specific password for use with 'git send-email'. Visit
>  https://security.google.com/settings/security/apppasswords to create it.
>  
> +You can also use OAuth2.0 authentication with Gmail. To do this, edit your
> +`~/.gitconfig` file and add `smtpAuth = OAUTHBEARER` to your account settings:
> +
> +----
> +[sendemail]
> +	smtpEncryption = tls
> +	smtpServer = smtp.gmail.com
> +	smtpUser = yourname@gmail.com
> +	smtpServerPort = 587
> +	smtpAuth = OAUTHBEARER
> +----
> +
> +Use Microsoft Outlook as the SMTP Server
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Unlike Gmail, Microsoft Outlook no longer supports app-specific passwords.
> +Therefore, OAuth2.0 authentication must be used for Outlook.
> +
> +Edit '~/.gitconfig' to specify your account settings for Outlook and use its
> +SMTP server with 'git send-email':
> +
> +----
> +[sendemail]
> +	smtpEncryption = tls
> +	smtpServer = smtp.office365.com
> +	smtpUser = yourname@outlook.com
> +	smtpServerPort = 587
> +	smtpAuth = XOAUTH2
> +----

Just for my education, the above description does say why Outlook
needs to use OAuth2.0, but does not hint the reason for the
difference between the two example, OAUTHBEARER vs XOAUTH2.  Do
these two services support both, or does Gmail support only
OAUTHBEARER while Outlook supports only XOAUTH2?  

Given that the former is described in RFC and the latter sometimes
described as "Proprietary Google extension, not a standard", it is
somewhat funny to see that Gmail example uses OAUTHBEARER while
Outlook example uses XOAUTH2.

> +SENDING PATCHES
> +---------------
>  Once your commits are ready to be sent to the mailing list, run the
>  following commands:
>  
> @@ -536,9 +567,23 @@ following commands:
>  	$ git send-email outgoing/*
>  
>  The first time you run it, you will be prompted for your credentials.  Enter the
> -app-specific or your regular password as appropriate.  If you have credential
> -helper configured (see linkgit:git-credential[1]), the password will be saved in
> -the credential store so you won't have to type it the next time.
> +app-specific or your regular password as appropriate.
> +
> +If you have a credential helper configured (see linkgit:git-credential[1]), the
> +password will be saved in the credential store so you won't have to type it the
> +next time.
> +
> +If you are using OAuth2.0 authentication, you need to use an access token in
> +place of a password when prompted. Various OAuth2.0 token generators are
> +available online. Community maintained credential helpers for Gmail and Outlook
> +are also available:
> +
> +	- https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail] (cross platform, dedicated helper for authenticating Gmail accounts)
> +
> +	- https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook] (cross platform, dedicated helper for authenticating Microsoft Outlook accounts)

Given that this will be formatted via AsciiDoc (or asciidoctor),
would it make sense to make it easier for readers of the source
document by folding lines, like:

	- https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail]
	  (cross platform, dedicated helper for authenticating Gmail accounts)

	- https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook]
	  (cross platform, dedicated helper for authenticating Microsoft Outlook accounts)

or something?

Other than that, very nicely done.  Thanks.