update docs for protocol negotiation and gen man

docs/README.md

@@ -1890,37 +1890,49 @@ By opposition to the previous section, you can force the HTTP/3, HTTP/2 or HTTP/
 $ https --http3 pie.dev/get
 ```
 
-By default, HTTPie cannot negotiate HTTP/3 without a first HTTP/1.1, or HTTP/2 successful response unless the
-remote host specified a DNS HTTPS record that indicate its support (and by using a custom DNS resolver, see bellow section).
+For HTTP (unencrypted) URLs, you can enforce HTTP 1 or HTTP 2 but not HTTP 3.
+You cannot enforce multiple protocols like `--http2 --http3`, they (toggles) are mutually exclusive.
 
-The remote server yield its support for HTTP/3 in the `Alt-Svc` header, if present HTTPie will issue
-the successive requests via HTTP/3. You may use that argument in case the remote peer does not support
-either HTTP/1.1 or HTTP/2.
+### Protocol selection
+
+By default, HTTPie follows what modern browser do to choose a protocol.
+
+#### For HTTP URLs
+
+HTTP/1.1 will always be chosen unless you specified `--http2` to enforce HTTP/2 with prior knowledge (also known as h2c).
+
+Notes:
+
+- You cannot enforce HTTP/3.
+- You cannot disable both HTTP/1.1 and HTTP/2.
 
-### Protocol combinations
+#### For HTTPS URLs
 
-Following `Force HTTP/3, HTTP/2 and HTTP/1` and `Disable HTTP/1, HTTP/2, or HTTP/3`, you may find a summary on how to make HTTPie negotiate a
-specific protocol.
+When reaching to an SSL/TLS server, HTTPie negotiate the protocol through what is called the ALPN extension during
+the handshake.
 
-|                         Arguments | HTTP/1.1 <br>enabled | HTTP/2 <br>enabled | HTTP/3 <br>enabled |
-|----------------------------------:|:--------------------:|:------------------:|:------------------:|
-|                         (Default) |          ✔           |         ✔          |         ✔          |
-|                 `--disable-http1` |          ✗           |         ✔          |         ✔          |
-|                 `--disable-http2` |          ✔           |         ✗          |         ✔          |
-|                 `--disable-http3` |          ✔           |         ✔          |         ✗          |
-| `--disable-http2 --disable-http3` |          ✔           |         ✗          |         ✗          |
-| `--disable-http1 --disable-http2` |          ✗           |         ✗          |         ✔          |
-|                         `--http1` |          ✔           |         ✗          |         ✗          |
-|                         `--http2` |          ✗           |         ✔          |         ✗          |
-|                         `--http3` |          ✗           |         ✗          |         ✔          |
+Basically, HTTPie says during the "Hello" phase: "I can speak HTTP/1.1 and HTTP/2 over TCP, and you?".
+Depending on what the server respond to us, we will choose a mutual supported protocols.
 
-Some specifics, through:
+Nowadays, it is most certainly be HTTP/2 by default.
 
-- You cannot enforce HTTP/3 over non HTTPS URLs.
-- You cannot disable both HTTP/1.1 and HTTP/2 for non HTTPS URLs.
-- Of course, you cannot disable all three protocols.
+Some specifics:
+
+- You cannot disable all three protocols.
 - Those toggles do not apply to the DNS-over-HTTPS custom resolver. You will have to specify it within the resolver URL.
 - When reaching a HTTPS URL, the ALPN extension sent during SSL/TLS handshake is affected.
+- HTTPie never tries HTTP/3 by default unless something hints us that it is possible.
+
+##### HTTP 3 Negotiation
+
+By default, HTTPie cannot negotiate HTTP/3 without a first HTTP/1.1, or HTTP/2 successful response unless the
+remote host specified a DNS HTTPS record that indicate its support (and by using a custom DNS resolver, see bellow section).
+
+The remote server yield its support for HTTP/3 in the `Alt-Svc` header, if present HTTPie will issue
+the successive requests via HTTP/3. You may use that argument in case the remote peer does not support
+either HTTP/1.1 or HTTP/2.
+
+Note: HTTPie caches what server are QUIC compatible in the `config` directory so that we can remember.
 
 ## Custom DNS resolver
 

extras/man/http.1

@@ -1,5 +1,5 @@
 .\" This file is auto-generated from the parser declaration in httpie/cli/definition.py by extras/scripts/generate_man_pages.py.
-.TH http 1 "2024-01-01" "HTTPie 4.0.0.b1" "HTTPie Manual"
+.TH http 1 "2024-06-25" "HTTPie 4.0.0" "HTTPie Manual"
 .SH NAME
 http
 .SH SYNOPSIS
@@ -496,12 +496,30 @@ Bypass dot segment (/../ or /./) URL squashing.
 Enable streaming via chunked transfer encoding. The Transfer-Encoding header is set to chunked.
 
 
+.IP "\fB\,--disable-http1\/\fR"
+
+
+Disable the HTTP/1 protocol.
+
+
+.IP "\fB\,--http1\/\fR"
+
+
+Use the HTTP/1 protocol for the request.
+
+
 .IP "\fB\,--disable-http2\/\fR"
 
 
 Disable the HTTP/2 protocol.
 
 
+.IP "\fB\,--http2\/\fR"
+
+
+Use the HTTP/2 protocol for the request.
+
+
 .IP "\fB\,--disable-http3\/\fR"
 
 

extras/man/httpie.1

@@ -1,5 +1,5 @@
 .\" This file is auto-generated from the parser declaration in httpie/manager/cli.py by extras/scripts/generate_man_pages.py.
-.TH httpie 1 "2024-01-01" "HTTPie 4.0.0.b1" "HTTPie Manual"
+.TH httpie 1 "2024-06-25" "HTTPie 4.0.0" "HTTPie Manual"
 .SH NAME
 httpie
 .SH SYNOPSIS

extras/man/https.1

@@ -1,5 +1,5 @@
 .\" This file is auto-generated from the parser declaration in httpie/cli/definition.py by extras/scripts/generate_man_pages.py.
-.TH https 1 "2024-01-01" "HTTPie 4.0.0.b1" "HTTPie Manual"
+.TH https 1 "2024-06-25" "HTTPie 4.0.0" "HTTPie Manual"
 .SH NAME
 https
 .SH SYNOPSIS
@@ -496,12 +496,30 @@ Bypass dot segment (/../ or /./) URL squashing.
 Enable streaming via chunked transfer encoding. The Transfer-Encoding header is set to chunked.
 
 
+.IP "\fB\,--disable-http1\/\fR"
+
+
+Disable the HTTP/1 protocol.
+
+
+.IP "\fB\,--http1\/\fR"
+
+
+Use the HTTP/1 protocol for the request.
+
+
 .IP "\fB\,--disable-http2\/\fR"
 
 
 Disable the HTTP/2 protocol.
 
 
+.IP "\fB\,--http2\/\fR"
+
+
+Use the HTTP/2 protocol for the request.
+
+
 .IP "\fB\,--disable-http3\/\fR"