DOCS: Added information for CURLOPT_MAIL_AUTH.

Added information relating to the new CURLOPT_MAIL_AUTH parameter and
reworked CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT to be a clearer.

Fixed inconsistencies of "vocalisation of the abbreviation" versus
"vocalisation of the first word" for all abbreviations.

Corrected a typo in CURLOPT_NOPROXY.

1 files changed, 50 insertions, 27 deletions

diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index a68b65855..895d85bcd 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -419,7 +419,7 @@ built against another SSL library, this functionality is absent.
 
 Function pointer that should match the following prototype: \fBCURLcode
 sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called
-by libcurl just before the initialization of an SSL connection after having
+by libcurl just before the initialization of a SSL connection after having
 processed all other SSL related options to give a last chance to an
 application to modify the behaviour of openssl's ssl initialization. The
 \fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If
@@ -434,7 +434,7 @@ the SSL negotiation. The SSL_CTX pointer will be a new one every time.
 To use this properly, a non-trivial amount of knowledge of the openssl
 libraries is necessary. For example, using this function allows you to use
 openssl callbacks to add additional validation code for certificates, and even
-to change the actual URI of an HTTPS request (example used in the lib509 test
+to change the actual URI of a HTTPS request (example used in the lib509 test
 case).  See also the example section for a replacement of the key, certificate
 and trust file settings.
 .IP CURLOPT_SSL_CTX_DATA
@@ -711,7 +711,7 @@ pop3://user:password@mail.domain.com/1 - This retrieves the first message
 
 .B SCP
 
-The path part of an SCP request specifies the file to retrieve and from what
+The path part of a SCP request specifies the file to retrieve and from what
 directory. The file part may not be omitted. The file is taken as an absolute
 path from the root directory on the server. To specify a path relative to
 the user's home directory on the server, prepend ~/ to the path portion.
@@ -725,7 +725,7 @@ user's home directory on the server
 
 .B SFTP
 
-The path part of an SFTP request specifies the file to retrieve and from what
+The path part of a SFTP request specifies the file to retrieve and from what
 directory. If the file part is omitted then libcurl downloads the directory
 listing for the directory specified.  If the path ends in a / then a directory
 listing is returned instead of a file.  If the path is omitted entirely then
@@ -778,7 +778,7 @@ proxy's port number may optionally be specified with the separate option. If
 not specified, libcurl will default to using port 1080 for proxies.
 \fICURLOPT_PROXYPORT\fP.
 
-When you tell the library to use an HTTP proxy, libcurl will transparently
+When you tell the library to use a HTTP proxy, libcurl will transparently
 convert operations to HTTP even if you specify an FTP URL etc. This may have
 an impact on what other features of the library you can use, such as
 \fICURLOPT_QUOTE\fP and similar FTP specifics that don't work unless you
@@ -817,7 +817,7 @@ affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version
 used for "regular" HTTP requests is instead controlled with
 \fICURLOPT_HTTP_VERSION\fP.
 .IP CURLOPT_NOPROXY
-Pass a pointer to a zero terminated string. The should be a comma separated
+Pass a pointer to a zero terminated string. This should be a comma separated
 list of hosts which do not use a proxy, if one is specified.  The only
 wildcard is a single * character, which matches all hosts, and effectively
 disables the proxy. Each name in this list is matched as either a domain which
@@ -1129,7 +1129,7 @@ Pass a parameter set to 1 to enable this. When enabled, libcurl will
 automatically set the Referer: field in requests where it follows a Location:
 redirect.
 .IP CURLOPT_ACCEPT_ENCODING
-Sets the contents of the Accept-Encoding: header sent in an HTTP request, and
+Sets the contents of the Accept-Encoding: header sent in a HTTP request, and
 enables decoding of a response when a Content-Encoding: header is received.
 Three encodings are supported: \fIidentity\fP, which does nothing,
 \fIdeflate\fP which requests the server to compress its response using the
@@ -1157,7 +1157,7 @@ by both HTTP clients and HTTP servers.
 (Added in 7.21.6)
 .IP CURLOPT_FOLLOWLOCATION
 A parameter set to 1 tells the library to follow any Location: header that the
-server sends as part of an HTTP header.
+server sends as part of a HTTP header.
 
 This means that the library will re-send the same request on the new location
 and follow new Location: headers all the way until no more such headers are
@@ -1237,7 +1237,7 @@ If you issue a POST request and then want to make a HEAD or GET using the same
 re-used handle, you must explicitly set the new request type using
 \fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar.
 .IP CURLOPT_POSTFIELDS
-Pass a void * as parameter, which should be the full data to post in an HTTP
+Pass a void * as parameter, which should be the full data to post in a HTTP
 POST operation. You must make sure that the data is formatted the way you want
 the server to receive it. libcurl will not convert or encode it for you. Most
 web servers will assume this data to be url-encoded.
@@ -1272,7 +1272,7 @@ Pass a curl_off_t as parameter. Use this to set the size of the
 data to figure out the size. This is the large file version of the
 \fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1)
 .IP CURLOPT_COPYPOSTFIELDS
-Pass a char * as parameter, which should be the full data to post in an HTTP
+Pass a char * as parameter, which should be the full data to post in a HTTP
 POST operation. It behaves as the \fICURLOPT_POSTFIELDS\fP option, but the
 original data are copied by the library, allowing the application to overwrite
 the original data after setting this option.
@@ -1444,25 +1444,48 @@ transfer decoding will be disabled, if set to 1 it is enabled
 option is set to zero. (added in 7.16.2)
 .SH SMTP OPTIONS
 .IP CURLOPT_MAIL_FROM
-Pass a pointer to a zero terminated string as parameter. It will be used to
-specify the sender address in a mail when sending an SMTP mail with libcurl.
+Pass a pointer to a zero terminated string as parameter. This should be used
+to specify the sender's email address when sending SMTP mail with libcurl.
+
+An originator email address should be specified with angled brackets (<>)
+around it, which if not specified, will be added by libcurl from version
+7.21.4 onwards. Failing to provide such brackets may cause the server to
+reject the email.
 
-An originator email address in SMTP lingo is specified within angle brackets
-(<>) which libcurl will not add for you before version 7.21.4. Failing to
-provide such brackets may cause the server to reject your mail.
+If this parameter is not specified then an empty address will be sent to the
+mail server which may or may not cause the email to be rejected.
 
 (Added in 7.20.0)
 .IP CURLOPT_MAIL_RCPT
 Pass a pointer to a linked list of recipients to pass to the server in your
-SMTP mail request.  The linked list should be a fully valid list of \fBstruct
+SMTP mail request. The linked list should be a fully valid list of \fBstruct
 curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to
 create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list.
 
-Each recipient in SMTP lingo is specified with angle brackets (<>), but should
-you not use an angle bracket as first letter libcurl will assume you provide a
-single email address only and enclose that with angle brackets for you.
+Each recipient should be specified within a pair of angled brackets (<>),
+however, should you not use an angled bracket as the first character libcurl
+will assume you provided a single email address and enclose that address
+within brackets for you.
 
 (Added in 7.20.0)
+.IP CURLOPT_MAIL_AUTH
+Pass a pointer to a zero terminated string as parameter. This will be used
+to specify the authentication address (identity) of a submitted message that
+is being relayed to another server.
+
+This optional parameter allows co-operating agents in a trusted environment to
+communicate the authentication of individual messages and should only be used
+by the application program, using libcurl, if the application is itself a
+mail server acting in such an environment. If the application is operating as
+such and the AUTH address is not known or is invalid, then an empty string
+should be used for this parameter.
+
+Unlike CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT, the address should not be
+specified within a pair of angled brackets (<>). However, if an empty string
+is used then a pair of brackets will be sent by libcurl as required by
+RFC-2554.
+
+(Added in 7.24.0)
 .SH TFTP OPTIONS
 .IP CURLOPT_TFTP_BLKSIZE
 Specify block size to use for TFTP data transmission. Valid range as per RFC
@@ -1684,7 +1707,7 @@ needed for this method)\fP  (Added in 7.20.0)
 When sent by a client, this method changes the description of the session. For
 example, if a client is using the server to record a meeting, the client can
 use Announce to inform the server of all the meta-information about the
-session.  ANNOUNCE acts like an HTTP PUT or POST just like
+session.  ANNOUNCE acts like a HTTP PUT or POST just like
 \fICURL_RTSPREQ_SET_PARAMETER\fP (Added in 7.20.0)
 .IP CURL_RTSPREQ_SETUP
 Setup is used to initialize the transport layer for the session. The
@@ -1707,7 +1730,7 @@ different connections.  (Added in 7.20.0)
 .IP CURL_RTSPREQ_GET_PARAMETER
 Retrieve a parameter from the server. By default, libcurl will automatically
 include a \fIContent-Type: text/parameters\fP header on all non-empty requests
-unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST
+unless a custom one is set. GET_PARAMETER acts just like a HTTP PUT or POST
 (see \fICURL_RTSPREQ_SET_PARAMETER\fP).
 Applications wishing to send a heartbeat message (e.g. in the presence of a
 server-specified timeout) should send use an empty GET_PARAMETER request.
@@ -1715,9 +1738,9 @@ server-specified timeout) should send use an empty GET_PARAMETER request.
 .IP CURL_RTSPREQ_SET_PARAMETER
 Set a parameter on the server. By default, libcurl will automatically include
 a \fIContent-Type: text/parameters\fP header unless a custom one is set. The
-interaction with SET_PARAMTER is much like an HTTP PUT or POST. An application
-may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like an HTTP
-PUT, or it may use \fICURLOPT_POSTFIELDS\fP like an HTTP POST. No chunked
+interaction with SET_PARAMTER is much like a HTTP PUT or POST. An application
+may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like a HTTP
+PUT, or it may use \fICURLOPT_POSTFIELDS\fP like a HTTP POST. No chunked
 transfers are allowed, so the application must set the
 \fICURLOPT_INFILESIZE\fP in the former and \fICURLOPT_POSTFIELDSIZE\fP in the
 latter. Also, there is no use of multi-part POSTs within RTSP. (Added in
@@ -1779,7 +1802,7 @@ over FTP. This is a known limitation/flaw that nobody has rectified. libcurl
 simply sets the mode to ASCII and performs a standard transfer.
 .IP CURLOPT_PROXY_TRANSFER_MODE
 Pass a long. If the value is set to 1 (one), it tells libcurl to set the
-transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by
+transfer mode (binary or ASCII) for FTP transfers done via a HTTP proxy, by
 appending ;type=a or ;type=i to the URL. Without this setting, or it being set
 to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing
 FTP via a proxy. Beware that not all proxies support this feature.  (Added in
@@ -1817,7 +1840,7 @@ Pass a curl_off_t as parameter. It contains the offset in number of bytes that
 you want the transfer to start from. (Added in 7.11.0)
 .IP CURLOPT_CUSTOMREQUEST
 Pass a pointer to a zero terminated string as parameter. It will be used
-instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST
+instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST
 when doing a FTP directory listing. This is useful for doing DELETE or other
 more or less obscure HTTP requests. Don't do this at will, make sure your
 server supports the command first.
@@ -2160,7 +2183,7 @@ Pass a long as parameter. By default, curl assumes a value of 1.
 This option determines whether curl verifies the authenticity of the peer's
 certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't.
 
-When negotiating an SSL connection, the server sends a certificate indicating
+When negotiating a SSL connection, the server sends a certificate indicating
 its identity.  Curl verifies whether the certificate is authentic, i.e. that
 you can trust that the server is who the certificate says it is.  This trust
 is based on a chain of digital signatures, rooted in certification authority