X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/36e3d7dc4bc9905a9b9074defd26ee6c32e1a6b9..ec173fd2c:/man/inc.man?ds=sidebyside

diff --git a/man/inc.man b/man/inc.man
index 9020ff1b..56764a31 100644
--- a/man/inc.man
+++ b/man/inc.man
@@ -1,16 +1,18 @@
-.TH INC %manext1% "October 9, 2016" "%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
@@ -29,9 +31,6 @@ inc \- incorporate new mail
 .IR portname/number ]
 .RB [ \-user
 .IR username ]
-.RB [ \-pack
-.IR file ]
-.RB [ \-nopack ]
 .RB [ \-proxy
 .IR command ]
 .RB [ \-sasl " | " \-nosasl ]
@@ -41,14 +40,12 @@ inc \- incorporate new mail
 .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
@@ -56,15 +53,15 @@ 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.
@@ -72,28 +69,26 @@ 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
+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
@@ -111,29 +106,31 @@ Eventually,
 .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
@@ -145,22 +142,24 @@ and
 .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
@@ -168,21 +167,21 @@ If the environment variable
 .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
@@ -191,11 +190,10 @@ switch directs
 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,
@@ -210,16 +208,17 @@ will query this POP service host for mail to incorporate.  If
 .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
 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
+switch.  The credentials profile entry in
+.IR mh\-profile (5)
 describes the ways to supply a username and password.
 .PP
 If passed the
@@ -229,24 +228,12 @@ switch,
 .B inc
 will use the specified command to establish the connection to the POP
 server.  The string
-.IR %h
+.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.
-.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.  If
+which will allow you to monitor the POP transaction.  If
 .B \-sasl \-saslmech xoauth2
 is used, the HTTP transaction is also shown.
 .PP
@@ -254,12 +241,13 @@ 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
+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
+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
@@ -269,9 +257,9 @@ 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
+switch; see
+.IR post (8)'s
+description of
 .B \-snoop
 for its other features.
 .PP
@@ -291,25 +279,34 @@ be specified with the
 .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.
+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.  The
-.B \-initialtls
-switch will negotiate TLS immediately after the connection has taken place,
+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)` with viewing the POP
+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
@@ -338,7 +335,7 @@ Folder\-Protect:
 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.
@@ -368,17 +365,14 @@ As described above.
 .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