docs: Add more HTTPS proxy documentation

- Document HTTPS proxy type.

- Document --write-out %{proxy_ssl_verify_result}.

- Document SOCKS proxy + HTTP/HTTPS proxy combination.

HTTPS proxy support was added in 7.52.0 for OpenSSL, GnuTLS and NSS.

Ref: https://github.com/curl/curl/commit/cb4e2be

6 files changed, 34 insertions, 17 deletions

diff --git a/docs/cmdline-opts/proxy.d b/docs/cmdline-opts/proxy.d
index 377a51aab..6506692be 100644
--- a/docs/cmdline-opts/proxy.d
+++ b/docs/cmdline-opts/proxy.d
@@ -5,11 +5,16 @@ Help: Use this proxy
 ---
 Use the specified proxy.
 
-The proxy string can be specified with a protocol:// prefix to specify
-alternative proxy protocols. Use socks4://, socks4a://, socks5:// or
-socks5h:// to request the specific SOCKS version to be used. No protocol
-specified, http:// and all others will be treated as HTTP proxies. (The
-protocol support was added in curl 7.21.7)
+The proxy string can be specified with a protocol:// prefix. No protocol
+specified or http:// will be treated as HTTP proxy. Use socks4://, socks4a://,
+socks5:// or socks5h:// to request a specific SOCKS version to be used.
+(The protocol support was added in curl 7.21.7)
+
+HTTPS proxy support via https:// protocol prefix was added in 7.52.0 for
+OpenSSL, GnuTLS and NSS.
+
+Unrecognized and unsupported proxy protocols cause an error since 7.52.0.
+Prior versions may ignore the protocol and use http:// instead.
 
 If the port number is not specified in the proxy string, it is assumed to be
 1080.
diff --git a/docs/cmdline-opts/socks4.d b/docs/cmdline-opts/socks4.d
index ab4536af3..46354408e 100644
--- a/docs/cmdline-opts/socks4.d
+++ b/docs/cmdline-opts/socks4.d
@@ -6,10 +6,12 @@ Added: 7.15.2
 Use the specified SOCKS4 proxy. If the port number is not specified, it is
 assumed at port 1080.
 
-This option overrides any previous use of --proxy, as they are mutually
-exclusive.
-
 Since 7.21.7, this option is superfluous since you can specify a socks4 proxy
 with --proxy using a socks4:// protocol prefix.
 
+This option typically overrides any previous use of --proxy; however since
+7.52.0 if --proxy is used to specify an HTTP or HTTPS proxy then curl will
+attempt to use it with the SOCKS proxy. In such a case curl first connects to
+the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
+
 If this option is used several times, the last one will be used.
diff --git a/docs/cmdline-opts/socks4a.d b/docs/cmdline-opts/socks4a.d
index a1db1f56a..c7663eebd 100644
--- a/docs/cmdline-opts/socks4a.d
+++ b/docs/cmdline-opts/socks4a.d
@@ -6,10 +6,12 @@ Added: 7.18.0
 Use the specified SOCKS4a proxy. If the port number is not specified, it is
 assumed at port 1080.
 
-This option overrides any previous use of --proxy, as they are mutually
-exclusive.
-
 Since 7.21.7, this option is superfluous since you can specify a socks4a proxy
 with --proxy using a socks4a:// protocol prefix.
 
+This option typically overrides any previous use of --proxy; however since
+7.52.0 if --proxy is used to specify an HTTP or HTTPS proxy then curl will
+attempt to use it with the SOCKS proxy. In such a case curl first connects to
+the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
+
 If this option is used several times, the last one will be used.
diff --git a/docs/cmdline-opts/socks5-hostname.d b/docs/cmdline-opts/socks5-hostname.d
index d971766af..87bc44a8e 100644
--- a/docs/cmdline-opts/socks5-hostname.d
+++ b/docs/cmdline-opts/socks5-hostname.d
@@ -6,10 +6,12 @@ Added: 7.18.0
 Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If
 the port number is not specified, it is assumed at port 1080.
 
-This option overrides any previous use of --proxy, as they are mutually
-exclusive.
-
 Since 7.21.7, this option is superfluous since you can specify a socks5
 hostname proxy with --proxy using a socks5h:// protocol prefix.
 
+This option typically overrides any previous use of --proxy; however since
+7.52.0 if --proxy is used to specify an HTTP or HTTPS proxy then curl will
+attempt to use it with the SOCKS proxy. In such a case curl first connects to
+the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
+
 If this option is used several times, the last one will be used.
diff --git a/docs/cmdline-opts/socks5.d b/docs/cmdline-opts/socks5.d
index 34f0311ed..aa07afeb1 100644
--- a/docs/cmdline-opts/socks5.d
+++ b/docs/cmdline-opts/socks5.d
@@ -6,12 +6,14 @@ Added: 7.18.0
 Use the specified SOCKS5 proxy - but resolve the host name locally. If the
 port number is not specified, it is assumed at port 1080.
 
-This option overrides any previous use of --proxy, as they are mutually
-exclusive.
-
 Since 7.21.7, this option is superfluous since you can specify a socks5 proxy
 with --proxy using a socks5:// protocol prefix.
 
+This option typically overrides any previous use of --proxy; however since
+7.52.0 if --proxy is used to specify an HTTP or HTTPS proxy then curl will
+attempt to use it with the SOCKS proxy. In such a case curl first connects to
+the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
+
 If this option is used several times, the last one will be used.
 
 This option (as well as --socks4) does not work with IPV6, FTPS or LDAP.
diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d
index 9580ac9d7..03506c9de 100644
--- a/docs/cmdline-opts/write-out.d
+++ b/docs/cmdline-opts/write-out.d
@@ -60,6 +60,10 @@ Number of new connects made in the recent transfer. (Added in 7.12.3)
 .B num_redirects
 Number of redirects that were followed in the request. (Added in 7.12.3)
 .TP
+.B proxy_ssl_verify_result
+The result of the HTTPS proxy's SSL peer certificate verification that was
+requested. 0 means the verification was successful. (Added in 7.52.0)
+.TP
 .B redirect_url
 When an HTTP request was made without -L to follow redirects, this variable
 will show the actual URL a redirect \fIwould\fP take you to. (Added in 7.18.2)