Improve these comments a bit.

[nmh] / man / mhlogin.man

diff --git a/man/mhlogin.man b/man/mhlogin.man
index 0651fdca7dab9185541c88db1485fa5f7650c638..eb067ea5ff69f5d98b3b3115b2a49b2cb6efc7c2 100644 (file)
--- a/man/mhlogin.man
+++ b/man/mhlogin.man
@@ -1,15 +1,21 @@
 .\"
 .\" %nmhwarning%
 .\"
-.TH SEND %manext1% "November 25, 2014" "%nmhversion%"
+.TH MHLOGIN %manext1% "September 11, 2016" "%nmhversion%"
 .SH NAME
 mhlogin \- login to external (OAuth) services
 .SH SYNOPSIS
 .HP 5
 .na
 .B mhlogin
-.RB \-oauth
-.IR service
+.RB [ \-user
+.IR username ]
+.RB [ \-saslmech
+.IR mechanism ]
+.RB [ \-authservice
+.IR service ]
+.RB [ \-browser
+.IR command ]
 .RB [ \-snoop ]
 .RB [ \-version ]
 .RB [ \-help ]
@@ -18,7 +24,10 @@ mhlogin \- login to external (OAuth) services
 .B Mhlogin
 currently only supports OAuth for Gmail.  Run
 .B mhlogin
-.B -oauth
+.B \-user
+.I username
+.B \-saslmech xoauth2
+.B \-authservice
 .I gmail
 and load the printed URL in your browser.  Login to a Gmail account, grant
 authorization, and copy and paste the code into the
@@ -26,7 +35,17 @@ authorization, and copy and paste the code into the
 prompt.  Be sure to use the same account with the
 .B -user
 switch to
-.B send
+.BR send .
+.PP
+The
+.B \-browser
+switch causes
+.B mhlogin
+to load the URL directly into a new browser session.  The command argument
+must include the browser invocation name, and can include any browser arguments
+in the
+.B \-browser
+argument string, e.g., 'google-chrome --new-window'.
 .PP
 The
 .B \-snoop
@@ -35,17 +54,34 @@ switch can be used to view the HTTP transaction.
 All parameters configuring the service may be overridden by profile components,
 and even though only Gmail is supported out of the box, the user can define
 new services entirely in the profile.  Profile components are prefixed by
-.I
-oauth-
-.I
-service-
-for example
+.IR oauth-service- ,
+for example,
 .I oauth-gmail-credential-file
 which specifies where
 .B mhlogin
 should write credentials and where
 .B send
 should read them.
+.SH "EXAMPLES"
+.PP
+.SS Gmail
+First, login to the Gmail account that you want to use, e.g, user@example.com,
+using a web browser.
+Then, enter a
+.B mhlogin
+command such as:
+.PP
+.RS
+.nf
+mhlogin -user user@example.com -saslmech xoauth2 -authservice gmail \
+-browser 'google-chrome --new-window'
+.fi
+.RE
+.PP
+Respond to the prompt in the browser window, then copy and paste the
+authorization code in response to the
+.B mhlogin
+prompt.
 .SH "PROFILE COMPONENTS"
 .fc ^ ~
 .nf
@@ -61,3 +97,7 @@ should read them.
 .fi
 .SH "SEE ALSO"
 .IR send (1)
+.SH DEFAULTS
+.nf
+.RB ` \-saslmech "' xoauth2"
+.fi