cmdline-opts: expand the parallel explanations

Closes #13886

diff --git a/docs/cmdline-opts/parallel-immediate.md b/docs/cmdline-opts/parallel-immediate.md
index f93a355f27c15365bf96fdd3780d8aa2e55ae9db..88b2a658f916dbf5e9a8fb5d5b93b240856a9da4 100644 (file)
--- a/docs/cmdline-opts/parallel-immediate.md
+++ b/docs/cmdline-opts/parallel-immediate.md
@@ -16,7 +16,10 @@ Example:
 
 # `--parallel-immediate`
 
-When doing parallel transfers, this option instructs curl that it should
-rather prefer opening up more connections in parallel at once rather than
-waiting to see if new transfers can be added as multiplexed streams on another
-connection.
+When doing parallel transfers, this option instructs curl to prefer opening up
+more connections in parallel at once rather than waiting to see if new
+transfers can be added as multiplexed streams on another connection.
+
+By default, without this option set, curl prefers to wait a little and
+multiplex new transfers over existing connections. It keeps the number of
+connections low at the expense of risking a slightly slower transfer startup.

diff --git a/docs/cmdline-opts/parallel-max.md b/docs/cmdline-opts/parallel-max.md
index f3d2ad19813fdbc9f582b0f20f9ecd3d002aa88e..ef9f5ac255660cbc9f3d7cda3ae961c141ffb041 100644 (file)
--- a/docs/cmdline-opts/parallel-max.md
+++ b/docs/cmdline-opts/parallel-max.md
@@ -7,6 +7,7 @@ Help: Maximum concurrency for parallel transfers
 Added: 7.66.0
 Category: connection curl
 Multi: single
+Scope: global
 See-also:
   - parallel
 Example:
@@ -18,7 +19,5 @@ Example:
 When asked to do parallel transfers, using --parallel, this option controls
 the maximum amount of transfers to do simultaneously.
 
-This option is global and does not need to be specified for each use of
---next.
+The default is 50. 300 is the largest supported value.
 
-The default is 50.

diff --git a/docs/cmdline-opts/parallel.md b/docs/cmdline-opts/parallel.md
index f67598a0b8b8d6bf8513def91b694e6534485103..9d59a4890ace991ed6e99be33cadc6b218696df3 100644 (file)
--- a/docs/cmdline-opts/parallel.md
+++ b/docs/cmdline-opts/parallel.md
@@ -11,11 +11,22 @@ Scope: global
 See-also:
   - next
   - verbose
+  - parallel-max
+  - parallel-immediate
 Example:
   - --parallel $URL -o file1 $URL -o file2
 ---
 
 # `--parallel`
 
-Makes curl perform its transfers in parallel as compared to the regular serial
-manner.
+Makes curl perform all transfers in parallel as compared to the regular serial
+manner. Parallel transfer means that curl runs up to N concurrent transfers
+simultaneously and if there are more than N transfers to handle, it starts new
+ones when earlier transfers finish.
+
+With parallel transfers, the progress meter output is different than when
+doing serial transfers, as it then displays the transfer status for multiple
+transfers in a single line.
+
+The maximum amount of concurrent transfers is set with --parallel-max and it
+defaults to 50.