docs: add categories to all cmdline opts

Adapted gen.pl with 'listcats'

This commit is a part of "--help me if you can"

Closes #5680

docs/cmdline-opts/abstract-unix-socket.d

@@ -3,6 +3,7 @@ Arg: <path>
 Help: Connect via abstract Unix domain socket
 Added: 7.53.0
 Protocols: HTTP
+Category: connection
 ---
 Connect through an abstract Unix domain socket, instead of using the network.
 Note: netstat shows the path of an abstract socket prefixed with '@', however

docs/cmdline-opts/alt-svc.d

@@ -3,6 +3,7 @@ Arg: <file name>
 Protocols: HTTPS
 Help: Enable alt-svc with this cache file
 Added: 7.64.1
+Category: http
 ---
 WARNING: this option is experimental. Do not use in production.
 

docs/cmdline-opts/anyauth.d

@@ -2,6 +2,7 @@ Long: anyauth
 Help: Pick any authentication method
 Protocols: HTTP
 See-also: proxy-anyauth basic digest
+Category: http proxy auth
 ---
 Tells curl to figure out authentication method by itself, and use the most
 secure one the remote site claims to support. This is done by first doing a

docs/cmdline-opts/append.d

@@ -2,6 +2,7 @@ Short: a
 Long: append
 Help: Append to target file when uploading
 Protocols: FTP SFTP
+Category: ftp sftp
 ---
 When used in an upload, this makes curl append to the target file instead of
 overwriting it. If the remote file doesn't exist, it will be created.  Note

docs/cmdline-opts/basic.d

@@ -2,6 +2,7 @@ Long: basic
 Help: Use HTTP Basic Authentication
 See-also: proxy-basic
 Protocols: HTTP
+Category: auth
 ---
 Tells curl to use HTTP Basic authentication with the remote host. This is the
 default and this option is usually pointless, unless you use it to override a

docs/cmdline-opts/cacert.d

@@ -2,6 +2,7 @@ Long: cacert
 Arg: <file>
 Help: CA certificate to verify peer against
 Protocols: TLS
+Category: tls
 ---
 Tells curl to use the specified certificate file to verify the peer. The file
 may contain multiple CA certificates. The certificate(s) must be in PEM

docs/cmdline-opts/capath.d

@@ -2,6 +2,7 @@ Long: capath
 Arg: <dir>
 Help: CA directory to verify peer against
 Protocols: TLS
+Category: tls
 ---
 Tells curl to use the specified certificate directory to verify the
 peer. Multiple paths can be provided by separating them with ":" (e.g.

docs/cmdline-opts/cert-status.d

@@ -2,6 +2,7 @@ Long: cert-status
 Protocols: TLS
 Added: 7.41.0
 Help: Verify the status of the server certificate
+Category: tls
 ---
 Tells curl to verify the status of the server certificate by using the
 Certificate Status Request (aka. OCSP stapling) TLS extension.

docs/cmdline-opts/cert-type.d

@@ -3,6 +3,7 @@ Protocols: TLS
 Arg: <type>
 Help: Certificate type (DER/PEM/ENG)
 See-also: cert key key-type
+Category: tls
 ---
 Tells curl what type the provided client certificate is using. PEM, DER, ENG
 and P12 are recognized types.  If not specified, PEM is assumed.

docs/cmdline-opts/cert.d

@@ -4,6 +4,7 @@ Arg: <certificate[:password]>
 Help: Client certificate file and password
 Protocols: TLS
 See-also: cert-type key key-type
+Category: tls
 ---
 Tells curl to use the specified client certificate file when getting a file
 with HTTPS, FTPS or another SSL-based protocol. The certificate must be in

docs/cmdline-opts/ciphers.d

@@ -2,6 +2,7 @@ Long: ciphers
 Arg: <list of ciphers>
 Help: SSL ciphers to use
 Protocols: TLS
+Category: tls
 ---
 Specifies which ciphers to use in the connection. The list of ciphers must
 specify valid ciphers. Read up on SSL cipher list details on this URL:

docs/cmdline-opts/compressed-ssh.d

@@ -2,6 +2,7 @@ Long: compressed-ssh
 Help: Enable SSH compression
 Protocols: SCP SFTP
 Added: 7.56.0
+Category: scp ssh
 ---
 Enables built-in SSH compression.
 This is a request, not an order; the server may or may not do it.

docs/cmdline-opts/compressed.d

@@ -1,6 +1,7 @@
 Long: compressed
 Help: Request compressed response
 Protocols: HTTP
+Category: http
 ---
 Request a compressed response using one of the algorithms curl supports, and
 automatically decompress the content. Headers are not modified.

docs/cmdline-opts/config.d

@@ -2,6 +2,7 @@ Long: config
 Arg: <file>
 Help: Read config from a file
 Short: K
+Category: curl
 ---
 
 Specify a text file to read curl arguments from. The command line arguments

docs/cmdline-opts/connect-timeout.d

@@ -2,6 +2,7 @@ Long: connect-timeout
 Arg: <seconds>
 Help: Maximum time allowed for connection
 See-also: max-time
+Category: connection
 ---
 Maximum time in seconds that you allow curl's connection to take.  This only
 limits the connection phase, so if curl connects within the given period it

docs/cmdline-opts/connect-to.d

@@ -3,6 +3,7 @@ Arg: <HOST1:PORT1:HOST2:PORT2>
 Help: Connect to host
 Added: 7.49.0
 See-also: resolve header
+Category: connection
 ---
 
 For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead.

docs/cmdline-opts/continue-at.d

@@ -3,6 +3,7 @@ Long: continue-at
 Arg: <offset>
 Help: Resumed transfer offset
 See-also: range
+Category: connection
 ---
 Continue/Resume a previous file transfer at the given offset. The given offset
 is the exact number of bytes that will be skipped, counting from the beginning

docs/cmdline-opts/cookie-jar.d

@@ -3,6 +3,7 @@ Long: cookie-jar
 Arg: <filename>
 Protocols: HTTP
 Help: Write cookies to <filename> after operation
+Category: http
 ---
 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

@@ -3,6 +3,7 @@ Long: cookie
 Arg: <data|filename>
 Protocols: HTTP
 Help: Send cookies from string/file
+Category: http
 ---
 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/create-dirs.d

@@ -1,5 +1,6 @@
 Long: create-dirs
 Help: Create necessary local directory hierarchy
+Category: curl
 ---
 When used in conjunction with the --output option, curl will create the
 necessary local directory hierarchy as needed. This option creates the dirs

docs/cmdline-opts/crlf.d

@@ -1,6 +1,7 @@
 Long: crlf
 Help: Convert LF to CRLF in upload
 Protocols: FTP SMTP
+Category: ftp smtp
 ---
 Convert LF to CRLF in upload. Useful for MVS (OS/390).
 

docs/cmdline-opts/crlfile.d

@@ -3,6 +3,7 @@ Arg: <file>
 Protocols: TLS
 Help: Get a CRL list in PEM format from the given file
 Added: 7.19.7
+Category: tls
 ---
 Provide a file using PEM format with a Certificate Revocation List that may
 specify peer certificates that are to be considered revoked.

docs/cmdline-opts/curves.d

@@ -3,6 +3,7 @@ Arg: <algorithm list>
 Help: (EC) TLS key exchange algorithm(s) to request
 Protocols: TLS
 Added: 7.73.0
+Category: tls
 ---
 Tells curl to request specific curves to use during SSL session establishment
 according to RFC 8422, 5.1.  Multiple algorithms can be provided by separating

docs/cmdline-opts/data-ascii.d

@@ -2,5 +2,6 @@ Long: data-ascii
 Arg: <data>
 Help: HTTP POST ASCII data
 Protocols: HTTP
+Category: http post upload
 ---
 This is just an alias for --data.

docs/cmdline-opts/data-binary.d

@@ -2,6 +2,7 @@ Long: data-binary
 Arg: <data>
 Help: HTTP POST binary data
 Protocols: HTTP
+Category: http post upload
 ---
 This posts data exactly as specified with no extra processing whatsoever.
 

docs/cmdline-opts/data-raw.d

@@ -4,6 +4,7 @@ Protocols: HTTP
 Help: HTTP POST data, '@' allowed
 Added: 7.43.0
 See-also: data
+Category: http post upload
 ---
 This posts data similarly to --data but without the special
 interpretation of the @ character.

docs/cmdline-opts/data-urlencode.d

@@ -4,6 +4,7 @@ Help: HTTP POST data url encoded
 Protocols: HTTP
 See-also: data data-raw
 Added: 7.18.0
+Category: http post upload
 ---
 This posts data, similar to the other --data options with the exception
 that this performs URL-encoding.

docs/cmdline-opts/data.d

@@ -5,6 +5,7 @@ Help: HTTP POST data
 Protocols: HTTP MQTT
 See-also: data-binary data-urlencode data-raw
 Mutexed: form head upload-file
+Category: important http post upload
 ---
 Sends the specified data in a POST request to the HTTP server, in the same way
 that a browser does when a user has filled in an HTML form and presses the

docs/cmdline-opts/delegation.d

@@ -2,6 +2,7 @@ Long: delegation
 Arg: <LEVEL>
 Help: GSS-API delegation permission
 Protocols: GSS/kerberos
+Category: misc
 ---
 Set LEVEL to tell the server what it is allowed to delegate when it
 comes to user credentials.

docs/cmdline-opts/digest.d

@@ -3,6 +3,7 @@ Help: Use HTTP Digest Authentication
 Protocols: HTTP
 Mutexed: basic ntlm negotiate
 See-also: user proxy-digest anyauth
+Category: proxy auth http
 ---
 Enables HTTP Digest authentication. This is an authentication scheme that
 prevents the password from being sent over the wire in clear text. Use this in

docs/cmdline-opts/disable-eprt.d

@@ -1,6 +1,7 @@
 Long: disable-eprt
 Help: Inhibit using EPRT or LPRT
 Protocols: FTP
+Category: ftp
 ---
 Tell curl to disable the use of the EPRT and LPRT commands when doing active
 FTP transfers. Curl will normally always first attempt to use EPRT, then LPRT

docs/cmdline-opts/disable-epsv.d

@@ -1,6 +1,7 @@
 Long: disable-epsv
 Help: Inhibit using EPSV
 Protocols: FTP
+Category: ftp
 ---
 (FTP) Tell curl to disable the use of the EPSV command when doing passive FTP
 transfers. Curl will normally always first attempt to use EPSV before PASV,

docs/cmdline-opts/disable.d

@@ -1,6 +1,7 @@
 Long: disable
 Short: q
 Help: Disable .curlrc
+Category: curl
 ---
 If used as the first parameter on the command line, the \fIcurlrc\fP config
 file will not be read and used. See the --config for details on the default

docs/cmdline-opts/disallow-username-in-url.d

@@ -3,5 +3,6 @@ Help: Disallow username in url
 Protocols: HTTP
 Added: 7.61.0
 See-also: proto
+Category: curl http
 ---
 This tells curl to exit if passed a url containing a username.

docs/cmdline-opts/dns-interface.d

@@ -5,6 +5,7 @@ Protocols: DNS
 See-also: dns-ipv4-addr dns-ipv6-addr
 Added: 7.33.0
 Requires: c-ares
+Category: dns
 ---
 Tell curl to send outgoing DNS requests through <interface>. This option is a
 counterpart to --interface (which does not affect DNS). The supplied string

docs/cmdline-opts/dns-ipv4-addr.d

@@ -5,6 +5,7 @@ Protocols: DNS
 See-also: dns-interface dns-ipv6-addr
 Added: 7.33.0
 Requires: c-ares
+Category: dns
 ---
 Tell curl to bind to <ip-address> when making IPv4 DNS requests, so that
 the DNS requests originate from this address. The argument should be a

docs/cmdline-opts/dns-ipv6-addr.d

@@ -5,6 +5,7 @@ Protocols: DNS
 See-also: dns-interface dns-ipv4-addr
 Added: 7.33.0
 Requires: c-ares
+Category: dns
 ---
 Tell curl to bind to <ip-address> when making IPv6 DNS requests, so that
 the DNS requests originate from this address. The argument should be a

docs/cmdline-opts/dns-servers.d

@@ -3,6 +3,7 @@ Arg: <addresses>
 Help: DNS server addrs to use
 Requires: c-ares
 Added: 7.33.0
+Category: dns
 ---
 Set the list of DNS servers to be used instead of the system default.
 The list of IP addresses should be separated with commas. Port numbers

docs/cmdline-opts/doh-url.d

@@ -3,6 +3,7 @@ Arg: <URL>
 Help: Resolve host names over DOH
 Protocols: all
 Added: 7.62.0
+Category: dns
 ---
 Specifies which DNS-over-HTTPS (DOH) server to use to resolve hostnames,
 instead of using the default name resolver mechanism. The URL must be HTTPS.

docs/cmdline-opts/dump-header.d

@@ -4,6 +4,7 @@ Arg: <filename>
 Help: Write the received headers to <filename>
 Protocols: HTTP FTP
 See-also: output
+Category: http ftp
 ---
 Write the received protocol headers to the specified file.
 

docs/cmdline-opts/egd-file.d

@@ -3,6 +3,7 @@ Arg: <file>
 Help: EGD socket path for random data
 Protocols: TLS
 See-also: random-file
+Category: tls
 ---
 Specify the path name to the Entropy Gathering Daemon socket. The socket is
 used to seed the random engine for SSL connections.

docs/cmdline-opts/engine.d

@@ -2,6 +2,7 @@ Long: engine
 Arg: <name>
 Help: Crypto engine to use
 Protocols: TLS
+Category: tls
 ---
 Select the OpenSSL crypto engine to use for cipher operations. Use --engine
 list to print a list of build-time supported engines. Note that not all (or

docs/cmdline-opts/etag-compare.d

@@ -3,6 +3,7 @@ Arg: <file>
 Help: Pass an ETag from a file as a custom header
 Protocols: HTTP
 Added: 7.68.0
+Category: http
 ---
 This option makes a conditional HTTP request for the specific
 ETag read from the given file by sending a custom If-None-Match

docs/cmdline-opts/etag-save.d

@@ -3,6 +3,7 @@ Arg: <file>
 Help: Parse ETag from a request and save it to a file
 Protocols: HTTP
 Added: 7.68.0
+Category: http
 ---
 This option saves an HTTP ETag to the specified file. Etag is
 usually part of headers returned by a request. When server sends an

docs/cmdline-opts/expect100-timeout.d

@@ -4,6 +4,7 @@ Help: How long to wait for 100-continue
 Protocols: HTTP
 Added: 7.47.0
 See-also: connect-timeout
+Category: http
 ---
 Maximum time in seconds that you allow curl to wait for a 100-continue
 response when curl emits an Expects: 100-continue header in its request. By

docs/cmdline-opts/fail-early.d

@@ -1,6 +1,7 @@
 Long: fail-early
 Help: Fail on first transfer error, do not continue
 Added: 7.52.0
+Category: curl
 ---
 Fail and exit on the first detected transfer error.
 

docs/cmdline-opts/fail.d

@@ -2,6 +2,7 @@ Long: fail
 Short: f
 Protocols: HTTP
 Help: Fail silently (no output at all) on HTTP errors
+Category: important http
 ---
 Fail silently (no output at all) on server errors. This is mostly done to
 better enable scripts etc to better deal with failed attempts. In normal cases

docs/cmdline-opts/false-start.d

@@ -2,6 +2,7 @@ Long: false-start
 Help: Enable TLS False Start
 Protocols: TLS
 Added: 7.42.0
+Category: tls
 ---
 Tells curl to use false start during the TLS handshake. False start is a mode
 where a TLS client will start sending application data before verifying the

docs/cmdline-opts/form-string.d

@@ -3,6 +3,7 @@ Help: Specify multipart MIME data
 Protocols: HTTP SMTP IMAP
 Arg: <name=string>
 See-also: form
+Category: http upload
 ---
 Similar to --form except that the value string for the named parameter is used
 literally. Leading \&'@' and \&'<' characters, and the \&';type=' string in

docs/cmdline-opts/form.d

@@ -4,6 +4,7 @@ Arg: <name=content>
 Help: Specify multipart MIME data
 Protocols: HTTP SMTP IMAP
 Mutexed: data head upload-file
+Category: http upload
 ---
 For HTTP protocol family, this lets curl emulate a filled-in form in which a
 user has pressed the submit button. This causes curl to POST data using the

docs/cmdline-opts/ftp-account.d

@@ -3,6 +3,7 @@ Arg: <data>
 Help: Account data string
 Protocols: FTP
 Added: 7.13.0
+Category: ftp auth
 ---
 When an FTP server asks for "account data" after user name and password has
 been provided, this data is sent off using the ACCT command.

docs/cmdline-opts/ftp-alternative-to-user.d

@@ -3,6 +3,7 @@ Arg: <command>
 Help: String to replace USER [name]
 Protocols: FTP
 Added: 7.15.5
+Category: ftp
 ---
 If authenticating with the USER and PASS commands fails, send this command.
 When connecting to Tumbleweed's Secure Transport server over FTPS using a

docs/cmdline-opts/ftp-create-dirs.d

@@ -2,6 +2,7 @@ Long: ftp-create-dirs
 Protocols: FTP SFTP
 Help: Create the remote dirs if not present
 See-also: create-dirs
+Category: ftp sftp curl
 ---
 When an FTP or SFTP URL/operation uses a path that doesn't currently exist on
 the server, the standard behavior of curl is to fail. Using this option, curl

docs/cmdline-opts/ftp-method.d

@@ -3,6 +3,7 @@ Arg: <method>
 Help: Control CWD usage
 Protocols: FTP
 Added: 7.15.1
+Category: ftp
 ---
 Control what method curl should use to reach a file on an FTP(S)
 server. The method argument should be one of the following alternatives:

docs/cmdline-opts/ftp-pasv.d

@@ -3,6 +3,7 @@ Help: Use PASV/EPSV instead of PORT
 Protocols: FTP
 Added: 7.11.0
 See-also: disable-epsv
+Category: ftp
 ---
 Use passive mode for the data connection. Passive is the internal default
 behavior, but using this option can be used to override a previous --ftp-port

docs/cmdline-opts/ftp-port.d

@@ -4,6 +4,7 @@ Help: Use PORT instead of PASV
 Short: P
 Protocols: FTP
 See-also: ftp-pasv disable-eprt
+Category: ftp
 ---
 Reverses the default initiator/listener roles when connecting with FTP. This
 option makes curl use active mode. curl then tells the server to connect back

docs/cmdline-opts/ftp-pret.d

@@ -2,6 +2,7 @@ Long: ftp-pret
 Help: Send PRET before PASV
 Protocols: FTP
 Added: 7.20.0
+Category: ftp
 ---
 Tell curl to send a PRET command before PASV (and EPSV). Certain FTP servers,
 mainly drftpd, require this non-standard command for directory listings as

docs/cmdline-opts/ftp-skip-pasv-ip.d

@@ -3,6 +3,7 @@ Help: Skip the IP address for PASV
 Protocols: FTP
 Added: 7.14.2
 See-also: ftp-pasv
+Category: ftp
 ---
 Tell curl to not use the IP address the server suggests in its response
 to curl's PASV command when curl connects the data connection. Instead curl

docs/cmdline-opts/ftp-ssl-ccc-mode.d

@@ -4,6 +4,7 @@ Help: Set CCC mode
 Protocols: FTP
 Added: 7.16.2
 See-also: ftp-ssl-ccc
+Category: ftp tls
 ---
 Sets the CCC mode. The passive mode will not initiate the shutdown, but
 instead wait for the server to do it, and will not reply to the shutdown from

docs/cmdline-opts/ftp-ssl-ccc.d

@@ -3,6 +3,7 @@ Help: Send CCC after authenticating
 Protocols: FTP
 See-also: ssl ftp-ssl-ccc-mode
 Added: 7.16.1
+Category: ftp tls
 ---
 Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after
 authenticating. The rest of the control channel communication will be

docs/cmdline-opts/ftp-ssl-control.d

@@ -2,6 +2,7 @@ Long: ftp-ssl-control
 Help: Require SSL/TLS for FTP login, clear for transfer
 Protocols: FTP
 Added: 7.16.0
+Category: ftp tls
 ---
 Require SSL/TLS for the FTP login, clear for transfer.  Allows secure
 authentication, but non-encrypted data transfers for efficiency.  Fails the

docs/cmdline-opts/gen.pl

@@ -43,6 +43,7 @@ my %helplong;
 my %arglong;
 my %redirlong;
 my %protolong;
+my %catlong;
 
 # get the long name version, return the man page string
 sub manpageify {
@@ -126,6 +127,7 @@ sub single {
     my $arg;
     my $mutexed;
     my $requires;
+    my $category;
     my $seealso;
     my $magic; # cmdline special option
     while(<F>) {
@@ -159,6 +161,9 @@ sub single {
         elsif(/^Requires: *(.*)/i) {
             $requires=$1;
         }
+        elsif(/^Category: *(.*)/i) {
+            $category=$1;
+        }
         elsif(/^Help: *(.*)/i) {
             ;
         }
@@ -166,6 +171,9 @@ sub single {
             if(!$long) {
                 print STDERR "WARN: no 'Long:' in $f\n";
             }
+            if(!$category) {
+                print STDERR "WARN: no 'Category:' in $f\n";
+            }
             last;
         }
         else {
@@ -274,6 +282,7 @@ sub getshortlong {
     my $help;
     my $arg;
     my $protocols;
+    my $category;
     while(<F>) {
         if(/^Short: (.)/i) {
             $short=$1;
@@ -290,6 +299,9 @@ sub getshortlong {
         elsif(/^Protocols: (.*)/i) {
             $protocols=$1;
         }
+        elsif(/^Category: (.*)/i) {
+            $category=$1;
+        }
         elsif(/^---/) {
             last;
         }
@@ -303,6 +315,7 @@ sub getshortlong {
         $helplong{$long}=$help;
         $arglong{$long}=$arg;
         $protolong{$long}=$protocols;
+        $catlong{$long}=$category;
     }
 }
 
@@ -328,6 +341,8 @@ sub listhelp {
     foreach my $f (sort keys %helplong) {
         my $long = $f;
         my $short = $optlong{$long};
+        my @categories = split ' ', $catlong{$long};
+        my $bitmask;
         my $opt;
 
         if(defined($short) && $long) {
@@ -336,7 +351,13 @@ sub listhelp {
         elsif($long && !$short) {
             $opt = "    --$long";
         }
-
+        for my $i (0 .. $#categories) {
+            $bitmask .= 'CURLHELP_' . uc $categories[$i];
+            # If not last element, append |
+            if($i < $#categories) {
+                $bitmask .= ' | ';
+            }
+        }
         my $arg = $arglong{$long};
         if($arg) {
             $opt .= " $arg";
@@ -344,7 +365,7 @@ sub listhelp {
         my $desc = $helplong{$f};
         $desc =~ s/\"/\\\"/g; # escape double quotes
 
-        my $line = sprintf "  {\"%s\",\n   \"%s\"},\n", $opt, $desc;
+        my $line = sprintf "  {\"%s\",\n   \"%s\",\n   %s},\n", $opt, $desc, $bitmask;
 
         if(length($opt) + length($desc) > 78) {
             print STDERR "WARN: the --$long line is too long\n";
@@ -353,6 +374,25 @@ sub listhelp {
     }
 }
 
+sub listcats {
+    my %allcats;
+    foreach my $f (sort keys %helplong) {
+        my @categories = split ' ', $catlong{$f};
+        foreach (@categories) {
+            $allcats{$_} = undef;
+        }
+    }
+    my @categories;
+    foreach my $key (keys %allcats) {
+        push @categories, $key;
+    }
+    @categories = sort @categories;
+    unshift @categories, 'hidden';
+    for my $i (0..$#categories) {
+        print '#define ' . 'CURLHELP_' . uc($categories[$i]) . ' ' . "1u << " . $i . "u\n";
+    }
+}
+
 sub mainpage {
     my (@files) = @_;
     # show the page header
@@ -406,8 +446,12 @@ sub getargs {
         showprotocols();
         return;
     }
+    elsif($f eq "listcats") {
+        listcats();
+        return;
+    }
 
-    print "Usage: gen.pl <mainpage/listhelp/single FILE/protos> [files]\n";
+    print "Usage: gen.pl <mainpage/listhelp/single FILE/protos/listcats> [files]\n";
 }
 
 #------------------------------------------------------------------------

docs/cmdline-opts/get.d

@@ -1,6 +1,7 @@
 Long: get
 Short: G
 Help: Put the post data in the URL and use GET
+Category: http upload
 ---
 When used, this option will make all data specified with --data, --data-binary
 or --data-urlencode to be used in an HTTP GET request instead of the POST

docs/cmdline-opts/globoff.d

@@ -1,6 +1,7 @@
 Long: globoff
 Short: g
 Help: Disable URL sequences and ranges using {} and []
+Category: curl
 ---
 This option switches off the "URL globbing parser". When you set this option,
 you can specify URLs that contain the letters {}[] without having them being

docs/cmdline-opts/happy-eyeballs-timeout-ms.d

@@ -2,6 +2,7 @@ Long: happy-eyeballs-timeout-ms
 Arg: <milliseconds>
 Help: Time for IPv6 before trying IPv4
 Added: 7.59.0
+Category: connection
 ---
 Happy eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6
 addresses for dual-stack hosts, preferring IPv6 first for the number of

docs/cmdline-opts/haproxy-protocol.d

@@ -2,6 +2,7 @@ Long: haproxy-protocol
 Help: Send HAProxy PROXY protocol v1 header
 Protocols: HTTP
 Added: 7.60.0
+Category: http proxy
 ---
 Send a HAProxy PROXY protocol v1 header at the beginning of the connection. This
 is used by some load balancers and reverse proxies to indicate the client's

docs/cmdline-opts/head.d

@@ -2,6 +2,7 @@ Long: head
 Short: I
 Help: Show document info only
 Protocols: HTTP FTP FILE
+Category: http ftp file
 ---
 Fetch the headers only! HTTP-servers feature the command HEAD which this uses
 to get nothing but the header of a document. When used on an FTP or FILE file,

docs/cmdline-opts/header.d

@@ -3,6 +3,7 @@ Short: H
 Arg: <header/@file>
 Help: Pass custom header(s) to server
 Protocols: HTTP
+Category: http
 ---
 Extra header to include in the request when sending HTTP to a server. You may
 specify any number of extra headers. Note that if you should add a custom

docs/cmdline-opts/help.d

@@ -1,6 +1,12 @@
 Long: help
+Arg: <category>
 Short: h
-Help: This help text
+Help: Get help for commands
+Category: important curl
 ---
-Usage help. This lists all current command line options with a short
-description.
+Usage help. This lists all commands of the <category>.
+If no arg was provided, curl will display the most important
+command line arguments and the list of categories.
+If the argument "all" was provided, curl will display all options available.
+If the argument "category" was provided, curl will display all categories and
+their meanings.

docs/cmdline-opts/hostpubmd5.d

@@ -3,6 +3,7 @@ Arg: <md5>
 Help: Acceptable MD5 hash of the host public key
 Protocols: SFTP SCP
 Added: 7.17.1
+Category: sftp scp
 ---
 Pass a string containing 32 hexadecimal digits. The string should
 be the 128 bit MD5 checksum of the remote host's public key, curl will refuse

docs/cmdline-opts/http0.9.d

@@ -3,6 +3,7 @@ Tags: Versions
 Protocols: HTTP
 Added:
 Help: Allow HTTP 0.9 responses
+Category: http
 ---
 Tells curl to be fine with HTTP version 0.9 response.
 

docs/cmdline-opts/http1.0.d

@@ -5,6 +5,7 @@ Protocols: HTTP
 Added:
 Mutexed: http1.1 http2
 Help: Use HTTP 1.0
+Category: http
 ---
 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 @@ Protocols: HTTP
 Added: 7.33.0
 Mutexed: http1.0 http2
 Help: Use HTTP 1.1
+Category: http
 ---
 Tells curl to use HTTP version 1.1.

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

@@ -5,6 +5,7 @@ Added: 7.49.0
 Mutexed: http1.1 http1.0 http2
 Requires: HTTP/2
 Help: Use HTTP 2 without HTTP/1.1 Upgrade
+Category: http
 ---
 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

@@ -7,5 +7,6 @@ Requires: HTTP/2
 See-also: no-alpn
 Help: Use HTTP 2
 See-also: http1.1 http3
+Category: http
 ---
 Tells curl to use HTTP version 2.

docs/cmdline-opts/http3.d

@@ -6,6 +6,7 @@ Mutexed: http1.1 http1.0 http2 http2-prior-knowledge
 Requires: HTTP/3
 Help: Use HTTP v3
 See-also: http1.1 http2
+Category: http
 ---
 
 WARNING: this option is experimental. Do not use in production.

docs/cmdline-opts/ignore-content-length.d

@@ -1,6 +1,7 @@
 Long: ignore-content-length
 Help: Ignore the size of the remote resource
 Protocols: FTP HTTP
+Category: http ftp
 ---
 For HTTP, Ignore the Content-Length header. This is particularly useful for
 servers running Apache 1.x, which will report incorrect Content-Length for

docs/cmdline-opts/include.d

@@ -2,6 +2,7 @@ Long: include
 Short: i
 Help: Include protocol response headers in the output
 See-also: verbose
+Category: important verbose
 ---
 Include the HTTP response headers in the output. The HTTP response headers can
 include things like server name, cookies, date of the document, HTTP version

docs/cmdline-opts/insecure.d

@@ -3,6 +3,7 @@ Short: k
 Help: Allow insecure server connections when using SSL
 Protocols: TLS
 See-also: proxy-insecure cacert
+Category: tls
 ---
 
 By default, every SSL connection curl makes is verified to be secure. This

docs/cmdline-opts/interface.d

@@ -2,6 +2,7 @@ Long: interface
 Arg: <name>
 Help: Use network INTERFACE (or address)
 See-also: dns-interface
+Category: connection
 ---
 
 Perform an operation using a specified interface. You can enter interface

docs/cmdline-opts/ipv4.d

@@ -7,6 +7,7 @@ Mutexed: ipv6
 Requires:
 See-also: http1.1 http2
 Help: Resolve names to IPv4 addresses
+Category: connection dns
 ---
 This option tells curl to resolve names to IPv4 addresses only, and not for
 example try IPv6.

docs/cmdline-opts/ipv6.d

@@ -7,6 +7,7 @@ Mutexed: ipv4
 Requires:
 See-also: http1.1 http2
 Help: Resolve names to IPv6 addresses
+Category: connection dns
 ---
 This option tells curl to resolve names to IPv6 addresses only, and not for
 example try IPv4.

docs/cmdline-opts/junk-session-cookies.d

@@ -3,6 +3,7 @@ Short: j
 Help: Ignore session cookies read from file
 Protocols: HTTP
 See-also: cookie cookie-jar
+Category: http
 ---
 When curl is told to read cookies from a given file, this option will make it
 discard all "session cookies". This will basically have the same effect as if

docs/cmdline-opts/keepalive-time.d

@@ -2,6 +2,7 @@ Long: keepalive-time
 Arg: <seconds>
 Help: Interval time for keepalive probes
 Added: 7.18.0
+Category: connection
 ---
 This option sets the time a connection needs to remain idle before sending
 keepalive probes and the time between individual keepalive probes. It is

docs/cmdline-opts/key-type.d

@@ -2,6 +2,7 @@ Long: key-type
 Arg: <type>
 Help: Private key file type (DER/PEM/ENG)
 Protocols: TLS
+Category: tls
 ---
 Private key file type. Specify which type your --key provided private key
 is. DER, PEM, and ENG are supported. If not specified, PEM is assumed.

docs/cmdline-opts/key.d

@@ -2,6 +2,7 @@ Long: key
 Arg: <key>
 Protocols: TLS SSH
 Help: Private key file name
+Category: tls ssh
 ---
 Private key file name. Allows you to provide your private key in this separate
 file. For SSH, if not specified, curl tries the following candidates in order:

docs/cmdline-opts/krb.d

@@ -3,6 +3,7 @@ Arg: <level>
 Help: Enable Kerberos with security <level>
 Protocols: FTP
 Requires: Kerberos
+Category: ftp
 ---
 Enable Kerberos authentication and use. The level must be entered and should
 be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a

docs/cmdline-opts/libcurl.d

@@ -2,6 +2,7 @@ Long: libcurl
 Arg: <file>
 Help: Dump libcurl equivalent code of this command line
 Added: 7.16.1
+Category: curl
 ---
 Append this option to any ordinary curl command line, and you will get a
 libcurl-using C source code written to the file that does the equivalent

docs/cmdline-opts/limit-rate.d

@@ -1,6 +1,7 @@
 Long: limit-rate
 Arg: <speed>
 Help: Limit transfer speed to RATE
+Category: connection
 ---
 Specify the maximum transfer rate you want curl to use - for both downloads
 and uploads. This feature is useful if you have a limited pipe and you'd like

docs/cmdline-opts/list-only.d

@@ -3,6 +3,7 @@ Short: l
 Protocols: FTP POP3
 Help: List only mode
 Added: 4.0
+Category: ftp pop3
 ---
 (FTP)
 When listing an FTP directory, this switch forces a name-only view. This is

docs/cmdline-opts/local-port.d

@@ -2,6 +2,7 @@ Long: local-port
 Arg: <num/range>
 Help: Force use of RANGE for local port numbers
 Added: 7.15.2
+Category: connection
 ---
 Set a preferred single number or range (FROM-TO) of local port numbers to use
 for the connection(s).  Note that port numbers by nature are a scarce resource

docs/cmdline-opts/location-trusted.d

@@ -2,6 +2,7 @@ Long: location-trusted
 Help: Like --location, and send auth to other hosts
 Protocols: HTTP
 See-also: user
+Category: http auth
 ---
 Like --location, but will allow sending the name + password to all hosts that
 the site may redirect to. This may or may not introduce a security breach if

docs/cmdline-opts/location.d

@@ -2,6 +2,7 @@ Long: location
 Short: L
 Help: Follow redirects
 Protocols: HTTP
+Category: http
 ---
 If the server reports that the requested page has moved to a different
 location (indicated with a Location: header and a 3XX response code), this

docs/cmdline-opts/login-options.d

@@ -3,6 +3,7 @@ Arg: <options>
 Protocols: IMAP POP3 SMTP
 Help: Server login options
 Added: 7.34.0
+Category: imap pop3 smtp auth
 ---
 Specify the login options to use during server authentication.
 

docs/cmdline-opts/mail-auth.d

@@ -4,6 +4,7 @@ Protocols: SMTP
 Help: Originator address of the original email
 Added: 7.25.0
 See-also: mail-rcpt mail-from
+Category: smtp
 ---
 Specify a single address. This will be used to specify the authentication
 address (identity) of a submitted message that is being relayed to another

docs/cmdline-opts/mail-from.d

@@ -4,5 +4,6 @@ Help: Mail from this address
 Protocols: SMTP
 Added: 7.20.0
 See-also: mail-rcpt mail-auth
+Category: smtp
 ---
 Specify a single address that the given mail should get sent from.

docs/cmdline-opts/mail-rcpt-allowfails.d

@@ -2,6 +2,7 @@ Long: mail-rcpt-allowfails
 Help: Allow RCPT TO command to fail for some recipients
 Protocols: SMTP
 Added: 7.69.0
+Category: smtp
 ---
 When sending data to multiple recipients, by default curl will abort SMTP
 conversation if at least one of the recipients causes RCPT TO command to

docs/cmdline-opts/mail-rcpt.d

@@ -3,6 +3,7 @@ Arg: <address>
 Help: Mail to this address
 Protocols: SMTP
 Added: 7.20.0
+Category: smtp
 ---
 Specify a single address, user name or mailing list name. Repeat this
 option several times to send to multiple recipients.

docs/cmdline-opts/manual.d

@@ -1,5 +1,6 @@
 Long: manual
 Short: M
 Help: Display the full manual
+Category: curl
 ---
 Manual. Display the huge help text.

docs/cmdline-opts/max-filesize.d

@@ -2,6 +2,7 @@ Long: max-filesize
 Arg: <bytes>
 Help: Maximum file size to download
 See-also: limit-rate
+Category: connection
 ---
 Specify the maximum size (in bytes) of a file to download. If the file
 requested is larger than this value, the transfer will not start and curl will