HTTPS-PROXY docs: update/polish

1 files changed, 23 insertions, 29 deletions

diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3
index e72027a8b..de4b15b34 100644
--- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3
+++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3
@@ -28,44 +28,35 @@ CURLOPT_PROXY_SSL_VERIFYHOST \- verify the proxy certificate's name against host
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYHOST, long verify);
 .SH DESCRIPTION
-TODO: Make this text specific to HTTPS proxy. (Added in 7.XXX)
-Pass a long as parameter specifying what to \fIverify\fP.
+Pass a long set to 2L as asking curl to \fIverify\fP in the HTTPS proxy's
+certificate name fields against the proxy name.
 
-This option determines whether libcurl verifies that the server cert is for
-the server it is known as.
+This option determines whether libcurl verifies that the proxy cert contains
+the correct name for the name it is known as.
 
-When negotiating TLS and SSL connections, the server sends a certificate
-indicating its identity.
+When \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP is 2, the proxy certificate must
+indicate that the server is the proxy to which you meant to connect to, or the
+connection fails.
 
-When \fICURLOPT_SSL_VERIFYHOST(3)\fP is 2, that certificate must indicate that
-the server is the server to which you meant to connect, or the connection
-fails. Simply put, it means it has to have the same name in the certificate as
-is in the URL you operate against.
-
-Curl considers the server the intended one when the Common Name field or a
+Curl considers the proxy the intended one when the Common Name field or a
 Subject Alternate Name field in the certificate matches the host name in the
-URL to which you told Curl to connect.
-
-When the \fIverify\fP value is 1, \fIcurl_easy_setopt\fP will return an error
-and the option value will not be changed.  It was previously (in 7.28.0 and
-earlier) a debug option of some sorts, but it is no longer supported due to
-frequently leading to programmer mistakes. Future versions will stop returning
-an error for 1 and just treat 1 and 2 the same.
+proxy string which you told curl to use.
 
-When the \fIverify\fP value is 0, the connection succeeds regardless of the
-names in the certificate. Use that ability with caution!
+When the \fIverify\fP value is 1L, \fIcurl_easy_setopt\fP will return an error
+and the option value will not be changed due to old legacy reasons.
 
-The default value for this option is 2.
+When the \fIverify\fP value is 0L, the connection succeeds regardless of the
+names used in the certificate. Use that ability with caution!
 
-This option controls checking the server's certificate's claimed identity.
-The server could be lying.  To control lying, see
-\fICURLOPT_SSL_VERIFYPEER(3)\fP.  If libcurl is built against NSS and
-\fICURLOPT_SSL_VERIFYPEER(3)\fP is zero, \fICURLOPT_SSL_VERIFYHOST(3)\fP is
-also set to zero and cannot be overridden.
+See also \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP to verify the digital signature
+of the proxy certificate.  If libcurl is built against NSS and
+\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero,
+\fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP is also set to zero and cannot be
+overridden.
 .SH DEFAULT
 2
 .SH PROTOCOLS
-All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
+All protocols when used over a HTTPS proxy.
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -79,10 +70,13 @@ if(curl) {
 }
 .fi
 .SH AVAILABILITY
+Added in 7.52.0.
+
 If built TLS enabled.
 .SH RETURN VALUE
 Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not.
 
 If 1 is set as argument, \fICURLE_BAD_FUNCTION_ARGUMENT\fP is returned.
 .SH "SEE ALSO"
-.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_CAINFO "(3), "
+.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_CAINFO "(3), ",
+.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_CAINFO "(3), ",