cmdline-opts: support generating the --help output

docs/cmdline-opts/MANPAGE.md

@@ -26,6 +26,7 @@ Each file has a set of meta-data and a body of text.
     Mutexed: (space separated list of options this overrides)
     Requires: (space separated list of features this option requres)
     See-also: (space separated list of related options)
+    Help: (short text for the --help output for this option)
     --- (end of meta-data)
 
 ### Body
@@ -37,11 +38,15 @@ correct markup that shows both short and long version.
 ## Header
 
 `page-header` is the nroff formatted file that will be output before the
-generated options output.
+generated options output for the master man page.
 
 ## Generate
 
-`perl gen.pl`
+`./gen.pl mainpage`
 
-This command outputs an nroff file, meant to become `curl.1`. The full curl
+This command outputs a single huge nroff file, meant to become `curl.1`. The
-man page.
+full curl man page.
+
+`./gen.pl listhelp`
+
+Generates a full `curl --help` output for all known command line options.

docs/cmdline-opts/cookie-jar.d

@@ -2,6 +2,7 @@ Short: c
 Long: cookie-jar
 Arg: <filename>
 Protocols: HTTP
+Help: Write cookies to <filename> after operation
 ---
 Specify to which file you want curl to write all cookies after a completed
 operation. Curl writes all cookies from its in-memory cookie storage to the

docs/cmdline-opts/cookie.d

@@ -1,7 +1,8 @@
 Short: b
 Long: cookie
-Arg: <name=data>
+Arg: <data>
 Protocols: HTTP
+Help: Send cookies from string/file
 ---
 Pass the data to the HTTP server in the Cookie header. It is supposedly
 the data previously received from the server in a "Set-Cookie:" line.  The

docs/cmdline-opts/gen.pl

@@ -8,6 +8,8 @@ closedir $dh;
 
 my %optshort;
 my %optlong;
+my %helplong;
+my %arglong;
 
 # get the long name version, return the man page string
 sub manpageify {
@@ -165,7 +167,8 @@ sub getshortlong {
     open(F, "<$f");
     my $short;
     my $long;
-
+    my $help;
+    my $arg;
     while(<F>) {
         if(/^Short: (.)/i) {
             $short=$1;
@@ -173,6 +176,12 @@ sub getshortlong {
         elsif(/^Long: (.*)/i) {
             $long=$1;
         }
+        elsif(/^Help: (.*)/i) {
+            $help=$1;
+        }
+        elsif(/^Arg: (.*)/i) {
+            $arg=$1;
+        }
         elsif(/^---/) {
             last;
         }
@@ -183,6 +192,8 @@ sub getshortlong {
     }
     if($long) {
         $optlong{$long}=$short;
+        $helplong{$long}=$help;
+        $arglong{$long}=$arg;
     }
 }
 
@@ -202,15 +213,59 @@ sub header {
     printdesc(@d);
 }
 
+sub listhelp {
+    foreach my $f (sort keys %helplong) {
+        my $long = $f;
+        my $short = $optlong{$long};
+        my $opt;
+
+        if(defined($short) && $long) {
+            $opt = "-$short, --$long";
+        }
+        elsif($long && !$short) {
+            $opt = "    --$long";
+        }
+
+        my $arg = $arglong{$long};
+        if($arg) {
+            $opt .= " $arg";
+        }
+
+        printf " %-19s %s\n", $opt, $helplong{$f};
+    }
+}
+
+sub mainpage {
+    # show the page header
+    header();
+
+    # output docs for all options
+    foreach my $f (sort @s) {
+        single($f);
+    }
+}
+
+sub getargs {
+    my $f;
+    do {
+        $f = shift @ARGV;
+        if($f eq "mainpage") {
+            mainpage();
+            return;
+        }
+        elsif($f eq "listhelp") {
+            listhelp();
+            return;
+        }
+    } while($f);
+
+    print "Usage: gen.pl <mainpage/listhelp>\n";
+}
+
 #------------------------------------------------------------------------
 
 # learn all existing options
 indexoptions();
 
-# show the page header
+getargs();
-header();
 
-# output docs for all options
-foreach my $f (sort @s) {
-    single($f);
-}

docs/cmdline-opts/http1.0.d

@@ -4,6 +4,7 @@ Tags: Versions
 Protocols: HTTP
 Added:
 Mutexed: http1.1 http2
+Help: Use HTTP 1.0
 ---
 Tells curl to use HTTP version 1.0 instead of using its internally preferred
 HTTP version.

docs/cmdline-opts/http1.1.d

@@ -4,5 +4,6 @@ Tags: Versions
 Protocols: HTTP
 Added: 7.33.0
 Mutexed: http1.0 http2
+Help: Use HTTP 1.1
 ---
 Tells curl to use HTTP version 1.1.

docs/cmdline-opts/http2-prior-knowledge.d

@@ -5,6 +5,7 @@ Protocols: HTTP
 Added: 7.49.0
 Mutexed: http1.1 http1.0 http2
 Requires: HTTP/2
+Help: Use HTTP 2 without HTTP/1.1 Upgrade
 ---
 Tells curl to issue its non-TLS HTTP requests using HTTP/2 without HTTP/1.1
 Upgrade. It requires prior knowledge that the server supports HTTP/2 straight

docs/cmdline-opts/http2.d

@@ -6,5 +6,6 @@ Added: 7.33.0
 Mutexed: http1.1 http1.0 http2-prior-knowledge
 Requires: HTTP/2
 See-also: no-alpn
+Help: Use HTTP 2
 ---
 Tells curl to use HTTP version 2.

docs/cmdline-opts/next.d

@@ -4,6 +4,7 @@ Tags:
 Protocols:
 Added: 7.36.0
 Magic: divider
+Help: Make next URL use its separate set of options
 ---
 Tells curl to use a separate operation for the following URL and associated
 options. This allows you to send several URL requests, each with their own

docs/cmdline-opts/no-alpn.d

@@ -6,6 +6,7 @@ Added: 7.36.0
 Mutexed:
 See-also: no-npn http2
 Requires: TLS
+Help: Disable the ALPN TLS extension
 ---
 Disable the ALPN TLS extension. ALPN is enabled by default if libcurl was built
 with an SSL library that supports ALPN. ALPN is used by a libcurl that supports

docs/cmdline-opts/no-npn.d

@@ -6,6 +6,7 @@ Added: 7.36.0
 Mutexed:
 See-also: no-alpn http2
 Requires: TLS
+Help: Disable the NPN TLS extension
 ---
 Disable the NPN TLS extension. NPN is enabled by default if libcurl was built
 with an SSL library that supports NPN. NPN is used by a libcurl that supports

docs/cmdline-opts/progress-bar.d

@@ -1,7 +1,6 @@
 Short: #
 Long: progress-bar
-Tags:
+Help: Disable the ALPN TLS extension
-Protocols:
 ---
 Make curl display transfer progress as a simple progress bar instead of the
 standard, more informational, meter.

docs/cmdline-opts/tlsv1.d

@@ -6,6 +6,7 @@ Added:
 Mutexed: tlsv1.1 tlsv1.2
 Requires: TLS
 See-also: http1.1 http2
+Help: Use TLSv1.0 or greater
 ---
 Forces curl to use TLS version 1.x when negotiating with a remote TLS server.
 You can use options --tlsv1.0, --tlsv1.1, --tlsv1.2, and --tlsv1.3 to control

docs/cmdline-opts/verbose.d

@@ -1,6 +1,7 @@
 Short: v
 Long: verbose
 Mutexed: trace trace-ascii
+Help: Make the operation more talkative
 ---
 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"