curl: help category cleanups

- add 'mqtt' as a category
- add more protocol categories to several options
- make --data worded better to also cover MQTT

Closes #22447

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

@@ -6,7 +6,7 @@ Arg: <path>
 Help: Connect via abstract Unix domain socket
 Added: 7.53.0
 Protocols: HTTP
-Category: connection
+Category: connection http
 Multi: single
 See-also:
   - unix-socket

docs/cmdline-opts/basic.md

@@ -4,7 +4,7 @@ SPDX-License-Identifier: curl
 Long: basic
 Help: HTTP Basic Authentication
 Protocols: HTTP
-Category: auth
+Category: auth http
 Added: 7.10.6
 Multi: boolean
 See-also:

docs/cmdline-opts/compressed-ssh.md

@@ -5,7 +5,7 @@ Long: compressed-ssh
 Help: Enable SSH compression
 Protocols: SCP SFTP
 Added: 7.56.0
-Category: scp ssh
+Category: scp sftp ssh
 Multi: boolean
 See-also:
   - compressed

docs/cmdline-opts/data.md

@@ -4,16 +4,17 @@ SPDX-License-Identifier: curl
 Long: data
 Short: d
 Arg: <data>
-Help: HTTP POST data
+Help: Post data
 Protocols: HTTP MQTT
 Mutexed: form head upload-file
-Category: important http post upload
+Category: important http post upload mqtt
 Added: 4.0
 Multi: append
 See-also:
   - data-binary
   - data-urlencode
   - data-raw
+  - form
 Example:
   - -d "name=curl" $URL
   - -d "name=curl" -d "tool=cmdline" $URL
@@ -22,10 +23,14 @@ Example:
 
 # `--data`
 
-Send the specified data in a POST request to the HTTP server, in the same way
+Send the specified data to a server.
-that a browser does when a user has filled in an HTML form and presses the
+
-submit button. This option makes curl pass the data to the server using the
+For HTTP(S), this is done with the POST method in the same way that a browser
-content-type application/x-www-form-urlencoded. Compared to --form.
+does when a user has filled in an HTML form and presses the submit button.
+This option makes curl pass the data to the server using the content-type
+application/x-www-form-urlencoded.
+
+For MQTT, the data is sent as a PUBLISH.
 
 --data-raw is almost the same but does not have a special interpretation of
 the @ character. To post data purely binary, you should instead use the

docs/cmdline-opts/form-escape.md

@@ -5,7 +5,7 @@ Long: form-escape
 Help: Escape form fields using backslash
 Protocols: HTTP IMAP SMTP
 Added: 7.81.0
-Category: http upload post
+Category: http upload post imap smtp
 Multi: single
 See-also:
   - form

docs/cmdline-opts/key.md

@@ -5,7 +5,7 @@ Long: key
 Arg: <key>
 Protocols: TLS SCP SFTP
 Help: Private key filename
-Category: tls ssh
+Category: tls sftp scp ssh
 Added: 7.9.3
 Multi: single
 See-also:

docs/cmdline-opts/knownhosts.md

@@ -5,7 +5,7 @@ Long: knownhosts
 Arg: <file>
 Protocols: SCP SFTP
 Help: Specify knownhosts path
-Category: ssh
+Category: sftp scp ssh
 Added: 8.17.0
 Multi: single
 See-also:

docs/cmdline-opts/max-filesize.md

@@ -5,7 +5,7 @@ Long: max-filesize
 Arg: <bytes>
 Help: Maximum file size to download
 Protocols: FTP HTTP MQTT
-Category: connection
+Category: connection ftp http mqtt
 Added: 7.10.8
 Multi: single
 See-also:

docs/cmdline-opts/oauth2-bearer.md

@@ -5,7 +5,7 @@ Long: oauth2-bearer
 Help: OAuth 2 Bearer Token
 Arg: <token>
 Protocols: IMAP LDAP POP3 SMTP HTTP
-Category: auth imap pop3 smtp ldap
+Category: auth imap pop3 smtp ldap http
 Added: 7.33.0
 Multi: single
 See-also:

docs/cmdline-opts/pass.md

@@ -5,7 +5,7 @@ Long: pass
 Arg: <phrase>
 Help: Passphrase for the private key
 Protocols: TLS SCP SFTP
-Category: ssh tls auth
+Category: tls sftp scp ssh auth
 Added: 7.9.3
 Multi: single
 See-also:

docs/cmdline-opts/proxy-header.md

@@ -6,7 +6,7 @@ Arg: <header/@file>
 Help: Pass custom header(s) to proxy
 Protocols: HTTP
 Added: 7.37.0
-Category: proxy
+Category: proxy http
 Multi: append
 See-also:
   - proxy

docs/cmdline-opts/remote-header-name.md

@@ -5,7 +5,7 @@ Long: remote-header-name
 Short: J
 Protocols: HTTP
 Help: Use the header-provided filename
-Category: output
+Category: output http
 Added: 7.20.0
 Multi: boolean
 See-also:

docs/cmdline-opts/sasl-authzid.md

@@ -6,7 +6,7 @@ Arg: <identity>
 Help: Identity for SASL PLAIN authentication
 Protocols: LDAP IMAP POP3 SMTP
 Added: 7.66.0
-Category: auth
+Category: auth imap smtp pop3 ldap
 Multi: single
 See-also:
   - login-options

docs/cmdline-opts/sasl-ir.md

@@ -5,7 +5,7 @@ Long: sasl-ir
 Help: Initial response in SASL authentication
 Protocols: LDAP IMAP POP3 SMTP
 Added: 7.31.0
-Category: auth
+Category: auth imap pop3 ldap smtp
 Multi: boolean
 See-also:
   - sasl-authzid

docs/cmdline-opts/show-headers.md

@@ -5,7 +5,7 @@ Long: show-headers
 Short: i
 Help: Show response headers in output
 Protocols: HTTP FTP
-Category: important verbose output
+Category: important verbose output http ftp
 Added: 4.8
 Multi: boolean
 See-also:

docs/cmdline-opts/ssl-reqd.md

@@ -5,7 +5,7 @@ Long: ssl-reqd
 Help: Require SSL/TLS
 Protocols: FTP IMAP POP3 SMTP LDAP
 Added: 7.20.0
-Category: tls imap pop3 smtp ldap
+Category: tls imap pop3 smtp ldap ftp
 Multi: boolean
 See-also:
   - ssl

docs/cmdline-opts/ssl.md

@@ -5,7 +5,7 @@ Long: ssl
 Help: Try enabling TLS
 Protocols: FTP IMAP POP3 SMTP LDAP
 Added: 7.20.0
-Category: tls imap pop3 smtp ldap
+Category: tls imap pop3 smtp ldap ftp
 Multi: boolean
 See-also:
   - ssl-reqd

docs/cmdline-opts/unix-socket.md

@@ -6,7 +6,7 @@ Arg: <path>
 Help: Connect through this Unix domain socket
 Added: 7.40.0
 Protocols: HTTP
-Category: connection
+Category: connection http
 Multi: single
 See-also:
   - abstract-unix-socket

docs/cmdline-opts/upload-file.md

@@ -5,7 +5,7 @@ Long: upload-file
 Short: T
 Arg: <file>
 Help: Transfer local FILE to destination
-Category: important upload
+Category: important upload imap
 Added: 4.0
 Multi: per-URL
 See-also:

docs/cmdline-opts/upload-flags.md

@@ -5,7 +5,7 @@ Long: upload-flags
 Arg: <flags>
 Help: IMAP upload behavior
 Protocols: IMAP
-Category: curl output
+Category: curl output imap upload
 Added: 8.13.0
 Multi: single
 See-also:

scripts/managen

@@ -1127,7 +1127,7 @@ HEAD
                 $bitmask .= ' | ';
             }
         }
-        $bitmask =~ s/(?=.{76}).{1,76}\|/$&\n   /g;
+        $bitmask =~ s/(?=.{75}).{1,75}\|/$&\n   /g;
         my $arg = $arglong{$long};
         if($arg) {
             $opt .= " $arg";

src/tool_help.c

@@ -51,6 +51,7 @@ static const struct category_descriptors categories[] = {
   { "http", "HTTP and HTTPS protocol", CURLHELP_HTTP },
   { "imap", "IMAP protocol", CURLHELP_IMAP },
   { "ldap", "LDAP protocol", CURLHELP_LDAP },
+  { "mqtt", "MQTT protocol", CURLHELP_MQTT },
   { "output", "File system output", CURLHELP_OUTPUT },
   { "pop3", "POP3 protocol", CURLHELP_POP3 },
   { "post", "HTTP POST specific", CURLHELP_POST },

src/tool_help.h

@@ -85,6 +85,7 @@ struct helptxt {
 #define CURLHELP_TLS        (1 << 23)
 #define CURLHELP_UPLOAD     (1 << 24)
 #define CURLHELP_VERBOSE    (1 << 25)
+#define CURLHELP_MQTT       (1 << 26)
 
 #define CURLHELP_ALL        0xfffffffU
 

src/tool_listhelp.c

@@ -36,7 +36,7 @@
 const struct helptxt helptext[] = {
   { "    --abstract-unix-socket <path>",
     "Connect via abstract Unix domain socket",
-    CURLHELP_CONNECTION },
+    CURLHELP_CONNECTION | CURLHELP_HTTP },
   { "    --alt-svc <filename>",
     "Enable alt-svc with this cache file",
     CURLHELP_HTTP },
@@ -51,7 +51,7 @@ const struct helptxt helptext[] = {
     CURLHELP_AUTH | CURLHELP_HTTP },
   { "    --basic",
     "HTTP Basic Authentication",
-    CURLHELP_AUTH },
+    CURLHELP_AUTH | CURLHELP_HTTP },
   { "    --ca-native",
     "Load CA certs from the OS",
     CURLHELP_TLS },
@@ -78,7 +78,7 @@ const struct helptxt helptext[] = {
     CURLHELP_HTTP },
   { "    --compressed-ssh",
     "Enable SSH compression",
-    CURLHELP_SCP | CURLHELP_SSH },
+    CURLHELP_SCP | CURLHELP_SFTP | CURLHELP_SSH },
   { "-K, --config <file>",
     "Read config from a file",
     CURLHELP_CURL },
@@ -113,8 +113,9 @@ const struct helptxt helptext[] = {
     "(EC) TLS key exchange algorithms to request",
     CURLHELP_TLS },
   { "-d, --data <data>",
-    "HTTP POST data",
+    "Post data",
-    CURLHELP_IMPORTANT | CURLHELP_HTTP | CURLHELP_POST | CURLHELP_UPLOAD },
+    CURLHELP_IMPORTANT | CURLHELP_HTTP | CURLHELP_POST | CURLHELP_UPLOAD |
+    CURLHELP_MQTT },
   { "    --data-ascii <data>",
     "HTTP POST ASCII data",
     CURLHELP_HTTP | CURLHELP_POST | CURLHELP_UPLOAD },
@@ -211,7 +212,8 @@ const struct helptxt helptext[] = {
     CURLHELP_SMTP },
   { "    --form-escape",
     "Escape form fields using backslash",
-    CURLHELP_HTTP | CURLHELP_UPLOAD | CURLHELP_POST },
+    CURLHELP_HTTP | CURLHELP_UPLOAD | CURLHELP_POST | CURLHELP_IMAP |
+    CURLHELP_SMTP },
   { "    --form-string <name=string>",
     "Specify multipart MIME data",
     CURLHELP_HTTP | CURLHELP_UPLOAD | CURLHELP_POST | CURLHELP_SMTP |
@@ -360,13 +362,13 @@ const struct helptxt helptext[] = {
     CURLHELP_CONNECTION | CURLHELP_TIMEOUT },
   { "    --key <key>",
     "Private key filename",
-    CURLHELP_TLS | CURLHELP_SSH },
+    CURLHELP_TLS | CURLHELP_SFTP | CURLHELP_SCP | CURLHELP_SSH },
   { "    --key-type <type>",
     "Private key file type (DER/PEM/ENG)",
     CURLHELP_TLS },
   { "    --knownhosts <file>",
     "Specify knownhosts path",
-    CURLHELP_SSH },
+    CURLHELP_SFTP | CURLHELP_SCP | CURLHELP_SSH },
   { "    --krb <level>",
     "Enable Kerberos with security <level>",
     CURLHELP_DEPRECATED },
@@ -409,7 +411,7 @@ const struct helptxt helptext[] = {
     CURLHELP_CURL },
   { "    --max-filesize <bytes>",
     "Maximum file size to download",
-    CURLHELP_CONNECTION },
+    CURLHELP_CONNECTION | CURLHELP_FTP | CURLHELP_HTTP | CURLHELP_MQTT },
   { "    --max-redirs <num>",
     "Maximum number of redirects allowed",
     CURLHELP_HTTP },
@@ -470,7 +472,7 @@ const struct helptxt helptext[] = {
   { "    --oauth2-bearer <token>",
     "OAuth 2 Bearer Token",
     CURLHELP_AUTH | CURLHELP_IMAP | CURLHELP_POP3 | CURLHELP_SMTP |
-    CURLHELP_LDAP },
+    CURLHELP_LDAP | CURLHELP_HTTP },
   { "    --out-null",
     "Discard response data into the void",
     CURLHELP_OUTPUT },
@@ -494,7 +496,8 @@ const struct helptxt helptext[] = {
     CURLHELP_CONNECTION | CURLHELP_CURL | CURLHELP_GLOBAL },
   { "    --pass <phrase>",
     "Passphrase for the private key",
-    CURLHELP_SSH | CURLHELP_TLS | CURLHELP_AUTH },
+    CURLHELP_TLS | CURLHELP_SFTP | CURLHELP_SCP | CURLHELP_SSH |
+    CURLHELP_AUTH },
   { "    --path-as-is",
     "Do not squash .. sequences in URL path",
     CURLHELP_CURL },
@@ -560,7 +563,7 @@ const struct helptxt helptext[] = {
     CURLHELP_PROXY | CURLHELP_TLS },
   { "    --proxy-header <header/@file>",
     "Pass custom header(s) to proxy",
-    CURLHELP_PROXY },
+    CURLHELP_PROXY | CURLHELP_HTTP },
   { "    --proxy-http2",
     "Use HTTP/2 with HTTPS proxy",
     CURLHELP_HTTP | CURLHELP_PROXY },
@@ -644,7 +647,7 @@ const struct helptxt helptext[] = {
     CURLHELP_HTTP },
   { "-J, --remote-header-name",
     "Use the header-provided filename",
-    CURLHELP_OUTPUT },
+    CURLHELP_OUTPUT | CURLHELP_HTTP },
   { "-O, --remote-name",
     "Write output to file named as remote file",
     CURLHELP_IMPORTANT | CURLHELP_OUTPUT },
@@ -684,10 +687,12 @@ const struct helptxt helptext[] = {
     CURLHELP_CURL | CURLHELP_TIMEOUT },
   { "    --sasl-authzid <identity>",
     "Identity for SASL PLAIN authentication",
-    CURLHELP_AUTH },
+    CURLHELP_AUTH | CURLHELP_IMAP | CURLHELP_SMTP | CURLHELP_POP3 |
+    CURLHELP_LDAP },
   { "    --sasl-ir",
     "Initial response in SASL authentication",
-    CURLHELP_AUTH },
+    CURLHELP_AUTH | CURLHELP_IMAP | CURLHELP_POP3 | CURLHELP_LDAP |
+    CURLHELP_SMTP },
   { "    --service-name <name>",
     "SPNEGO service name",
     CURLHELP_AUTH },
@@ -696,7 +701,8 @@ const struct helptxt helptext[] = {
     CURLHELP_CURL | CURLHELP_GLOBAL },
   { "-i, --show-headers",
     "Show response headers in output",
-    CURLHELP_IMPORTANT | CURLHELP_VERBOSE | CURLHELP_OUTPUT },
+    CURLHELP_IMPORTANT | CURLHELP_VERBOSE | CURLHELP_OUTPUT | CURLHELP_HTTP |
+    CURLHELP_FTP },
   { "    --sigalgs <list>",
     "TLS signature algorithms to use",
     CURLHELP_TLS },
@@ -739,7 +745,7 @@ const struct helptxt helptext[] = {
   { "    --ssl",
     "Try enabling TLS",
     CURLHELP_TLS | CURLHELP_IMAP | CURLHELP_POP3 | CURLHELP_SMTP |
-    CURLHELP_LDAP },
+    CURLHELP_LDAP | CURLHELP_FTP },
   { "    --ssl-allow-beast",
     "Allow security flaw to improve interop",
     CURLHELP_TLS },
@@ -752,7 +758,7 @@ const struct helptxt helptext[] = {
   { "    --ssl-reqd",
     "Require SSL/TLS",
     CURLHELP_TLS | CURLHELP_IMAP | CURLHELP_POP3 | CURLHELP_SMTP |
-    CURLHELP_LDAP },
+    CURLHELP_LDAP | CURLHELP_FTP },
   { "    --ssl-revoke-best-effort",
     "Ignore missing cert CRL dist points",
     CURLHELP_TLS },
@@ -845,13 +851,13 @@ const struct helptxt helptext[] = {
     CURLHELP_VERBOSE | CURLHELP_GLOBAL },
   { "    --unix-socket <path>",
     "Connect through this Unix domain socket",
-    CURLHELP_CONNECTION },
+    CURLHELP_CONNECTION | CURLHELP_HTTP },
   { "-T, --upload-file <file>",
     "Transfer local FILE to destination",
-    CURLHELP_IMPORTANT | CURLHELP_UPLOAD },
+    CURLHELP_IMPORTANT | CURLHELP_UPLOAD | CURLHELP_IMAP },
   { "    --upload-flags <flags>",
     "IMAP upload behavior",
-    CURLHELP_CURL | CURLHELP_OUTPUT },
+    CURLHELP_CURL | CURLHELP_OUTPUT | CURLHELP_IMAP | CURLHELP_UPLOAD },
   { "    --url <url/file>",
     "URL(s) to work with",
     CURLHELP_CURL },

tests/data/data1461.txt

@@ -1,5 +1,5 @@
 Usage: curl [options...] <url>
- -d, --data <data>            HTTP POST data
+ -d, --data <data>            Post data
  -f, --fail                   Fail fast with no output on HTTP errors
  -I, --head                   Show document info only
  -H, --header <header/@file>  Pass custom header(s) to server
@@ -17,7 +17,7 @@ Usage: curl [options...] <url>
 This is not the full help; this menu is split into categories.
 Use "--help category" to get an overview of all categories, which are:
 auth, connection, curl, deprecated, dns, file, ftp, global, http, imap, ldap,%SP
-output, pop3, post, proxy, scp, sftp, smtp, ssh, telnet, tftp, timeout, tls,%SP
+mqtt, output, pop3, post, proxy, scp, sftp, smtp, ssh, telnet, tftp, timeout,%SP
-upload, verbose.
+tls, upload, verbose.
 Use "--help all" to list all options
 Use "--help [option]" to view documentation for a given option

tests/data/test1462

@@ -39,6 +39,7 @@ Unknown category provided, here is a list of all categories:
  http        HTTP and HTTPS protocol
  imap        IMAP protocol
  ldap        LDAP protocol
+ mqtt        MQTT protocol
  output      File system output
  pop3        POP3 protocol
  post        HTTP POST specific