-.\"
+.TH INC %manext1% 2016-11-02 "%nmhversion%"
+.
.\" %nmhwarning%
-.\" $Id$
-.\"
-.\" include the -mh macro file
-.so %etcdir%/tmac.h
-.\"
-.TH INC %manext1% MH.6.8 [%nmhversion%]
+.
.SH NAME
-inc \- incorporate new mail
+inc \- incorporate new mail to an nmh folder
.SH SYNOPSIS
-.in +.5i
-.ti -.5i
-inc
-\%[+folder]
-\%[\-audit\ audit\-file] \%[\-noaudit]
-\%[\-changecur]
-.br
-\%[\-nochangecur]
-\%[\-form\ formatfile]
-\%[\-format\ string]
-.br
-\%[\-file\ name]
-\%[\-silent] \%[\-nosilent]
-\%[\-truncate]
-.br
-\%[\-notruncate]
-\%[\-width\ columns]
-%nmhbeginpop%
-\%[\-host\ hostname]
-.br
-\%[\-user\ username]
-\%[\-pack\ file]
-\%[\-nopack]
-\%[\-apop]
-\%[\-noapop]
-\%[\-kpop]
-\%[\-sasl]
-\%[\-saslmech\ mechanism]
-\%[\-snoop]
-.br
-%nmhendpop%
-\%[\-version]
-\%[\-help]
-.in -.5i
+.HP 5
+.na
+.B inc
+.RB [ \-help ]
+.RB [ \-version ]
+.RI [ +folder ]
+.RB [ \-audit
+.IR audit-file ]
+.RB [ \-noaudit ]
+.RB [ \-changecur " | " \-nochangecur ]
+.RB [ \-form
+.IR formfile ]
+.RB [ \-format
+.IR string ]
+.RB [ \-file
+.IR name ]
+.RB [ \-silent " | " \-nosilent ]
+.RB [ \-truncate " | " \-notruncate ]
+.RB [ \-width
+.IR columns ]
+.RB [ \-host
+.IR hostname ]
+.RB [ \-port
+.IR portname/number ]
+.RB [ \-user
+.IR username ]
+.RB [ \-proxy
+.IR command ]
+.RB [ \-sasl " | " \-nosasl ]
+.RB [ \-saslmech
+.IR mechanism ]
+.RB [ \-authservice
+.IR service ]
+.RB [ \-initialtls ]
+.RB [ \-notls ]
+.RB [ \-certverify " | " \-nocertverify ]
+.RB [ \-snoop ]
+.ad
.SH DESCRIPTION
-\fIInc\fR incorporates mail from the user's incoming mail drop into
-an \fInmh\fR folder.
-
-You may specify which folder to use with `+folder'. If no folder
-is specified, then \fIinc\fR will use either the folder given by a
-(non\-empty) \*(lqInbox:\*(rq entry in the user's profile, or the folder
-named \*(lqinbox\*(rq. If the specified (or default) folder doesn't
+.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
+.B mbox
+or
+.B MMDF
+format.
+If the mail drop is a directory it is considered to be in
+.B Maildir
+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)
+.RI \*(lq Inbox \*(rq
+entry in the user's profile, or the folder named
+.RI \*(lq inbox \*(rq.
+If the specified (or default) folder doesn't
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 \fIscan\fR listing of the new mail is produced.
-
-If the user's profile contains a \*(lqMsg\-Protect: nnn\*(rq entry, it
-will be used as the protection on the newly created messages, otherwise
-the \fInmh\fR default of 0644 will be used. For all subsequent operations
-on these messages, this initially assigned protection will be preserved.
-
-If the switch `\-audit\ audit\-file' is specified (usually as a default
-switch in the profile), then \fIinc\fR will append a header line and a
-line per message to the end of the specified audit\-file with the format:
-
+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
+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
+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 user's profile), then
+.B inc
+will append a header line and a line per message to the specified
+audit-file with the format:
+.PP
+.RS 5
.nf
-.ti 1i
-\*(<<inc\*(>> date
-.ti 1.5i
+<<inc>> date
<scan line for first message>
-.ti 1.5i
<scan line for second message>
-.ti 2.5i
<etc.>
.fi
-
+.RE
+.PP
This is useful for keeping track of volume and source of incoming mail.
-Eventually, \fIrepl\fR, \fIforw\fR, \fIcomp\fR, and \fIdist\fR
-may also produce audits to this (or another) file, perhaps with
-\*(lqMessage\-Id:\*(rq information to keep an exact correspondence
-history. \*(lqAudit\-file\*(rq will be in the user's nmh directory unless
-a full path is specified.
-
-\fIInc\fR will incorporate even improperly formatted messages into the
-user's nmh folder, inserting a blank line prior to the offending component
+Eventually,
+.BR repl ,
+.BR forw ,
+.BR comp ,
+and
+.B dist
+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
+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
and printing a comment identifying the bad message.
-
-In all cases, the user's mail drop will be zeroed, unless the
-`\-notruncate' switch is given.
-
-If the profile entry \*(lqUnseen\-Sequence\*(rq is present and non\-empty,
-then \fIinc\fR will add each of the newly incorporated messages to
-each sequence named by the profile entry. \fIInc\fR will not zero each
-sequence prior to adding messages.
-
-The interpretation of the `\-form\ formatfile', `\-format\ string', and
-`\-width\ columns' switches is the same as in \fIscan\fR\0(1).
-
-By using the `\-file\ name' switch, one can direct \fIinc\fR to
-incorporate messages from a file other than the user's maildrop.
-Note that the name file will NOT be zeroed, unless the `\-truncate'
+.PP
+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.
-
-If the environment variable \fB$MAILDROP\fR is set, then \fIinc\fR
-uses it as the location of the user's maildrop instead of the default
-(the `-file\ name' switch still overrides this, however). If this
-environment variable is not set, then \fIinc\fR will consult the profile
-entry \*(lqMailDrop\*(rq for this information. If the value found is
-not absolute, then it is interpreted relative to the user's \fInmh\fR
-directory. If the value is not found, then \fIinc\fR will look in the
-standard system location for the user's maildrop.
-
-The `\-silent' switch directs \fIinc\fR to be quiet and not ask any
-questions at all. This is useful for putting \fIinc\fR in the background
-and going on to other things.
-%nmhbeginpop%
-
-.Uh "Using POP"
-\fIinc\fR will normally check local mail drops for mail, as covered above. But
-if the option \*(lqpophost:\*(rq is set in \*(lqmts.conf\*(rq, or if the
-`\-host\ hostname' switch is given, or if the \fB$MAILHOST\fR environment
-variable is set, then \fIinc\fR will query this POP service host for mail to
-incorporate. If \fB$MAILHOST\fR is set and \-host is specified as well, the
-commandline switch will override the environment variable.
-
-The default is for \fIinc\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.
-
-If \fIinc\fR uses POP, then the `\-pack\ file' switch is considered.
-If given, then \fIinc\fR simply uses the POP to \fIpackf\fR\0(1) the
-user's maildrop from the POP service host to the named file. This switch
-is provided for those users who prefer to use \fImsh\fR to read their
-maildrops.
-
-For debugging purposes, you may give the switch `\-snoop', which will
-allow you to watch the POP transaction take place between you and the
-POP server.
-
-If nmh has been compiled with APOP #defined, the `\-apop' switch will cause
-\fIinc\fR to use APOP rather than standard POP3 authentication. Under APOP, a
-unique string (generally of the format
-<\fIpid\fR.\fItimestamp\fR@\fIhostname\fR>) is announced by the POP server.
-Rather than `USER \fIuser\fR', `PASS \fIpassword\fR', inc sends `APOP \fIuser\fR
-\fIdigest\fR', where digest is the MD5 hash of the unique string followed by a
-`secret' shared by client and server, essentially equivalent to the user's
-password (though an APOP-enabled POP3 server can have separate APOP and plain
-POP3 passwords for a single user). `\-noapop' disables APOP in cases where it'd
-otherwise be used.
-
-If nmh has been compiled with KPOP #defined, the `\-kpop' switch will allow
-\fIinc\fR to use Kerberized POP rather than standard POP3 on a given invocation.
-If POPSERVICE was also #defined to "kpop", \fIinc\fR will be hardwired to always
-use KPOP.
-
-If nmh has been compiled with SASL support, the `\-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
-\*(lq.netrc\*(rq file can be used to store this password). The
-`\-saslmech' switch can be used to select a particular SASL mechanism.
-
-If SASL authentication is successful, \fIinc\fR 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 `\-snoop' switch.
-%nmhendpop%
-.Fi
-^$HOME/\&.mh\(ruprofile~^The user profile
-^%etcdir%/mts.conf~^nmh mts configuration file
-^%mailspool%/$USER~^Location of mail drop
-.Pr
-^Path:~^To determine the user's nmh directory
-.Ps
-^Alternate\-Mailboxes:~^To determine the user's mailboxes
-.Ps
-^Inbox:~^To determine the inbox, default \*(lqinbox\*(rq
-.Ps
-^Folder\-Protect:~^To set mode when creating a new folder
-.Ps
-^Msg\-Protect:~^To set mode when creating a new message and audit\-file
-.Ps
-^Unseen\-Sequence:~^To name sequences denoting unseen messages
-.Sa
-mhmail(1), scan(1), mh\-mail(5), post(8)
-.De
-`+folder' defaulted by \*(lqInbox\*(rq above
-.Ds
-`\-noaudit'
-.Ds
-`\-changecur'
-.Ds
-`\-format' defaulted as described above
-.Ds
-`\-nosilent'
-.Ds
-`\-truncate' if `\-file\ name' not given, `\-notruncate' otherwise
-.Ds
-`\-width' defaulted to the width of the terminal
-%nmhbeginpop%
-.Ds
-`\-nopack'
-%nmhendpop%
-.Co
+.PP
+If the profile entry
+.RI \*(lq Unseen\-Sequence \*(rq
+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 not zero each sequence prior to adding messages.
+.PP
+The interpretation of the
+.B \-form
+.IR formatfile ,
+.B \-format
+.IR string ,
+and
+.B \-width
+.I columns
+switches is the same as in
+.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 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 the use of standard input.
+Instead, the
+.B rcvstore
+command can be used to incorporate mail from the standard input stream.
+.PP
+If the environment variable
+.B $MAILDROP
+is set, then
+.B inc
+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
+.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
+.B nmh
+directory. If the value is not found, then
+.B inc
+will look in the standard system location for the user's mail drop.
+.PP
+The
+.B \-silent
+switch directs
+.B inc
+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.
+.SS "Using POP"
+.B inc
+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,
+or if the
+.B \-host
+.I hostname
+switch is given, or if the
+.B $MAILHOST
+environment variable is set, then
+.B inc
+will query this POP service host for mail to incorporate. If
+.B $MAILHOST
+is set and
+.B \-host
+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.
+.PP
+To specify a username for authentication with the POP server, use the
+.B \-user
+.I username
+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
+.I command
+switch,
+.B inc
+will use the specified command to establish the connection to the POP
+server. The string
+.I %h
+in the command will be substituted by the hostname to connect to.
+.PP
+For debugging purposes, you may give the switch
+.BR \-snoop ,
+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
+.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
+If SASL authentication is successful,
+.B inc
+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
+.IR post (8)'s
+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
+The user's profile.
+.TP
+%nmhetcdir%/mts.conf
+mts configuration file.
+.TP
+%mailspool%/$USER
+Location of the system mail drop.
+.PD
+.SH "PROFILE COMPONENTS"
+.PD 0
+.TP 20
+Path:
+To determine the user's nmh directory.
+.TP
+Alternate\-Mailboxes:
+To determine the user's mailboxes.
+.TP
+Inbox:
+To determine the inbox.
+.TP
+Folder\-Protect:
+To set mode when creating a new folder.
+.TP
+Msg\-Protect:
+To set mode when creating a new message and audit-file.
+.TP
+Unseen\-Sequence:
+To name sequences denoting unseen messages.
+.PD
+.SH "SEE ALSO"
+.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
+.PD 0
+.TP 20
++folder
+defaulted by \*(lqInbox\*(rq above.
+.TP
+\-noaudit
+.TP
+\-changecur
+.TP
+\-format
+As described above.
+.TP
+\-nosilent
+.TP
+\-nosasl
+.TP
+\-notruncate
+Unless
+.B \-file
+.I name
+is given.
+.TP
+\-width
+The width of the terminal.
+.PD
+.SH CONTEXT
The folder into which messages are being incorporated will become the
current folder. The first message incorporated will become the current
-message, unless the `\-nochangecur' option is specified. This leaves
-the context ready for a \fIshow\fR of the first new message.
-.Bu
-The argument to the `\-format' switch must be interpreted as a single
-token by the shell that invokes \fIinc\fR. Therefore, one must usually
-place the argument to this switch inside double\-quotes.
-.En
+message, unless the
+.B \-nochangecur
+option is specified. This leaves the context ready for a
+.B show
+of the first new message.
projects / nmh / blobdiff