-.TH INC %manext1% "February 16, 2013" "%nmhversion%"
-.\"
+.TH INC %manext1% 2016-11-02 "%nmhversion%"
+.
.\" %nmhwarning%
-.\"
+.
.SH NAME
-inc \- incorporate new mail
+inc \- incorporate new mail to an nmh folder
.SH SYNOPSIS
.HP 5
.na
.B inc
+.RB [ \-help ]
+.RB [ \-version ]
.RI [ +folder ]
.RB [ \-audit
-.IR audit\-file ]
+.IR audit-file ]
.RB [ \-noaudit ]
.RB [ \-changecur " | " \-nochangecur ]
.RB [ \-form
.IR portname/number ]
.RB [ \-user
.IR username ]
-.RB [ \-pack
-.IR file ]
-.RB [ \-nopack ]
.RB [ \-proxy
.IR command ]
.RB [ \-sasl " | " \-nosasl ]
.RB [ \-saslmech
.IR mechanism ]
+.RB [ \-authservice
+.IR service ]
+.RB [ \-initialtls ]
+.RB [ \-notls ]
+.RB [ \-certverify " | " \-nocertverify ]
.RB [ \-snoop ]
-.RB [ \-version ]
-.RB [ \-help ]
.ad
.SH DESCRIPTION
-.B Inc
-incorporates mail from the user's incoming mail drop into
-an
+.B inc
+incorporates mail from the user's incoming mail drop into an
.B nmh
folder.
If the mail drop is a file, it can be in
or
.B MMDF
format.
-If the mail drop is a directory it will considered to be a
+If the mail drop is a directory it is considered to be in
.B Maildir
-format mail drop.
+format.
.PP
You may specify which folder to use with
.IR +folder .
If no folder is specified, then
.B inc
-will use either the folder given by a (non\-empty)
+will use either the folder given by a (non-empty)
.RI \*(lq Inbox \*(rq
entry in the user's profile, or the folder named
.RI \*(lq inbox \*(rq.
exist, the user will be queried prior to its creation.
.PP
When the new messages are incorporated into the folder, they are assigned
-numbers starting with the next highest number for the folder. As the
-messages are processed, a
+numbers starting with the next highest number for the folder.
+As the messages are processed, a
.B scan
listing of the new mail is produced.
.PP
-If the user's profile contains a
+The newly created messages will have a mode of 0600, see chmod(1),
+on filesystems that support it.
+Alternatively, a
.RI \*(lq "Msg\-Protect: nnn" \*(rq
-entry, it will be used as the protection on the newly created
-messages, otherwise the
-.B nmh
-default of 0600 will be used (on filesystems that support it). For
-all subsequent operations on these messages, this initially assigned
-protection will be preserved.
+profile entry gives the mode to use, in octal.
+For all subsequent operations on these messages, this initially assigned
+mode will be preserved.
.PP
If the switch
.B \-audit
-.I audit\-file
-is specified (usually as a default
-switch in the profile), then
+.I audit-file
+is specified (usually as a default switch in the user's profile), then
.B inc
-will append a header line and a
-line per message to the end of the specified audit\-file with the format:
+will append a header line and a line per message to the specified
+audit-file with the format:
.PP
.RS 5
.nf
.BR comp ,
and
.B dist
-may also produce audits to this (or another) file, perhaps with
+may also output audit information to this (or another) file, perhaps with
.RI \*(lq Message\-Id \*(rq
-information to keep an exact correspondence
-history.
-.RI \*(lq Audit\-file \*(rq
-will be in the user's nmh directory unless a full path is specified.
+information to keep an exact correspondence history.
+.RI \*(lq Audit-file \*(rq
+is assumed to be in the user's nmh directory unless a full path is specified.
.PP
-.B Inc
-will incorporate even improperly formatted messages into the
-user's nmh folder, inserting a blank line prior to the offending component
+.B inc
+will incorporate even improperly formatted messages into the user's
+nmh folder, inserting a blank line prior to the offending component
and printing a comment identifying the bad message.
.PP
-In all cases, the user's mail drop will be zeroed, unless the
+In all cases, except the use of
+.B \-file
+.I name
+(see below), the user's mail drop will be zeroed, unless the
.B \-notruncate
switch is given.
.PP
If the profile entry
.RI \*(lq Unseen\-Sequence \*(rq
-is present and non\-empty, then
+is present and non-empty, then
+.B inc
+will add each of the newly incorporated messages to each sequence
+named in the profile entry.
.B inc
-will add each of the newly incorporated messages to
-each sequence named by the profile entry.
-.B Inc
will not zero each sequence prior to adding messages.
.PP
The interpretation of the
.B \-width
.I columns
switches is the same as in
-.BR scan .
+.IR scan (1).
.PP
By using the
.B \-file
.I name
switch, one can direct
.B inc
-to incorporate messages from a file other than the user's maildrop.
-Note that the name file will NOT be zeroed, unless the
+to incorporate messages from a file other than the user's mail drop.
+Note that the named file will
+.I not
+be zeroed, unless the
.B \-truncate
switch is given.
.PP
The
.B \-file
-switch does not support use of standard input. Instead,
-the
+switch does not support the use of standard input.
+Instead, the
.B rcvstore
command can be used to incorporate mail from the standard input stream.
.PP
.B $MAILDROP
is set, then
.B inc
-uses it as the location of the user's maildrop instead of the default
+uses it as the location of the user's mail drop instead of the default
(the
.B -file
.I name
-switch still overrides this, however). If this
-environment variable is not set, then
+switch still overrides this, however).
+If this environment variable is not set, then
.B inc
will consult the profile entry
.RI \*(lq MailDrop \*(rq
-for this information. If the value found is
-not absolute, then it is interpreted relative to the user's
+for this information. If the value found is not absolute, then it is
+interpreted relative to the user's
.B nmh
directory. If the value is not found, then
.B inc
-will look in the standard system location for the user's maildrop.
+will look in the standard system location for the user's mail drop.
.PP
The
.B \-silent
to be quiet and not ask any questions at all. This is useful for putting
.B inc
in the background and going on to other things.
-.PP
.SS "Using POP"
.B inc
-will normally check local mail drops for mail, as covered above. But
-if the option
+will normally check local mail drops for mail, as covered above.
+But if the option
.RI \*(lq pophost \*(rq
is set in
.RI \*(lq mts.conf \*(rq,
.B $MAILHOST
is set and
.B \-host
-is specified as well, the commandline switch will override
+is specified as well, the command-line switch will override
the environment variable. The
.B \-port
switch specifies the port name or number used to connect to the POP
-server. If unspecified the default is \*(lqpop3\*(rq.
+server. If unspecified, the default is \*(lqpop3\*(rq.
.PP
-The default is for
-.B inc
-to assume that your account name on
-the POP server is the same as your current username. To specify
-a different username, use the
+To specify a username for authentication with the POP server, use the
.B \-user
.I username
-switch.
-.PP
-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
-.RI \*(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
-.IR mypopserver ,
-.IR mylogin ,
-and
-.I mypassword
-with your own account information.
-.PP
-.RS 5
-.B machine
-.I mypopserver
-.B login
-.I mylogin
-.B password
-.I mypassword
-.RE
-.PP
-This
-.RI \*(lq .netrc \*(rq
-file should be owned and readable only by you.
+switch. The credentials profile entry in
+.IR mh\-profile (5)
+describes the ways to supply a username and password.
.PP
If passed the
.B \-proxy
switch,
.B inc
will use the specified command to establish the connection to the POP
-server. The string
-.IR %h
+server. The string
+.I %h
in the command will be substituted by the hostname to connect to.
.PP
-If
-.B inc
-uses POP, then the
-.B \-pack
-.I file
-switch is considered. If given, then
-.B inc
-simply uses the POP to
-.B packf
-the user's maildrop from the POP service host to the named file. This switch
-is provided for those users who prefer to use
-.B msh
-to read their maildrops.
-.PP
For debugging purposes, you may give the switch
.BR \-snoop ,
-which will allow you to watch the POP transaction take place
-between you and the POP server.
+which will allow you to monitor the POP transaction. 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
-.RI \*(lq .netrc \*(rq
-file can be used to store this password). The
+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
+.IR mh\-profile (5)).
+The
.B \-saslmech
switch can be used to select a particular SASL mechanism.
.PP
Encrypted traffic is labelled with `(encrypted)' and `(decrypted)'
when viewing the POP transaction with the
.B \-snoop
-switch.
+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
+and
+.B \-saslmech xoauth2
+switches 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 granting authorization to that account. See
+.IR mhlogin (1)
+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.
+.B inc
+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)` when 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
.PD 0
.TP 20
-$HOME/.mh\-profile
+$HOME/.mh_profile
The user's profile.
.TP
-%etcdir%/mts.conf
+%nmhetcdir%/mts.conf
mts configuration file.
.TP
%mailspool%/$USER
To set mode when creating a new folder.
.TP
Msg\-Protect:
-To set mode when creating a new message and audit\-file.
+To set mode when creating a new message and audit-file.
.TP
Unseen\-Sequence:
To name sequences denoting unseen messages.
.IR mhmail (1),
.IR scan (1),
.IR mh\-mail (5),
+.IR mh\-profile (5),
+.IR mhlogin (1),
.IR post (8),
.IR rcvstore (1)
.SH DEFAULTS
.TP
\-nosasl
.TP
-\-truncate
-If
+\-notruncate
+Unless
.B \-file
.I name
-not given,
-\-notruncate otherwise.
+is given.
.TP
\-width
The width of the terminal.
-.TP
-\-nopack
.PD
.SH CONTEXT
The folder into which messages are being incorporated will become the
projects / nmh / blobdiff