cmdline-opts: shorter help texts

[bagder]

In an effort to increase the readability of the "--help all" output on narrow (80 column) terminals.

[bagder]

curl 8.6.0 --help all output (the top of it):

Usage: curl [options...] <url>
     --abstract-unix-socket <path> Connect via abstract Unix domain socket
     --alt-svc <file name> Enable alt-svc with this cache file
     --anyauth     Pick any authentication method
 -a, --append      Append to target file when uploading
     --aws-sigv4 <provider1[:provider2[:region[:service]]]> Use AWS V4 signature authentication
     --basic       Use HTTP Basic Authentication
     --ca-native   Use CA certificates from the native OS
     --cacert <file> CA certificate to verify peer against
     --capath <dir> CA directory to verify peer against
 -E, --cert <certificate[:password]> Client certificate file and password
     --cert-status Verify the status of the server cert via OCSP-staple
     --cert-type <type> Certificate type (DER/PEM/ENG/P12)
     --ciphers <list of ciphers> SSL ciphers to use
     --compressed  Request compressed response
     --compressed-ssh Enable SSH compression
 -K, --config <file> Read config from a file
     --connect-timeout <fractional seconds> Maximum time allowed for connection
     --connect-to <HOST1:PORT1:HOST2:PORT2> Connect to host
 -C, --continue-at <offset> Resumed transfer offset
 -b, --cookie <data|filename> Send cookies from string/file
 -c, --cookie-jar <filename> Write cookies to <filename> after operation
     --create-dirs Create necessary local directory hierarchy
     --create-file-mode <mode> File mode for created files
     --crlf        Convert LF to CRLF in upload
     --crlfile <file> Use this CRL list
     --curves <algorithm list> (EC) TLS key exchange algorithm(s) to request
 -d, --data <data> HTTP POST data
     --data-ascii <data> HTTP POST ASCII data
     --data-binary <data> HTTP POST binary data
     --data-raw <data> HTTP POST data, '@' allowed
     --data-urlencode <data> HTTP POST data URL encoded
     --delegation <LEVEL> GSS-API delegation permission
     --digest      Use HTTP Digest Authentication
 -q, --disable     Disable .curlrc

output after this PR:

Usage: curl [options...] <url>
     --abstract-unix-socket <path> Connect via abstract Unix domain socket
     --alt-svc <filename>     Enable alt-svc with this cache file
     --anyauth                Pick any authentication method
 -a, --append                 Append to target file when uploading
     --aws-sigv4 <provider1[:prvdr2[:reg[:srv]]]> AWS V4 signature auth
     --basic                  HTTP Basic Authentication
     --ca-native              Load CA certificates from the OS
     --cacert <file>          CA certificate to verify peer against
     --capath <dir>           CA directory to verify peer against
 -E, --cert <certificate[:password]> Client certificate file and password
     --cert-status            OCSP-staple the server
     --cert-type <type>       Certificate type (DER/PEM/ENG/P12)
     --ciphers <list of ciphers> SSL ciphers to use
     --compressed             Request compressed response
     --compressed-ssh         Enable SSH compression
 -K, --config <file>          Read config from a file
     --connect-timeout <seconds> Maximum time allowed to connect
     --connect-to <HOST1:PORT1:HOST2:PORT2> Connect to host
 -C, --continue-at <offset>   Resumed transfer offset
 -b, --cookie <data|filename> Send cookies from string/load from file
 -c, --cookie-jar <filename>  Save cookies to <filename> after operation
     --create-dirs            Create necessary local directory hierarchy
     --create-file-mode <mode> File mode for created files
     --crlf                   Convert LF to CRLF in upload
     --crlfile <file>         Certificate Revocation list
     --curves <list>          (EC) TLS key exchange algorithms to request
 -d, --data <data>            HTTP POST data
     --data-ascii <data>      HTTP POST ASCII data
     --data-binary <data>     HTTP POST binary data
     --data-raw <data>        HTTP POST data, '@' allowed
     --data-urlencode <data>  HTTP POST data URL encoded
     --delegation <LEVEL>     GSS-API delegation permission
     --digest                 HTTP Digest Authentication
 -q, --disable                Disable .curlrc

[bagder]

and now

Usage: curl [options...] <url>
     --abstract-unix-socket <path> Connect via abstract Unix domain socket
     --alt-svc <filename>          Enable alt-svc with this cache file
     --anyauth                     Pick any authentication method
 -a, --append                      Append to target file when uploading
     --aws-sigv4 <provider1[:prvdr2[:reg[:srv]]]> AWS V4 signature auth
     --basic                       HTTP Basic Authentication
     --ca-native                   Load CA certificates from the OS
     --cacert <file>               CA certificate to verify peer against
     --capath <dir>                CA directory to verify peer against
 -E, --cert <certificate[:password]> Client certificate file and password
     --cert-status                 OCSP-staple the server
     --cert-type <type>            Certificate type (DER/PEM/ENG/P12)
     --ciphers <list of ciphers>   SSL ciphers to use
     --compressed                  Request compressed response
     --compressed-ssh              Enable SSH compression
 -K, --config <file>               Read config from a file
     --connect-timeout <seconds>   Maximum time allowed to connect
     --connect-to <HOST1:PORT1:HOST2:PORT2> Connect to host
 -C, --continue-at <offset>        Resumed transfer offset
 -b, --cookie <data|filename>      Send cookies from string/load from file
 -c, --cookie-jar <filename>       Save cookies to <filename> after operation
     --create-dirs                 Create necessary local directory hierarchy
     --create-file-mode <mode>     File mode for created files
     --crlf                        Convert LF to CRLF in upload
     --crlfile <file>              Certificate Revocation list
     --curves <list>               (EC) TLS key exchange algorithms to request
 -d, --data <data>                 HTTP POST data
     --data-ascii <data>           HTTP POST ASCII data
     --data-binary <data>          HTTP POST binary data
     --data-raw <data>             HTTP POST data, '@' allowed
     --data-urlencode <data>       HTTP POST data URL encoded
     --delegation <LEVEL>          GSS-API delegation permission
     --digest                      HTTP Digest Authentication
 -q, --disable                     Disable .curlrc
     --disable-eprt                Inhibit using EPRT or LPRT

[dfandrich]

Does scripts/completion.pl still work properly with this change?

[bagder]

Does scripts/completion.pl still work properly with this change?

I have no idea. Never used them, don't know how they work... 😮

[bagder]

From a manual inspection, I don't see anything special that this PR should break.

[jay]

For some Windows consoles if the characters run to 80 then it makes the next line a blank line. for example here's what it looks like:

     --crlfile <file>                Certificate Revocation list
     --curves <list>                 (EC) TLS key exchange algorithms to request

 -d, --data <data>                   HTTP POST data

I think that the math needs to account for the spaces in the printf. But also I think there should be another space for the options that exceed the alignment and we end up with one space. here's what that looks like:

     --request-target <path>         Specify the target for this request
     --resolve <[+]host:port:addr[,addr]...> Resolve host+port to address
     --retry <num>                   Retry request if transient problems occur

cutting back a few columns:

diff --git a/src/tool_help.c b/src/tool_help.c
index 38a77f2..4e44f3a 100644
--- a/src/tool_help.c
+++ b/src/tool_help.c
@@ -91,21 +91,21 @@ static void print_category(curlhelp_t category)
     if(len > longdesc)
       longdesc = len;
   }
-  if(longopt + longdesc >= 80) {
+  if(longopt + longdesc >= 79) {
     longdesc -= 3;
-    longopt = 79 - longdesc;
+    longopt = 78 - longdesc;
   }
   for(i = 0; helptext[i].opt; ++i)
     if(helptext[i].categories & category) {
       int opt = (int)longopt;
       size_t desclen = strlen(helptext[i].desc);
-      if(opt + desclen >= 79) {
-        if(desclen < 79)
-          opt = 78 - (int)desclen;
+      if(opt + desclen >= 77) {
+        if(desclen < 77)
+          opt = 76 - (int)desclen;
         else
           opt = 0;
       }
-      printf(" %-*s %s\n", opt, helptext[i].opt, helptext[i].desc);
+      printf(" %-*s  %s\n", opt, helptext[i].opt, helptext[i].desc);
     }
 }
 

     --crlfile <file>                Certificate Revocation list
     --curves <list>                (EC) TLS key exchange algorithms to request
 -d, --data <data>                   HTTP POST data

     --request-target <path>         Specify the target for this request
     --resolve <[+]host:port:addr[,addr]...>  Resolve host+port to address
     --retry <num>                   Retry request if transient problems occur

[bagder]

I think we could maybe save the fine tuning for #13171...

[bagder]

• made two-space gap minimum
• made Windows builds be one byte narrower

[bagder]

update

Usage: curl [options...] <url>
     --abstract-unix-socket <path>   Connect via abstract Unix domain socket
     --alt-svc <filename>            Enable alt-svc with this cache file
     --anyauth                       Pick any authentication method
 -a, --append                        Append to target file when uploading
     --aws-sigv4 <provider1[:prvdr2[:reg[:srv]]]>  AWS V4 signature auth
     --basic                         HTTP Basic Authentication
     --ca-native                     Load CA certs from the OS
     --cacert <file>                 CA certificate to verify peer against
     --capath <dir>                  CA directory to verify peer against
 -E, --cert <certificate[:password]>  Client certificate file and password
     --cert-status                   OCSP-staple the server
     --cert-type <type>              Certificate type (DER/PEM/ENG/P12)
     --ciphers <list of ciphers>     SSL ciphers to use
     --compressed                    Request compressed response
     --compressed-ssh                Enable SSH compression
 -K, --config <file>                 Read config from a file
     --connect-timeout <seconds>     Maximum time allowed to connect
     --connect-to <HOST1:PORT1:HOST2:PORT2>  Connect to host
 -C, --continue-at <offset>          Resumed transfer offset
 -b, --cookie <data|filename>        Send cookies from string/load from file
 -c, --cookie-jar <filename>         Save cookies to <filename> after operation
     --create-dirs                   Create necessary local directory hierarchy
     --create-file-mode <mode>       File mode for created files
     --crlf                          Convert LF to CRLF in upload
     --crlfile <file>                Certificate Revocation list
     --curves <list>                 (EC) TLS key exchange algorithms to request
 -d, --data <data>                   HTTP POST data
     --data-ascii <data>             HTTP POST ASCII data
     --data-binary <data>            HTTP POST binary data
     --data-raw <data>               HTTP POST data, '@' allowed
     --data-urlencode <data>         HTTP POST data URL encoded
     --delegation <LEVEL>            GSS-API delegation permission
     --digest                        HTTP Digest Authentication
 -q, --disable                       Disable .curlrc

[jay]

I think a cert-status description of "OCSP-staple the server" is unclear so I changed it to something longer, however in the case of DoH it is a little longer than I would like but I couldn't think of a better way to say it. Here's what it looks like now (on windows):

> curld --help tls
Usage: curl [options...] <url>
tls: All TLS/SSL related options
     --ca-native                    Load CA certs from the OS
     --cacert <file>                CA certificate to verify peer against
     --capath <dir>                 CA directory to verify peer against
 -E, --cert <certificate[:password]>  Client certificate file and password
     --cert-status                  Verify server cert status via OCSP-staple
     --cert-type <type>             Certificate type (DER/PEM/ENG/P12)
     --ciphers <list of ciphers>    SSL ciphers to use
     --crlfile <file>               Certificate Revocation list
     --curves <list>                (EC) TLS key exchange algorithms to request
     --doh-cert-status            Verify DoH server cert status via OCSP-staple
     --doh-insecure                 Allow insecure DoH server connections
     --egd-file <file>              EGD socket path for random data
     --engine <name>                Crypto engine to use
     --false-start                  Enable TLS False Start
     --ftp-ssl-ccc                  Send CCC after authenticating
     --ftp-ssl-ccc-mode <active/passive>  Set CCC mode
     --ftp-ssl-control              Require TLS for login, clear for transfer
 -k, --insecure                     Allow insecure server connections
     --key <key>                    Private key filename
     --key-type <type>              Private key file type (DER/PEM/ENG)

---

edit: maybe get rid of the word via?

> curld --help tls
Usage: curl [options...] <url>
tls: All TLS/SSL related options
     --ca-native                    Load CA certs from the OS
     --cacert <file>                CA certificate to verify peer against
     --capath <dir>                 CA directory to verify peer against
 -E, --cert <certificate[:password]>  Client certificate file and password
     --cert-status                  Verify server cert status OCSP-staple
     --cert-type <type>             Certificate type (DER/PEM/ENG/P12)
     --ciphers <list of ciphers>    SSL ciphers to use
     --crlfile <file>               Certificate Revocation list
     --curves <list>                (EC) TLS key exchange algorithms to request
     --doh-cert-status              Verify DoH server cert status OCSP-staple
     --doh-insecure                 Allow insecure DoH server connections
     --egd-file <file>              EGD socket path for random data
     --engine <name>                Crypto engine to use
     --false-start                  Enable TLS False Start
     --ftp-ssl-ccc                  Send CCC after authenticating
     --ftp-ssl-ccc-mode <active/passive>  Set CCC mode
     --ftp-ssl-control              Require TLS for login, clear for transfer
 -k, --insecure                     Allow insecure server connections
     --key <key>                    Private key filename
     --key-type <type>              Private key file type (DER/PEM/ENG)