From: Daniel Stenberg <daniel@haxx.se>
Date: Wed, 5 Jun 2024 07:34:32 +0000 (+0200)
Subject: cmdline-opts: expand the parallel explanations
X-Git-Tag: curl-8_9_0~291
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=6ceb23dc097d4a9f3a7d1cd07723c7f99a5fc7ab;p=thirdparty%2Fcurl.git

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 f93a355f27..88b2a658f9 100644
--- 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 f3d2ad1981..ef9f5ac255 100644
--- 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 f67598a0b8..9d59a4890a 100644
--- 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.