Added all of mhshow's documented switches to show's handling, on the

[nmh] / man / send.man

diff --git a/man/send.man b/man/send.man
index 43d1ad1278f3a50dd6ea04d072f50be22781017b..1673c5ced138e86b9cd75db76a78789de4b6c385 100644 (file)
--- a/man/send.man
+++ b/man/send.man
@@ -1,186 +1,524 @@
 .\"
 .\" %nmhwarning%
 .\"
 .\" %nmhwarning%

-.\" $Id$

 .\"
 .\"

-.\" include the -mh macro file
-.so %etcdir%/tmac.h
-.\"
-.TH SEND %manext1% MH.6.8 [%nmhversion%]
+.TH SEND %manext1% "July 8, 2014" "%nmhversion%"

 .SH NAME
 send \- send a message
 .SH SYNOPSIS
 .SH NAME
 send \- send a message
 .SH SYNOPSIS

-.in +.5i
-.ti -.5i
-send
-\%[\-alias\ aliasfile]
-\%[\-draft]
-\%[\-draftfolder\ +folder]
-.br
-\%[\-draftmessage\ msg] \%[\-nodraftfolder]
-.br
-\%[\-filter\ filterfile] \%[\-nofilter]
-\%[\-format] \%[\-noformat]
-.br
-\%[\-forward] \%[\-noforward]
-\%[\-mime] \%[\-nomime]
-\%[\-msgid]
-.br
-\%[\-nomsgid]
-\%[\-push] \%[\-nopush]
-\%[\-split\ seconds]
-.br
-\%[\-verbose] \%[\-noverbose]
-\%[\-watch] \%[\-nowatch]
-.br
-\%[\-width\ columns]
-\%[file\ ...] 
-\%[\-version]
-\%[\-help]
-.in -.5i
+.HP 5
+.na
+.B send
+.RB [ \-alias
+.IR aliasfile ]
+.RB [ \-draft ]
+.RB [ \-draftfolder
+.IR +folder ]
+.RB [ \-draftmessage
+.IR msg ]
+.RB [ \-nodraftfolder ]
+.RB [ \-filter
+.IR filterfile ]
+.RB [ \-nofilter ]
+.RB [ \-format " | " \-noformat ]
+.RB [ \-forward " | " \-noforward ]
+.RB [ \-mime " | " \-nomime ]
+.RB [ \-msgid " | " \-nomsgid ]
+.RB [ \-messageid
+.IR localname " | " random ]
+.RB [ \-push " | " \-nopush ]
+.RB [ \-split
+.IR seconds ]
+.RB [ \-verbose " | " \-noverbose ]
+.RB [ \-watch " | " \-nowatch ]
+.RB [ \-mts
+.IR smtp " | " sendmail/smtp " | " sendmail/pipe ]
+.RB [ \-sendmail
+.IR program ]
+.RB [ \-server
+.IR servername ]
+.RB [ \-port
+.IR port-name/number ]
+.RB [ \-sasl ]
+.RB [ \-nosasl ]
+.RB [ \-saslmaxssf
+.IR ssf ]
+.RB [ \-saslmech
+.IR mechanism ]
+.RB [ \-snoop ]
+.RB [ \-user
+.IR username ]
+.RB [ \-tls ]
+.RB [ \-initialtls ]
+.RB [ \-notls ]
+.RB [ \-width
+.IR columns ]
+.RB [ file
+\&...]
+.RB [ \-version ]
+.RB [ \-help ]
+.ad

 .SH DESCRIPTION
 .SH DESCRIPTION

-\fISend\fR will cause each of the specified files to be delivered
+.B Send
+will cause each of the specified files to be delivered

 to each of the destinations in the \*(lqTo:\*(rq, \*(lqcc:\*(rq,
 to each of the destinations in the \*(lqTo:\*(rq, \*(lqcc:\*(rq,

-\*(lqBcc:\*(rq, and \*(lqFcc:\*(rq fields of the message.  If \fIsend\fR
-is re\-distributing a message, as invoked from \fIdist\fR, then the
+\*(lqBcc:\*(rq, \*(lqDcc:\*(rq, and \*(lqFcc:\*(rq fields of the message.  If
+.B send
+is re\-distributing a message, as invoked from
+.BR dist ,
+then the

 corresponding \*(lqResent\-xxx\*(rq fields are examined instead.
 corresponding \*(lqResent\-xxx\*(rq fields are examined instead.

-
-By default, \fIsend\fR uses the program \fIpost\fR(8) to do the actual
+.PP
+By default,
+.B send
+uses the program
+.B post
+to do the actual

 delivery of the messages, although this can be changed by defining the
 delivery of the messages, although this can be changed by defining the

-\fIpostproc\fR profile component.  Most of the features attributed to
-\fIsend\fR are actually performed by \fIpost\fR.
-
-If `\-push' is specified, \fIsend\fR will detach itself from the user's
-terminal and perform its actions in the background.  If \fIpush\fR\0'd
+.I postproc
+profile component.  Most of the features attributed to
+.B send
+are actually performed by
+.BR post .
+.PP
+Before
+.B send
+gives the message to
+.B post
+for delivery, the message is processed by
+.B mhbuild
+to perform any necessary MIME encoding of the outgoing message.  This
+can be changed by the
+.I buildmimeproc
+profile component.
+.B mhbuild
+is invoked with the
+.B \-auto
+switch, so
+.B mhbuild
+directives are not processed by default.  See
+.IR mhbuild (1)
+for more information.
+.PP
+.B mhbuild
+will scan the message draft for a header named
+.IR Attach .
+The draft is converted to a MIME message if one or more matches are found.
+This conversion occurs before all other processing.  The
+.IR whatnow (1)
+man page describes the user interface for managing MIME attachments via
+this mechanism.
+.PP
+The first part of the MIME message is the draft body if that body contains
+any non-blank characters.
+The body of each
+.I Attach
+header field is interpreted as a file name, and each file named is included as a separate
+part in the MIME message.
+.PP
+Determination of the content MIME type inserted into the Content-Type
+header for each part depends on how the
+.B nmh
+installation was configured.  If a program, such as
+.B file
+with a
+.B \-\-mime
+or
+.B \-i
+option, was found that can specify the type of a file as a MIME type
+string, then that will be used.  To determine if your
+.B nmh
+was so configured, run
+.B mhparam mimetypeproc
+and see if a non-empty string is displayed.
+.PP
+If your
+.B nmh
+was not configured with a program to specify a file type as a MIME
+string, then a different method is used to determine the content-type
+string.  For file names with dot suffixes, the profile is scanned for a
+.I mhshow-suffix-
+entry for that suffix.
+The content-type for the part is taken from that profile entry if a match is
+found.  If a match is not found in the user profile, the mhn.defaults
+profile is scanned next.
+If no match is found or the file does not have a dot suffix, the content-type
+is text/plain if the file contains only ASCII characters or application/octet-stream
+if it contains characters outside of the ASCII range.  See
+.IR mhshow (1)
+for more details and example syntax.
+.PP
+Each attached MIME part contains a 
+\*(lqContent-Description\*(rq header that includes the filename, and
+adds a \*(lqContent-Disposition\*(rq header.
+Here is an example of MIME part headers for an attachment:
+.PP
+.nf
+Content-Type: text/plain; name="VERSION"; charset="us-ascii"
+Content-Description: VERSION
+Content-Disposition: attachment; filename="VERSION"
+.fi
+.PP
+See
+.IR mhbuild (1)
+for explanation of how the Content-Disposition value is selected.
+.PP
+If
+.B \-push
+is specified,
+.B send
+will detach itself from the user's
+terminal and perform its actions in the background.  If
+.BR push 'd

 and the draft can't be sent, then an error message will be sent (using
 and the draft can't be sent, then an error message will be sent (using

-the mailproc) back to the user.  If `\-forward' is given, then a copy
-of the draft will be attached to this failure notice.  Using `\-push'
-differs from putting \fIsend\fR in the background because the output is
-trapped and analyzed by \fInmh\fR.
-
-If `\-verbose' is specified, \fIsend\fR will indicate the interactions
+the mailproc) back to the user.  If
+.B \-forward
+is given, then a copy
+of the draft will be attached to this failure notice.  Using
+.B \-push
+differs from putting
+.B send
+in the background because the output is
+trapped and analyzed by
+.BR nmh .
+.PP
+If
+.B \-verbose
+is specified,
+.B send
+will indicate the interactions

 occurring with the transport system, prior to actual delivery.
 occurring with the transport system, prior to actual delivery.

-If `\-watch' is specified \fIsend\fR will monitor the delivery of local
+If
+.B \-watch
+is specified
+.B send
+will monitor the delivery of local

 and network mail.  Hence, by specifying both switches, a large detail
 of information can be gathered about each step of the message's entry
 into the transport system.
 and network mail.  Hence, by specifying both switches, a large detail
 of information can be gathered about each step of the message's entry
 into the transport system.

-
-The `\-draftfolder\ +folder' and `\-draftmessage\ msg' switches invoke
-the \fInmh\fR draft folder facility.  This is an advanced (and highly
-useful) feature.  Consult the \fImh-draft\fR(5) man page for more
+.PP
+The
+.B \-draftfolder
+.I +folder
+and
+.B \-draftmessage
+.I msg
+switches invoke
+the
+.B nmh
+draft folder facility.  This is an advanced (and highly
+useful) feature.  Consult the
+.IR mh-draft (5)
+man page for more

 information.
 information.

-
-If `\-split' is specified, \fIsend\fR will split the draft into one
+.PP
+If
+.B \-split
+is specified,
+.B send
+will split the draft into one

 or more partial messages prior to sending.  This makes use of the
 or more partial messages prior to sending.  This makes use of the

-MIME features in nmh.  Note however that if \fIsend\fR is
-invoked under \fIdist\fR\0(1), then this switch is ignored\0--\0it makes
+MIME features in
+.BR nmh .
+Note however that if
+.B send
+is
+invoked under
+.BR dist ,
+then this switch is ignored\0--\0it makes

 no sense to redistribute a message in this fashion.  Sometimes you want
 no sense to redistribute a message in this fashion.  Sometimes you want

-\fIsend\fR to pause after posting a partial message.  This is usually
-the case when you are running \fIsendmail\fR and expect to generate a
-lot of partial messages.  The argument to `\-split' tells it how long
+.B send
+to pause after posting a partial message.  This is usually
+the case when you are running
+.B sendmail
+and expect to generate a
+lot of partial messages.  The argument to
+.B \-split
+tells it how long

 to pause between postings.
 to pause between postings.

-
-\fISend\fR with no \fIfile\fR argument will query whether the draft
-is the intended file, whereas `\-draft' will suppress this question.
+.PP
+.B Send
+with no
+.I file
+argument will query whether the draft
+is the intended file, whereas
+.B \-draft
+will suppress this question.

 Once the transport system has successfully accepted custody of the
 Once the transport system has successfully accepted custody of the

-message, the file will be renamed with a leading comma, which allows
+message, the file will be renamed with a site-dependent prefix
+(usually a comma), which allows

 it to be retrieved until the next draft message is sent.  If there are
 it to be retrieved until the next draft message is sent.  If there are

-errors in the formatting of the message, \fIsend\fR will abort with a
+errors in the formatting of the message,
+.B send
+will abort with a

 (hopefully) helpful error message.
 (hopefully) helpful error message.

-
+.PP

 If a \*(lqBcc:\*(rq field is encountered, its addresses will be used for
 delivery, and the \*(lqBcc:\*(rq field will be removed from the message
 sent to sighted recipients.  The blind recipients will receive an entirely
 new message with a minimal set of headers.  Included in the body of the
 message will be a copy of the message sent to the sighted recipients.
 If a \*(lqBcc:\*(rq field is encountered, its addresses will be used for
 delivery, and the \*(lqBcc:\*(rq field will be removed from the message
 sent to sighted recipients.  The blind recipients will receive an entirely
 new message with a minimal set of headers.  Included in the body of the
 message will be a copy of the message sent to the sighted recipients.

-If `\-filter\ filterfile' is specified, then this copy is filtered
-(re\-formatted) by \fImhl\fR prior to being sent to the blind recipients.
-Alternately, if you specify the `-mime' switch, then \fIsend\fR will
+.PP
+If a \*(lqDcc:\*(rq field is encountered and the
+.B sendmail/pipe
+mail transport method is not in use, its addresses will be used for
+delivery, and the \*(lqDcc:\*(rq field will be removed from the message.  The
+blind recipients will receive the same message sent to the sighted
+recipients. *WARNING* Recipients listed in the \*(lqDcc:\*(rq field receive no
+explicit indication that they have received a \*(lqblind copy\*(rq.
+This can cause blind recipients to
+inadvertently reply to all of the sighted recipients of the
+original message, revealing that they received a blind copy.
+On the other hand, since a normal reply to a message sent
+via a \*(lqBcc:\*(rq field
+will generate a reply only to the sender of the original message,
+it takes extra effort in most mailers to reply to the included
+message, and so would usually only be done deliberately, rather
+than by accident.
+.PP
+If
+.B \-filter
+.I filterfile
+is specified, then this copy is filtered
+(re\-formatted) by
+.B mhl
+prior to being sent to the blind recipients.
+Alternately, if you specify the
+.B -mime
+switch, then
+.B send
+will

 use the MIME rules for encapsulation.
 use the MIME rules for encapsulation.

-
-Prior to sending the message, the fields \*(lqFrom:\ user@local\*(rq,
-and \*(lqDate:\ now\*(rq will be appended to the headers in the message.
-If the environment variable \fB$SIGNATURE\fR is set, then its value
-is used as your personal name when constructing the \*(lqFrom:\*(rq
-line of the message.  If this environment variable is not set, then
-\fIsend\fR will consult the profile entry \*(lqSignature\*(rq for
-this information.  On hosts where \fInmh\fR was configured with the UCI
-option, if \fB$SIGNATURE\fR is not set and the \*(lqSignature\*(rq profile
-entry is not present, then the file \fB$HOME\fR/.signature is consulted.
-If `\-msgid' is specified, then a \*(lqMessage\-ID:\*(rq field will also
+.PP
+Prior to sending the message, the \*(lqDate:\ now\*(rq field will be appended to the headers in the message.
+If
+.B \-msgid
+is specified, then a \*(lqMessage\-ID:\*(rq field will also

 be added to the message.
 be added to the message.

-
-If \fIsend\fR is re\-distributing a message (when invoked by
-\fIdist\fR\0), then \*(lqResent\-\*(rq will be prepended to each of these
+.PP
+The
+.B \-messageid
+switch selects the style used for the part appearing after the @
+in \*(lqMessage\-ID:\*(rq, \*(lqResent\-Message\-ID:\*(rq, and
+\*(lqContent\-ID:\*(rq header fields.  The two acceptable options are
+.B localname
+(which is the default),
+and
+.BR random .
+With
+.BR localname ,
+the local hostname is used.  With
+.BR random ,
+a random sequence of characters is used instead.  Note that the
+.B \-msgid
+switch must be enabled for this switch to have any effect.
+.PP
+If
+.B send
+is re\-distributing a message (when invoked by
+.BR dist ),
+then \*(lqResent\-\*(rq will be prepended to each of these

 fields: \*(lqFrom:\*(rq, \*(lqDate:\*(rq, and \*(lqMessage\-ID:\*(rq.
 fields: \*(lqFrom:\*(rq, \*(lqDate:\*(rq, and \*(lqMessage\-ID:\*(rq.

-If the message already contains a \*(lqFrom:\*(rq field, then a
-\*(lqSender: user@local\*(rq field will be added as well.  (An already
-existing \*(lqSender:\*(rq field is an error!)
-
-By using the `\-format' switch, each of the entries in the \*(lqTo:\*(rq
+.PP
+A \*(lqFrom:\*(rq field is required for all outgoing messages.  Multiple
+addresses are permitted in the \*(lqFrom:\*(rq field, but a \*(lqSender:\*(rq
+field is required in this case.  Otherwise a \*(lqSender:\*(rq field
+is optional.
+.PP
+If a message with multiple \*(lqFrom:\*(rq
+addresses does
+.B NOT
+include a \*(lqSender:\*(rq field but does include an \*(lqEnvelope\-From:\*(rq
+field, the \*(lqEnvelope\-From:\*(rq field will be used to construct
+a \*(lqSender:\*(rq field.
+.PP
+When using SMTP for mail submission, the envelope\-from used for the SMTP
+transaction is derived from the \*(lqEnvelope\-From:\*(rq field.
+If no \*(lqEnvelope\-From:\*(rq field is present, the \*(lqSender:\*(rq
+field is used.  If neither the \*(lqEnvelope\-From:\*(rq nor the
+\*(lqSender:\*(rq field is present, the \*(lqFrom:\*(rq field is used.
+When \*(lqEnvelope\-From:\*(rq appears in a message
+it will be removed from the final outgoing message.
+.PP
+By using the
+.B \-format
+switch, each of the entries in the \*(lqTo:\*(rq

 and \*(lqcc:\*(rq fields will be replaced with \*(lqstandard\*(rq
 format entries.  This standard format is designed to be usable by all
 of the message handlers on the various systems around the Internet.
 and \*(lqcc:\*(rq fields will be replaced with \*(lqstandard\*(rq
 format entries.  This standard format is designed to be usable by all
 of the message handlers on the various systems around the Internet.

-If `\-noformat' is given, then headers are output exactly as they appear
+If
+.B \-noformat
+is given, then headers are output exactly as they appear

 in the message draft.
 in the message draft.

-
+.PP

 If an \*(lqFcc:\ folder\*(rq is encountered, the message will be copied
 to the specified folder for the sender in the format in which it will
 appear to any non\-Bcc receivers of the message.  That is, it will have
 the appended fields and field reformatting.  The \*(lqFcc:\*(rq fields
 will be removed from all outgoing copies of the message.
 If an \*(lqFcc:\ folder\*(rq is encountered, the message will be copied
 to the specified folder for the sender in the format in which it will
 appear to any non\-Bcc receivers of the message.  That is, it will have
 the appended fields and field reformatting.  The \*(lqFcc:\*(rq fields
 will be removed from all outgoing copies of the message.

-
-By using the `\-width\ columns' switch, the user can direct \fIsend\fR
+.PP
+By using the
+.B \-width
+.I columns
+switch, the user can direct
+.B send

 as to how long it should make header lines containing addresses.
 as to how long it should make header lines containing addresses.

-
+.PP
+The mail transport system default is provided in
+.I %nmhetcdir%/mts.conf
+but can be overriiden here with the
+.B \-mts
+switch.
+.PP
+If nmh is using as its mail transport system
+.BR sendmail/pipe ,
+the
+.B \-sendmail
+switch can be used to override the default
+.B sendmail
+program.
+.PP
+If nmh is using the SMTP MTA, the
+.B \-server
+and the
+.B \-port
+switches can be used to override the default mail server (defined by the
+.I %nmhetcdir%/mts.conf
+.RI servers
+entry).  The
+.B \-snoop
+switch can be used to view the SMTP transaction.  (Beware that the
+SMTP transaction may contain authentication information either in
+plaintext or easily decoded base64.)
+.PP
+If
+.B nmh
+has been compiled with SASL support, the
+.B \-sasl
+and
+.B \-nosasl
+switches will enable and disable
+the use of SASL authentication with the SMTP MTA.  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,
+and the
+.B \-user
+switch can be used to select a authorization userid to provide to SASL
+other than the default.  The credentials profile entry in the
+mh\-profile(5) man page describes the ways to supply a username and
+password.
+.PP
+If SASL authentication is successful,
+.BR nmh
+will attempt to negotiate a security layer for session encryption.
+Encrypted data is labelled with `(encrypted)' and `(decrypted)' when
+viewing the SMTP transaction with the
+.B \-snoop
+switch.  The
+.B \-saslmaxssf
+switch can be used to select the maximum value of the Security Strength Factor.
+This is an integer value and the exact meaning of this value depends on the
+underlying SASL mechanism.  A value of 0 disables encryption.
+.PP
+If
+.B nmh
+has been compiled with TLS support, the
+.B \-tls
+and
+.B \-initialtls
+switches will require the negotiation of TLS when
+connecting to the SMTP MTA.  The
+.B \-tls
+switch will negotiate TLS as part of the normal SMTP protocol
+using the STARTTLS command.  The
+.B \-initialtls
+will negotiate TLS immediately after the connection has
+taken place, before any SMTP commands are sent or received.  Encrypted data
+is labelled with `(tls-encrypted)' and
+`(tls-decrypted)' when viewing the SMTP transction with the
+.B \-snoop
+switch.
+The
+.B \-notls
+switch will disable all attempts to negotiate TLS.
+.PP
+If port 465 is specified and none of the TLS switches were enabled,
+.B \-initialtls
+will be implied if TLS support was compiled in.  Though port 465 for
+SMTPS (SMTP over SSL) was deregistered by IANA in 1998, it is still
+used for that service.
+.PP

 The files specified by the profile entry \*(lqAliasfile:\*(rq and any
 The files specified by the profile entry \*(lqAliasfile:\*(rq and any

-additional alias files given by the `\-alias aliasfile' switch will be
-read (more than one file, each preceded by `\-alias', can be named).
-See \fImh\-alias\fR\0(5) for more information.
-.Fi
+additional alias files given by the
+.B \-alias
+.I aliasfile
+switch will be
+read (more than one file, each preceded by
+.BR \-alias ,
+can be named).
+See
+.IR mh\-alias (5)
+for more information.
+.SH FILES
+.fc ^ ~
+.nf
+.ta \w'%nmhetcdir%/ExtraBigFileName  'u

 ^$HOME/\&.mh\(ruprofile~^The user profile
 ^$HOME/\&.mh\(ruprofile~^The user profile

-.Pr
+.fi
+.SH "PROFILE COMPONENTS"
+.fc ^ ~
+.nf
+.ta 2.4i
+.ta \w'ExtraBigProfileName  'u

 ^Path:~^To determine the user's nmh directory
 ^Path:~^To determine the user's nmh directory

-.Ps

 ^Draft\-Folder:~^To find the default draft\-folder
 ^Draft\-Folder:~^To find the default draft\-folder

-.Ps

 ^Aliasfile:~^For a default alias file
 ^Aliasfile:~^For a default alias file

-.Ps

 ^Signature:~^To determine the user's mail signature
 ^Signature:~^To determine the user's mail signature

-.Ps

 ^mailproc:~^Program to post failure notices
 ^mailproc:~^Program to post failure notices

-.Ps

 ^postproc:~^Program to post the message
 ^postproc:~^Program to post the message

-.Sa
-comp(1), dist(1), forw(1), repl(1), mh\-alias(5), post(8)
-.De
-`file' defaults to <mh\-dir>/draft
-.Ds
-`\-alias %etcdir%/MailAliases'
-.Ds
-`\-nodraftfolder'
-.Ds
-`\-nofilter'
-.Ds
-`\-format'
-.Ds
-`\-forward'
-.Ds
-`\-nomime'
-.Ds
-`\-nomsgid'
-.Ds
-`\-nopush'
-.Ds
-`\-noverbose'
-.Ds
-`\-nowatch'
-.Ds
-`\-width\ 72'
-.Co
+.fi
+.SH "SEE ALSO"
+.IR comp (1),
+.IR dist (1),
+.IR file (1),
+.IR forw (1),
+.IR mhbuild (1),
+.IR mhparam (1),
+.IR repl (1),
+.IR whatnow (1),
+.IR mh\-alias (5),
+.IR mh\-profile (5),
+.IR mh\-tailor (5),
+.IR post (8)
+.SH DEFAULTS
+.nf
+.RB ` file "' defaults to <mh\-dir>/draft"
+.RB ` \-alias "' defaults to %nmhetcdir%/MailAliases"
+.RB ` \-nodraftfolder '
+.RB ` \-nofilter '
+.RB ` \-format '
+.RB ` \-forward '
+.RB ` \-nomime '
+.RB ` \-nomsgid '
+.RB ` "\-messageid\ localname" '
+.RB ` \-nopush '
+.RB ` \-noverbose '
+.RB ` \-nowatch '
+.RB ` "\-width\ 72" '
+.fi
+.SH CONTEXT

 None
 None

-.Bu
+.SH BUGS

 Under some configurations, it is not possible to monitor the mail delivery
 Under some configurations, it is not possible to monitor the mail delivery

-transaction; `\-watch' is a no-op on those systems.
-.sp
-Using `\-split\00' doesn't work correctly.
-.En
+transaction;
+.B \-watch
+is a no-op on those systems.
+.PP
+Using
+.B \-split
+.I 0
+doesn't work correctly.