X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/0d1c5f533f3a6cd1c7f038f59585378f53b666c2..ecd50cc5f6c2a427e821483993678b78c94ffdfd:/man/msgchk.man

diff --git a/man/msgchk.man b/man/msgchk.man
index 973fb4ba..ce112cb6 100644
--- a/man/msgchk.man
+++ b/man/msgchk.man
@@ -1,100 +1,203 @@
-.\"
+.TH MSGCHK %manext1% 2016-11-02 "%nmhversion%"
+.
 .\" %nmhwarning%
-.\" $Id$
-.\"
-.\" include the -mh macro file
-.so %etcdir%/tmac.h
-.\"
-.TH MSGCHK %manext1% MH.6.8 [%nmhversion%]
+.
 .SH NAME
-msgchk \- check for messages
+msgchk \- nmh's check for incoming email
 .SH SYNOPSIS
-.in +.5i
-.ti -.5i
-msgchk
-\%[\-date] \%[\-nodate]
-\%[\-notify\ all/mail/nomail]
-.br
-\%[\-nonotify\ all/mail/nomail]
-.br
-%nmhbeginpop%
-\%[\-host\ hostname]
-\%[\-user\ username]
-\%[\-kpop]
-.br
-%nmhendpop%
-\%[users\ ...]
-\%[\-version]
-\%[\-help]
-.in -.5i
+.HP 5
+.na
+.B msgchk
+.RB [ \-help ]
+.RB [ \-version ]
+.RB [ \-date " | " \-nodate ]
+.RB [ \-notify
+all/mail/nomail ]
+.RB [ \-nonotify
+all/mail/nomail ]
+.RB [ \-host
+.IR hostname ]
+.RB [ \-user
+.IR username ]
+.RB [ \-sasl " | " \-nosasl ]
+.RB [ \-saslmech
+.IR mechanism ]
+.RB [ \-initialtls ]
+.RB [ \-notls ]
+.RB [ \-certverify " | " \-nocertverify ]
+.RB [ \-authservice
+.IR service ]
+.RB [ \-snoop ]
+.RI [ users
+\&... ]
+.ad
 .SH DESCRIPTION
-The \fImsgchk\fR program checks all known mail drops for mail waiting
-for you.  For those drops which have mail for you, \fImsgchk\fR will
+The
+.B msgchk
+program checks all known mail drops for mail waiting
+for you.  For those drops which have mail for you,
+.B msgchk
+will
 indicate if it believes that you have seen the mail in question before.
-
-The `\-notify\ type' switch indicates under what circumstances
-\fImsgchk\fR should produce a message.  The default is `\-notify\ all'
-which says that \fImsgchk\fR should always report the status of the
-users maildrop.  Other values for `type' include `mail' which says that
-\fImsgchk\fR should report the status of waiting mail; and, `nomail'
-which says that \fImsgchk\fR should report the status of empty maildrops.
-The `\-nonotify\ type' switch has the inverted sense, so
-`\-nonotify\ all' directs \fImsgchk\fR to never report the status of
-maildrops.  This is useful if the user wishes to check \fImsgchk\fR's
-exit status.  A non\-zero exit status indicates that mail was \fBnot\fR
+.PP
+The
+.B \-notify
+.I type
+switch indicates under what circumstances
+.B msgchk
+should produce a message.  The default is
+.B \-notify
+.I all
+which says that
+.B msgchk
+should always report the status of the
+users mail drop.  Other values for `type' include `mail' which says that
+.B msgchk
+should report the status of waiting mail; and, `nomail'
+which says that
+.B msgchk
+should report the status of empty mail drops.
+The
+.B \-nonotify
+.I type
+switch has the inverted sense, so
+.B \-nonotify
+.I all
+directs
+.B msgchk
+to never report the status of
+mail drops.  This is useful if the user wishes to check
+.BR msgchk 's
+exit status.  A non-zero exit status indicates that mail was
+.I not
 waiting for at least one of the indicated users.
-
-If \fImsgchk\fR produces output, then the `\-date' switch directs
-\fImsgchk\fR to print out the last date mail was read, if this can
+.PP
+If
+.B msgchk
+produces output, then the
+.B \-date
+switch directs
+.B msgchk
+to print out the last date mail was read, if this can
 be determined.
-%nmhbeginpop%
- 
-.Uh "Using POP"
-\fImsgchk\fR will normally check all the local mail drops, but if
+.SS "Using POP"
+.B msgchk
+will normally check all the local mail drops, but if
 the option \*(lqpophost:\*(rq is set in the mts configuration file
-\*(lqmts.conf\*(rq, or if the `\-host\ hostname' switch is given,
-\fImsgchk\fR will query this POP service host as to the status of
+\*(lqmts.conf\*(rq, or if the
+.B \-host
+.I hostname
+switch is given,
+.B msgchk
+will query this POP service host as to the status of
 mail waiting.
-
-The default is for \fImsgchk\fR to assume that your account name
-on the POP server is the same as your current username.  To specify
-a different username, use the `\-user\ username' switch.
-
-When using POP, you will normally need to type the password for
-your account on the POP server, in order to retrieve your messages.
-It is possible to automate this process by creating a \*(lq.netrc\*(rq
-file containing your login account information for this POP server.
-For each POP server, this file should have a line of the following
-form.  Replace the words mypopserver, mylogin, and mypassword with
-your own account information.
-
-machine mypopserver login mylogin password mypassword
-
-This \*(lq.netrc\*(rq file should be owned and readable only by
-you.
-
-For debugging purposes, there is also a switch `\-snoop', which will
+.PP
+To specify a username for authentication with the POP server, use the
+.B \-user
+.I username
+switch.  The credentials profile entry in the mh\-profile(5) man page
+describes the ways to supply a username and password.
+.PP
+For debugging purposes, there is also a switch
+.BR \-snoop ,
+which will
 allow you to watch the POP transaction take place between you and the
-POP server.
-
-If nmh has been compiled with KPOP #defined, but without POPSERVICE being set to
-"kpop", the -kpop switch may be specified to cause the use of Kerberized POP
-rather than standard POP3 during a given invocation of \fImsgchk\fR.
-%nmhendpop%
-.Fi
-^$HOME/\&.mh\(ruprofile~^The user profile
-^%etcdir%/mts.conf~^nmh mts configuration file
+POP server.  If
+.B \-sasl \-saslmech xoauth2
+is used, the HTTP transaction is also shown.
+.PP
+If
+.B nmh
+has been compiled with SASL support, the
+.B \-sasl
+switch will enable
+the use of SASL authentication.  Depending on the SASL mechanism used, this
+may require an additional password prompt from the user (but the
+.I netrc
+file can be used to store this password, as described in the
+mh-profile(5) man page).  The
+.B \-saslmech
+switch can be used to select a particular SASL mechanism.
+.PP
+If SASL authentication is successful,
+.B msgchk
+will attempt to negotiate
+a security layer for session encryption.  Encrypted traffic is labelled
+with `(encrypted)' and `(decrypted)' when viewing the POP transaction
+with the
+.B \-snoop
+switch; see the
+.B post
+man page description of
+.B \-snoop
+for its other features.
+.PP
+If
+.B nmh
+has been compiled with OAuth support, the
+.B \-sasl \-saslmech xoauth2
+switch will enable OAuth authentication.  The
+.B \-user
+switch must be used, and the
+.I user-name
+must be an email address the user has for the service, which must
+be specified with the
+.B \-authservice
+.I service
+switch.  Before using this, the user must authorize nmh by running
+.B mhlogin
+and grant authorization to that account.  See the
+.B mhlogin
+man page for more details.
+.PP
+If
+.B nmh
+has been compiled with TLS support, the
+.B \-initialtls
+switch will require the negotiation of TLS when connecting
+to the remote POP server.  The
+.B \-initialtls
+switch will negotiate TLS immediately after the connection has taken place,
+before any POP commands are sent or received.  Data encrypted by TLS is
+labeled `(tls-encrypted)' and `(tls-decrypted)` with viewing the POP
+transaction with the
+.B \-snoop
+switch.  The
+.B \-notls
+switch will disable all attempts to negotiate TLS.
+.PP
+When using TLS the default is to verify the remote certificate and SubjectName
+against the local trusted certificate store.  This can be controlled by
+the
+.B \-certverify
+and
+.B \-nocertverify
+switches.  See your OpenSSL documentation for more information on certificate
+verification.
+.SH FILES
+.fc ^ ~
+.nf
+.ta \w'%nmhetcdir%/ExtraBigFileName  'u
+^$HOME/.mh_profile~^The user profile
+^%nmhetcdir%/mts.conf~^nmh mts configuration file
 ^%mailspool%/$USER~^Location of mail drop
-.Pr
+.fi
+.SH "PROFILE COMPONENTS"
+.fc ^ ~
+.nf
+.ta 2.4i
+.ta \w'ExtraBigProfileName  'u
 None
-.Sa
-inc(1)
-.De
-`user' defaults to the current user
-.Ds
-`\-date'
-.Ds
-`\-notify\ all'
-.Co
+.fi
+.SH "SEE ALSO"
+.IR inc (1),
+.IR mh\-mail (5),
+.IR post (8)
+.SH DEFAULTS
+.nf
+.RB ` user "' defaults to the current user"
+.RB ` \-date '
+.RB ` "\-notify\ all" '
+.fi
+.SH CONTEXT
 None
-.En