cmdline-docs: extended, clarified, refreshed

Closes #18550

diff --git a/docs/cmdline-opts/abstract-unix-socket.md b/docs/cmdline-opts/abstract-unix-socket.md
index 7078e642fd8bef7f1b93744098ab4f59da627b36..b1b6100e1611a274827b64ad8d0a8398e04caa14 100644 (file)
--- a/docs/cmdline-opts/abstract-unix-socket.md
+++ b/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.

diff --git a/docs/cmdline-opts/compressed-ssh.md b/docs/cmdline-opts/compressed-ssh.md
index 955c59c2b704fdaf4c44a947b2a6b1da4469f3e6..07d3981b484e7a19adcd7bdf805390b8c1a93c93 100644 (file)
--- a/docs/cmdline-opts/compressed-ssh.md
+++ b/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.

diff --git a/docs/cmdline-opts/disallow-username-in-url.md b/docs/cmdline-opts/disallow-username-in-url.md
index 012f2d0dc80af5dce5b55044da938e1e65797798..0507f531cc76b4f852c81d198a802912c210066d 100644 (file)
--- a/docs/cmdline-opts/disallow-username-in-url.md
+++ b/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.

diff --git a/docs/cmdline-opts/engine.md b/docs/cmdline-opts/engine.md
index 511190023ef2088f5186fb0ff2c97299a4aaeb47..cde6949b8691ee30927175f46b17593f62a3b9b4 100644 (file)
--- a/docs/cmdline-opts/engine.md
+++ b/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.

diff --git a/docs/cmdline-opts/follow.md b/docs/cmdline-opts/follow.md
index 9d4225ab355dcea5c88a2b218e05b237272629de..47d9128441808def2a303d44ab1b9eb22a01577f 100644 (file)
--- a/docs/cmdline-opts/follow.md
+++ b/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.

diff --git a/docs/cmdline-opts/globoff.md b/docs/cmdline-opts/globoff.md
index 3c8c341439d344036889d32c19a0efcb6d6fc639..5ef4b2ae884334a0526127cb971bf4c1809168b6 100644 (file)
--- a/docs/cmdline-opts/globoff.md
+++ b/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.

diff --git a/docs/cmdline-opts/http2.md b/docs/cmdline-opts/http2.md
index ae4d26974c8b008315de53833cf6d39f7ae1115f..f5180be2b5333be9e56ac3dcaa5759b98f58ab1f 100644 (file)
--- a/docs/cmdline-opts/http2.md
+++ b/docs/cmdline-opts/http2.md
@@ -14,6 +14,7 @@ See-also:
   - http1.1
   - http3
   - no-alpn
+  - proxy-http2
 Example:
   - --http2 $URL
 ---

diff --git a/docs/cmdline-opts/http3.md b/docs/cmdline-opts/http3.md
index a66d7978297efb9fbb9c7687e045f7c50cdd7618..e4dfeef075be87ee14a038efa02aebf33289e77f 100644 (file)
--- a/docs/cmdline-opts/http3.md
+++ b/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.

diff --git a/docs/cmdline-opts/junk-session-cookies.md b/docs/cmdline-opts/junk-session-cookies.md
index 63971050c030358fc06af00326eccb08d74ec715..668dfce2d67f533490c3794d61c95b22c3932200 100644 (file)
--- a/docs/cmdline-opts/junk-session-cookies.md
+++ b/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".

diff --git a/docs/cmdline-opts/location.md b/docs/cmdline-opts/location.md
index 86ae7e358013b09513683c142e96f12003ba5ea8..56950c2dfc1e05befde054727e8d5028181a171c 100644 (file)
--- a/docs/cmdline-opts/location.md
+++ b/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.

diff --git a/docs/cmdline-opts/max-redirs.md b/docs/cmdline-opts/max-redirs.md
index 7c9f193d2c4df5f23c68eb1abee77793be9a8db9..02bdfaa7fb63e478c6e5191be1ee48cb0b4bee04 100644 (file)
--- a/docs/cmdline-opts/max-redirs.md
+++ b/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.

diff --git a/docs/cmdline-opts/proto-redir.md b/docs/cmdline-opts/proto-redir.md
index 337aa93cb682fd82a8e5779238b74546ff0c638e..1f75bfdfd6c9ff0a9889222754bbc1f2cee58c29 100644 (file)
--- a/docs/cmdline-opts/proto-redir.md
+++ b/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

diff --git a/docs/cmdline-opts/proxy.md b/docs/cmdline-opts/proxy.md
index 1ed503c108440a61c5e8a58942c6d6d2bab57b47..6cd456169d3454ecf0a7f7ad027dda3a08e48615 100644 (file)
--- a/docs/cmdline-opts/proxy.md
+++ b/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.

diff --git a/docs/cmdline-opts/request.md b/docs/cmdline-opts/request.md
index 86cf10deafa4cc47a7fb5b8fda1e37a210b2aea5..2c9d7776e587c1e8ad56cb1623f5f6be0340b192 100644 (file)
--- a/docs/cmdline-opts/request.md
+++ b/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

diff --git a/docs/cmdline-opts/retry-connrefused.md b/docs/cmdline-opts/retry-connrefused.md
index 22345cd8818eaf19c8a07956f5097d913867c294..2e6ba8068696d2f76155e4c33f8e78d5a80d24a0 100644 (file)
--- a/docs/cmdline-opts/retry-connrefused.md
+++ b/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.

diff --git a/docs/cmdline-opts/retry.md b/docs/cmdline-opts/retry.md
index 2176e8f43da155b2ad283e90eac097bbff2f75df..f55d8edcca12f89577cd215113e96ffc18907485 100644 (file)
--- a/docs/cmdline-opts/retry.md
+++ b/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).

diff --git a/docs/cmdline-opts/sasl-ir.md b/docs/cmdline-opts/sasl-ir.md
index b11137df0a63a8bfd679128d60131c78330f7fbb..0f759c6d1005be9b52872aebba610e0b5a2955f4 100644 (file)
--- a/docs/cmdline-opts/sasl-ir.md
+++ b/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.

diff --git a/docs/cmdline-opts/tr-encoding.md b/docs/cmdline-opts/tr-encoding.md
index cdd8f02d67b3b94a091e89f9f39a2d964f0b1626..c364c07d4b23f15bfe3b12361aa16a9a8aedf857 100644 (file)
--- a/docs/cmdline-opts/tr-encoding.md
+++ b/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.

diff --git a/docs/cmdline-opts/trace-ids.md b/docs/cmdline-opts/trace-ids.md
index b9a622260040f0823c1d27b6251ea457ae366c69..302631d8440e50cb73298f44baafaf1fea5e1988 100644 (file)
--- a/docs/cmdline-opts/trace-ids.md
+++ b/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.

diff --git a/docs/cmdline-opts/unix-socket.md b/docs/cmdline-opts/unix-socket.md
index 582f32dc50e1523d38fca84ac82d9033360679b0..34cc714f79df15ae28cc886e861b3bda21278ba0 100644 (file)
--- a/docs/cmdline-opts/unix-socket.md
+++ b/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.