cmdline-docs: extended, clarified, refreshed

Closes #18550

docs/cmdline-opts/abstract-unix-socket.md

@@ -16,6 +16,6 @@ Example:
 
 # `--abstract-unix-socket`
 
-Connect through an abstract Unix domain socket, instead of using the network.
-Note: netstat shows the path of an abstract socket prefixed with `@`, however
-the \<path\> argument should not have this leading character.
+Connect to the server through an abstract Unix domain socket, instead of using
+the network. Note: netstat shows the path of an abstract socket prefixed with
+`@`, however the \<path\> argument should not have this leading character.

docs/cmdline-opts/compressed-ssh.md

@@ -16,4 +16,5 @@ Example:
 # `--compressed-ssh`
 
 Enable SSH compression. This is a request, not an order; the server may or may
-not do it.
+not do it. This allows the data to be sent compressed over the wire, and
+automatically decompressed in the receiving end, to save bandwidth.

docs/cmdline-opts/disallow-username-in-url.md

@@ -16,3 +16,6 @@ Example:
 
 Exit with error if passed a URL containing a username. Probably most useful
 when the URL is being provided at runtime or similar.
+
+Accepting and using credentials in a URL is normally considered a security
+hazard as they are easily leaked that way.

docs/cmdline-opts/engine.md

@@ -17,6 +17,9 @@ Example:
 
 # `--engine`
 
-Select the OpenSSL crypto engine to use for cipher operations. Use --engine
-list to print a list of build-time supported engines. Note that not all (and
+Select the OpenSSL crypto engine to use for cipher operations. Use `--engine
+list` to print a list of build-time supported engines. Note that not all (and
 possibly none) of the engines may be available at runtime.
+
+The OpenSSL concept "engines" has been superseded by "providers" in OpenSSL 3,
+and this option should work fine to specify such as well.

docs/cmdline-opts/follow.md

@@ -9,6 +9,8 @@ Multi: boolean
 See-also:
   - request
   - location
+  - proto-redir
+  - max-redirs
 Example:
   - -X POST --follow $URL
 ---
@@ -23,3 +25,5 @@ status codes 307 or 308, but may be reset to GET for 301, 302 and 303.
 
 This is subtly different than --location, as that option always set the custom
 method in all subsequent requests independent of response code.
+
+Restrict which protocols a redirect is accepted to follow with --proto-redir.

docs/cmdline-opts/globoff.md

@@ -20,3 +20,6 @@ Switch off the URL globbing function. When you set this option, you can
 specify URLs that contain the letters {}[] without having curl itself
 interpret them. Note that these letters are not normal legal URL contents but
 they should be encoded according to the URI standard.
+
+curl detects numerical IPv6 addresses when used in URLs and excludes them from
+the treatment, so they can still be used without having to disable globbing.

docs/cmdline-opts/http2.md

@@ -14,6 +14,7 @@ See-also:
   - http1.1
   - http3
   - no-alpn
+  - proxy-http2
 Example:
   - --http2 $URL
 ---

docs/cmdline-opts/http3.md

@@ -33,3 +33,5 @@ still tries to proceed with an older HTTP version. The fallback performs the
 regular negotiation between HTTP/1 and HTTP/2.
 
 Use --http3-only for similar functionality *without* a fallback.
+
+curl cannot do HTTP/3 over any proxy.

docs/cmdline-opts/junk-session-cookies.md

@@ -18,5 +18,8 @@ Example:
 # `--junk-session-cookies`
 
 When curl is told to read cookies from a given file, this option makes it
-discard all "session cookies". This has the same effect as if a new session is
+discard all session cookies. This has the same effect as if a new session is
 started. Typical browsers discard session cookies when they are closed down.
+
+Session cookies are cookies without a set expiry time. They are meant to only
+last for "a session".

docs/cmdline-opts/location.md

@@ -12,6 +12,8 @@ See-also:
   - resolve
   - alt-svc
   - follow
+  - proto-redir
+  - max-redirs
 Example:
   - -L $URL
 ---
@@ -40,3 +42,5 @@ using the dedicated options for that: --post301, --post302 and --post303.
 
 The method set with --request overrides the method curl would otherwise select
 to use.
+
+Restrict which protocols a redirect is accepted to follow with --proto-redir.

docs/cmdline-opts/max-redirs.md

@@ -10,12 +10,14 @@ Added: 7.5
 Multi: single
 See-also:
   - location
+  - follow
 Example:
   - --max-redirs 3 --location $URL
 ---
 
 # `--max-redirs`
 
-Set the maximum number of redirections to follow. When --location is used, to
-prevent curl from following too many redirects, by default, the limit is
-set to 50 redirects. Set this option to -1 to make it unlimited.
+Set the maximum number of redirections to follow. When --location or --follow
+are used, this option prevents curl from following too many redirects. By
+default the limit is set to 50 redirects. Set this option to -1 to make it
+unlimited.

docs/cmdline-opts/proto-redir.md

@@ -9,8 +9,9 @@ Category: connection curl
 Multi: single
 See-also:
   - proto
+  - follow
 Example:
-  - --proto-redir =http,https $URL
+  - --proto-redir =http,https --follow $URL
 ---
 
 # `--proto-redir`
@@ -20,7 +21,7 @@ not overridden by this option. See --proto for how protocols are represented.
 
 Example, allow only HTTP and HTTPS on redirect:
 
-    curl --proto-redir -all,http,https http://example.com
+    curl --proto-redir -all,http,https --follow http://example.com
 
 By default curl only allows HTTP, HTTPS, FTP and FTPS on redirects
 (added in 7.65.2). Specifying *all* or *+all* enables all protocols on

docs/cmdline-opts/proxy.md

@@ -31,8 +31,7 @@ HTTPS proxy support works with the https:// protocol prefix for OpenSSL and
 GnuTLS (added in 7.52.0). It also works for mbedTLS, Rustls, Schannel and
 wolfSSL (added in 7.87.0).
 
-Unrecognized and unsupported proxy protocols cause an error (added in 7.52.0).
-Ancient curl versions ignored unknown schemes and used http:// instead.
+Unrecognized and unsupported proxy protocol schemes cause an error.
 
 If the port number is not specified in the proxy string, it is assumed to be
 1080.

docs/cmdline-opts/request.md

@@ -10,8 +10,9 @@ Added: 6.0
 Multi: single
 See-also:
   - request-target
+  - follow
 Example:
-  - -X "DELETE" $URL
+  - --request "DELETE" $URL
   - -X NLST ftp://example.com/
 ---
 
@@ -37,10 +38,10 @@ This option only changes the actual word used in the HTTP request, it does not
 alter the way curl behaves. For example if you want to make a proper HEAD
 request, using -X HEAD does not suffice. You need to use the --head option.
 
-The method string you set with --request is used for all requests, which
-if you for example use --location may cause unintended side-effects when curl
-does not change request method according to the HTTP 30x response codes - and
-similar.
+If --location is used, the method string you set with --request is used for
+all requests, which may cause unintended side-effects when curl does not
+change request method according to the HTTP 30x response codes - and similar.
+Consider using --follow instead in combination with --request.
 
 ## FTP
 Specifies a custom FTP command to use instead of *LIST* when doing file lists

docs/cmdline-opts/retry-connrefused.md

@@ -15,5 +15,7 @@ Example:
 
 # `--retry-connrefused`
 
-In addition to the other conditions, consider ECONNREFUSED as a transient
-error too for --retry. This option is used together with --retry.
+In addition to the other conditions, also consider ECONNREFUSED as a transient
+error for --retry. This option is used together with --retry. Normally, a
+confused connection is not considered a transient error and therefore thus not
+otherwise trigger a retry.

docs/cmdline-opts/retry.md

@@ -9,6 +9,8 @@ Category: curl
 Multi: single
 See-also:
   - retry-max-time
+  - retry-connrefused
+  - retry-delay
 Example:
   - --retry 7 $URL
 ---
@@ -16,16 +18,17 @@ Example:
 # `--retry`
 
 If a transient error is returned when curl tries to perform a transfer, it
-retries this number of times before giving up. Setting the number to 0
-makes curl do no retries (which is the default). Transient error means either:
-a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504
+retries this number of times before giving up. Setting the number to 0 makes
+curl do no retries (which is the default). Transient error means either: a
+timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504
 response code.
 
 When curl is about to retry a transfer, it first waits one second and then for
 all forthcoming retries it doubles the waiting time until it reaches 10
 minutes, which then remains the set fixed delay time between the rest of the
-retries. By using --retry-delay you disable this exponential backoff algorithm.
-See also --retry-max-time to limit the total time allowed for retries.
+retries. By using --retry-delay you disable this exponential backoff
+algorithm. See also --retry-max-time to limit the total time allowed for
+retries.
 
 curl complies with the Retry-After: response header if one was present to know
 when to issue the next retry (added in 7.66.0).

docs/cmdline-opts/sasl-ir.md

@@ -14,4 +14,6 @@ Example:
 
 # `--sasl-ir`
 
-Enable initial response in SASL authentication.
+Enable initial response in SASL authentication. Such an "initial response" is
+a message sent by the client to the server after the client selects an
+authentication mechanism.

docs/cmdline-opts/tr-encoding.md

@@ -17,3 +17,8 @@ Example:
 
 Request a compressed Transfer-Encoding response using one of the algorithms
 curl supports, and uncompress the data while receiving it.
+
+This method was once intended to be the way to do automatic data compression
+for HTTP but for all practical purposes using Content-Encoding as done with
+--compressed has superseded transfer encoding. The --tr-encoding option is
+therefore often not be one you want.

docs/cmdline-opts/trace-ids.md

@@ -18,3 +18,7 @@ Example:
 
 Prepend the transfer and connection identifiers to each trace or verbose line
 that curl displays.
+
+The identifiers are unique numbers assigned to each connection and transfer to
+allow a user to better understand which transfer and connection each verbose
+output line refers to.

docs/cmdline-opts/unix-socket.md

@@ -16,4 +16,7 @@ Example:
 
 # `--unix-socket`
 
-Connect through this Unix domain socket, instead of using the network.
+Connect to the server through this Unix domain socket, instead of using the
+network.
+
+To connect to a proxy over Unix domain socket, see --proxy.