src: add --http3-only

Warning: --http3 and --http3-only are subject to change again (or be
removed) before HTTP/3 support goes non-experimental.

Closes #10264

docs/cmdline-opts/Makefile.inc

@@ -107,6 +107,7 @@ DPAGES = \
   http2-prior-knowledge.d \
   http2.d \
   http3.d \
+  http3-only.d \
   ignore-content-length.d \
   include.d \
   insecure.d \

docs/cmdline-opts/http3-only.d

@@ -0,0 +1,25 @@
+c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+SPDX-License-Identifier: curl
+Long: http3-only
+Tags: Versions
+Protocols: HTTP
+Added: 7.88.0
+Mutexed: http1.1 http1.0 http2 http2-prior-knowledge http3
+Requires: HTTP/3
+Help: Use HTTP v3 only
+See-also: http1.1 http2 http3
+Category: http
+Example: --http3-only $URL
+Multi: mutex
+Experimental: yes
+---
+Instructs curl to use HTTP/3 to the host in the URL, with no fallback to
+earlier HTTP versions. HTTP/3 can only be used for HTTPS and not for HTTP
+URLs. For HTTP, this option will trigger an error.
+
+This option allows a user to avoid using the Alt-Svc method of upgrading to
+HTTP/3 when you know that the target speaks HTTP/3 on the given host and port.
+
+This option will make curl fail if a QUIC connection cannot be established, it
+will not attempt any other HTTP version on its own. Use --http3 for similar
+fuctionality *with* a fallback.

docs/cmdline-opts/http3.d

@@ -4,7 +4,7 @@ Long: http3
 Tags: Versions
 Protocols: HTTP
 Added: 7.66.0
-Mutexed: http1.1 http1.0 http2 http2-prior-knowledge
+Mutexed: http1.1 http1.0 http2 http2-prior-knowledge http3-only
 Requires: HTTP/3
 Help: Use HTTP v3
 See-also: http1.1 http2
@@ -13,10 +13,15 @@ Example: --http3 $URL
 Multi: mutex
 Experimental: yes
 ---
-Tells curl to use HTTP version 3 directly to the host and port number used in
-the URL. A normal HTTP/3 transaction will be done to a host and then get
-redirected via Alt-Svc, but this option allows a user to circumvent that when
-you know that the target speaks HTTP/3 on the given host and port.
+Tells curl to try HTTP/3 to the host in the URL, but fallback to earlier
+HTTP versions if the HTTP/3 connection establishement fails. HTTP/3 is only
+available for HTTPS and not for HTTP URLs.
 
-This option will make curl fail if a QUIC connection cannot be established, it
-cannot fall back to a lower HTTP version on its own.
+This option allows a user to avoid using the Alt-Svc method of upgrading to
+HTTP/3 when you know that the target speaks HTTP/3 on the given host and port.
+
+When asked to use HTTP/3, curl will issue a separate attempt to use older HTTP
+versions with a slight delay, so if the HTTP/3 transfer fails or is very slow,
+curl will still try to proceed with an older HTTP version.
+
+Use --http3-only for similar fuctionality *without* a fallback.

docs/options-in-versions

@@ -93,6 +93,7 @@
 --http2                              7.33.0
 --http2-prior-knowledge              7.49.0
 --http3                              7.66.0
+--http3-only                         7.88.0
 --ignore-content-length              7.14.1
 --include (-i)                       4.8
 --insecure (-k)                      7.10