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

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

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.

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".

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.