From: Daniel Stenberg <daniel@haxx.se>
Date: Tue, 21 Feb 2023 15:42:26 +0000 (+0100)
Subject: docs/cmdline-opts: mark all global options
X-Git-Tag: curl-8_0_0~176
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=86ec17b8560cf4613b752c52feb8e2f11f9e6c05;p=thirdparty%2Fcurl.git

docs/cmdline-opts: mark all global options

gen.pl now outputs a generic explanations for them for each option

Fixes #10566
Reported-by: u20221022 on github
Closes #10584
---

diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md
index 5a584ee2a7..541d7806bf 100644
--- a/docs/cmdline-opts/MANPAGE.md
+++ b/docs/cmdline-opts/MANPAGE.md
@@ -35,6 +35,7 @@ Each file has a set of meta-data and a body of text.
     Mutexed: (space separated list of options this overrides, no dashes)
     Protocols: (space separated list for which protocols this option works)
     Requires: (space separated list of features this requires, no dashes)
+    Scope: global (if the option is global)
     See-also: (space separated list of related options, no dashes)
     Short: (single letter, without dash)
     SPDX-License-Identifier: curl
diff --git a/docs/cmdline-opts/fail-early.d b/docs/cmdline-opts/fail-early.d
index 339970539c..975f346271 100644
--- a/docs/cmdline-opts/fail-early.d
+++ b/docs/cmdline-opts/fail-early.d
@@ -7,6 +7,7 @@ Category: curl
 Example: --fail-early $URL https://two.example
 See-also: fail fail-with-body
 Multi: boolean
+Scope: global
 ---
 Fail and exit on the first detected transfer error.
 
@@ -20,8 +21,6 @@ Using this option, curl will instead return an error on the first transfer
 that fails, independent of the amount of URLs that are given on the command
 line. This way, no transfer failures go undetected by scripts and similar.
 
-This option is global and does not need to be specified for each use of --next.
-
 This option does not imply --fail, which causes transfers to fail due to the
 server's HTTP status code. You can combine the two options, however note --fail
 is not global and is therefore contained by --next.
diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl
index f6ffb28f3e..8f0d636ca2 100755
--- a/docs/cmdline-opts/gen.pl
+++ b/docs/cmdline-opts/gen.pl
@@ -211,6 +211,7 @@ sub single {
     my $magic; # cmdline special option
     my $line;
     my $multi;
+    my $scope;
     my $experimental;
     while(<F>) {
         $line++;
@@ -253,6 +254,9 @@ sub single {
         elsif(/^Multi: *(.*)/i) {
             $multi=$1;
         }
+        elsif(/^Scope: *(.*)/i) {
+            $scope=$1;
+        }
         elsif(/^Experimental: yes/i) {
             $experimental=1;
         }
@@ -347,6 +351,16 @@ sub single {
     printdesc(@desc);
     undef @desc;
 
+    if($scope) {
+        if($scope eq "global") {
+            print "\nThis option is global and does not need to be specified for each use of --next.\n";
+        }
+        else {
+            print STDERR "$f:$line:1:ERROR: unrecognized scope: '$scope'\n";
+            return 2;
+        }
+    }
+
     my @extra;
     if($multi eq "single") {
         push @extra, "\nIf --$long is provided several times, the last set ".
@@ -406,6 +420,7 @@ sub single {
         }
         push @foot, seealso($standalone, $mstr);
     }
+
     if($requires) {
         my $l = manpageify($long);
         push @foot, "$l requires that the underlying libcurl".
diff --git a/docs/cmdline-opts/libcurl.d b/docs/cmdline-opts/libcurl.d
index a7ad6c9075..0f5d5826c6 100644
--- a/docs/cmdline-opts/libcurl.d
+++ b/docs/cmdline-opts/libcurl.d
@@ -8,10 +8,8 @@ Category: curl
 Example: --libcurl client.c $URL
 See-also: verbose
 Multi: single
+Scope: global
 ---
 Append this option to any ordinary curl command line, and you will get
 libcurl-using C source code written to the file that does the equivalent
 of what your command-line operation does!
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/page-header b/docs/cmdline-opts/page-header
index 44c245c55e..3907460f12 100644
--- a/docs/cmdline-opts/page-header
+++ b/docs/cmdline-opts/page-header
@@ -197,3 +197,7 @@ In general, all boolean options are enabled with --**option** and yet again
 disabled with --**no-**option. That is, you use the same option name but
 prefix it with "no-". However, in this list we mostly only list and show the
 --option version of them.
+
+When --next is used, it resets the parser state and you start again with a
+clean option state, except for the options that are "global". Global options
+will retain their values and meaning even after --next.
diff --git a/docs/cmdline-opts/parallel-immediate.d b/docs/cmdline-opts/parallel-immediate.d
index 9d8aa8bcbc..da15d62771 100644
--- a/docs/cmdline-opts/parallel-immediate.d
+++ b/docs/cmdline-opts/parallel-immediate.d
@@ -7,11 +7,9 @@ See-also: parallel parallel-max
 Category: connection curl
 Example: --parallel-immediate -Z $URL -o file1 $URL -o file2
 Multi: boolean
+Scope: global
 ---
 When doing parallel transfers, this option will instruct 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.
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/parallel.d b/docs/cmdline-opts/parallel.d
index 8123af2769..4f698f8b3a 100644
--- a/docs/cmdline-opts/parallel.d
+++ b/docs/cmdline-opts/parallel.d
@@ -8,9 +8,7 @@ Category: connection curl
 Example: --parallel $URL -o file1 $URL -o file2
 See-also: next verbose
 Multi: boolean
+Scope: global
 ---
 Makes curl perform its transfers in parallel as compared to the regular serial
 manner.
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/progress-bar.d b/docs/cmdline-opts/progress-bar.d
index 5b7eee450c..a6cc8f50e3 100644
--- a/docs/cmdline-opts/progress-bar.d
+++ b/docs/cmdline-opts/progress-bar.d
@@ -8,6 +8,7 @@ Example: -# -O $URL
 Added: 5.10
 See-also: styled-output
 Multi: boolean
+Scope: global
 ---
 Make curl display transfer progress as a simple progress bar instead of the
 standard, more informational, meter.
@@ -17,6 +18,3 @@ shows a percentage if the transfer size is known. For transfers without a
 known size, there will be space ship (-=o=-) that moves back and forth but
 only while data is being transferred, with a set of flying hash sign symbols on
 top.
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/rate.d b/docs/cmdline-opts/rate.d
index d12386cbb4..4f2ec4011c 100644
--- a/docs/cmdline-opts/rate.d
+++ b/docs/cmdline-opts/rate.d
@@ -10,6 +10,7 @@ Example: --rate 14/m $URL
 Added: 7.84.0
 See-also: limit-rate retry-delay
 Multi: single
+Scope: global
 ---
 Specify the maximum transfer frequency you allow curl to use - in number of
 transfer starts per time unit (sometimes called request rate). Without this
diff --git a/docs/cmdline-opts/show-error.d b/docs/cmdline-opts/show-error.d
index bf1c74e75d..f150287458 100644
--- a/docs/cmdline-opts/show-error.d
+++ b/docs/cmdline-opts/show-error.d
@@ -8,8 +8,6 @@ Category: curl
 Example: --show-error --silent $URL
 Added: 5.9
 Multi: boolean
+Scope: global
 ---
 When used with --silent, it makes curl show an error message if it fails.
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/stderr.d b/docs/cmdline-opts/stderr.d
index 3caca73276..a80bf43d1c 100644
--- a/docs/cmdline-opts/stderr.d
+++ b/docs/cmdline-opts/stderr.d
@@ -8,9 +8,7 @@ Category: verbose
 Example: --stderr output.txt $URL
 Added: 6.2
 Multi: single
+Scope: global
 ---
 Redirect all writes to stderr to the specified file instead. If the file name
 is a plain '-', it is instead written to stdout.
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/styled-output.d b/docs/cmdline-opts/styled-output.d
index 35c791eca0..70e9da4e84 100644
--- a/docs/cmdline-opts/styled-output.d
+++ b/docs/cmdline-opts/styled-output.d
@@ -7,12 +7,10 @@ Category: verbose
 Example: --styled-output -I $URL
 See-also: head verbose
 Multi: boolean
+Scope: global
 ---
 Enables the automatic use of bold font styles when writing HTTP headers to the
 terminal. Use --no-styled-output to switch them off.
 
 Styled output requires a terminal that supports bold fonts. This feature is
 not present on curl for Windows due to lack of this capability.
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/trace-ascii.d b/docs/cmdline-opts/trace-ascii.d
index 49d16f4b61..3d74b29038 100644
--- a/docs/cmdline-opts/trace-ascii.d
+++ b/docs/cmdline-opts/trace-ascii.d
@@ -9,6 +9,7 @@ Example: --trace-ascii log.txt $URL
 Added: 7.9.7
 See-also: verbose trace
 Multi: single
+Scope: global
 ---
 Enables a full trace dump of all incoming and outgoing data, including
 descriptive information, to the given output file. Use "-" as filename to have
@@ -17,6 +18,3 @@ the output sent to stdout.
 This is similar to --trace, but leaves out the hex part and only shows the
 ASCII part of the dump. It makes smaller output that might be easier to read
 for untrained humans.
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/trace-time.d b/docs/cmdline-opts/trace-time.d
index 5ed412eda0..f40ee02d7c 100644
--- a/docs/cmdline-opts/trace-time.d
+++ b/docs/cmdline-opts/trace-time.d
@@ -7,8 +7,6 @@ Category: verbose
 Example: --trace-time --trace-ascii output $URL
 See-also: trace verbose
 Multi: boolean
+Scope: global
 ---
 Prepends a time stamp to each trace or verbose line that curl displays.
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/trace.d b/docs/cmdline-opts/trace.d
index 8123f60dff..1b422c2f05 100644
--- a/docs/cmdline-opts/trace.d
+++ b/docs/cmdline-opts/trace.d
@@ -9,11 +9,9 @@ Example: --trace log.txt $URL
 Added: 7.9.7
 See-also: trace-ascii trace-time
 Multi: single
+Scope: global
 ---
 Enables a full trace dump of all incoming and outgoing data, including
 descriptive information, to the given output file. Use "-" as filename to have
 the output sent to stdout. Use "%" as filename to have the output sent to
 stderr.
-
-This option is global and does not need to be specified for each use of
---next.
diff --git a/docs/cmdline-opts/verbose.d b/docs/cmdline-opts/verbose.d
index b6cef104bc..4036aadc5e 100644
--- a/docs/cmdline-opts/verbose.d
+++ b/docs/cmdline-opts/verbose.d
@@ -4,11 +4,12 @@ Short: v
 Long: verbose
 Mutexed: trace trace-ascii
 Help: Make the operation more talkative
-See-also: include
+See-also: include silent trace trace-ascii
 Category: important verbose
 Example: --verbose $URL
 Added: 4.0
 Multi: boolean
+Scope: global
 ---
 Makes curl verbose during the operation. Useful for debugging and seeing
 what's going on "under the hood". A line starting with '>' means "header data"
@@ -16,13 +17,8 @@ sent by curl, '<' means "header data" received by curl that is hidden in
 normal cases, and a line starting with '*' means additional info provided by
 curl.
 
-If you only want HTTP headers in the output, --include might be the option
-you are looking for.
+If you only want HTTP headers in the output, --include or --dump-header might
+be more suitable options.
 
 If you think this option still does not give you enough details, consider using
 --trace or --trace-ascii instead.
-
-This option is global and does not need to be specified for each use of
---next.
-
-Use --silent to make curl really quiet.