From b8c35f40f99cd1965d6e3152fc01071b73c3d2f1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 15 Nov 2016 09:08:50 +0100 Subject: cmdline-opts: support generating the --help output --- docs/cmdline-opts/MANPAGE.md | 13 ++++-- docs/cmdline-opts/cookie-jar.d | 1 + docs/cmdline-opts/cookie.d | 3 +- docs/cmdline-opts/gen.pl | 69 +++++++++++++++++++++++++++---- docs/cmdline-opts/http1.0.d | 1 + docs/cmdline-opts/http1.1.d | 1 + docs/cmdline-opts/http2-prior-knowledge.d | 1 + docs/cmdline-opts/http2.d | 1 + docs/cmdline-opts/next.d | 1 + docs/cmdline-opts/no-alpn.d | 1 + docs/cmdline-opts/no-npn.d | 1 + docs/cmdline-opts/progress-bar.d | 3 +- docs/cmdline-opts/tlsv1.d | 1 + docs/cmdline-opts/verbose.d | 1 + 14 files changed, 84 insertions(+), 14 deletions(-) (limited to 'docs/cmdline-opts') diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index d5077636a..f776f81f0 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/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 -man page. +This command outputs a single huge nroff file, meant to become `curl.1`. The +full curl man page. + +`./gen.pl listhelp` + +Generates a full `curl --help` output for all known command line options. diff --git a/docs/cmdline-opts/cookie-jar.d b/docs/cmdline-opts/cookie-jar.d index 50bfa61c0..da79777eb 100644 --- a/docs/cmdline-opts/cookie-jar.d +++ b/docs/cmdline-opts/cookie-jar.d @@ -2,6 +2,7 @@ Short: c Long: cookie-jar Arg: Protocols: HTTP +Help: Write cookies to 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 diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.d index f97fbdeec..383adda6e 100644 --- a/docs/cmdline-opts/cookie.d +++ b/docs/cmdline-opts/cookie.d @@ -1,7 +1,8 @@ Short: b Long: cookie -Arg: +Arg: 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 diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index ae52bfa84..9bdfa4c31 100755 --- a/docs/cmdline-opts/gen.pl +++ b/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() { 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 \n"; +} + #------------------------------------------------------------------------ # learn all existing options indexoptions(); -# show the page header -header(); +getargs(); -# output docs for all options -foreach my $f (sort @s) { - single($f); -} diff --git a/docs/cmdline-opts/http1.0.d b/docs/cmdline-opts/http1.0.d index 1bcd67d57..d9bbd76f0 100644 --- a/docs/cmdline-opts/http1.0.d +++ b/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. diff --git a/docs/cmdline-opts/http1.1.d b/docs/cmdline-opts/http1.1.d index 2ee2a4a30..fea1ada95 100644 --- a/docs/cmdline-opts/http1.1.d +++ b/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. diff --git a/docs/cmdline-opts/http2-prior-knowledge.d b/docs/cmdline-opts/http2-prior-knowledge.d index 0fb42354b..5ae95684c 100644 --- a/docs/cmdline-opts/http2-prior-knowledge.d +++ b/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 diff --git a/docs/cmdline-opts/http2.d b/docs/cmdline-opts/http2.d index ea396dbd4..4d1bb2a3f 100644 --- a/docs/cmdline-opts/http2.d +++ b/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. diff --git a/docs/cmdline-opts/next.d b/docs/cmdline-opts/next.d index b1c00ba20..f368c1b7d 100644 --- a/docs/cmdline-opts/next.d +++ b/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 diff --git a/docs/cmdline-opts/no-alpn.d b/docs/cmdline-opts/no-alpn.d index 0a94cdff4..46cd68bc0 100644 --- a/docs/cmdline-opts/no-alpn.d +++ b/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 diff --git a/docs/cmdline-opts/no-npn.d b/docs/cmdline-opts/no-npn.d index 754c79aaa..5ccfe33a9 100644 --- a/docs/cmdline-opts/no-npn.d +++ b/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 diff --git a/docs/cmdline-opts/progress-bar.d b/docs/cmdline-opts/progress-bar.d index 6f964fd6b..360690c17 100644 --- a/docs/cmdline-opts/progress-bar.d +++ b/docs/cmdline-opts/progress-bar.d @@ -1,7 +1,6 @@ Short: # Long: progress-bar -Tags: -Protocols: +Help: Disable the ALPN TLS extension --- Make curl display transfer progress as a simple progress bar instead of the standard, more informational, meter. diff --git a/docs/cmdline-opts/tlsv1.d b/docs/cmdline-opts/tlsv1.d index 7c11abca5..d96fd1cc1 100644 --- a/docs/cmdline-opts/tlsv1.d +++ b/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 diff --git a/docs/cmdline-opts/verbose.d b/docs/cmdline-opts/verbose.d index 9c8693807..640c5a782 100644 --- a/docs/cmdline-opts/verbose.d +++ b/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" -- cgit v1.2.3