curl: --help [option] displays documentation for given cmdline option

[bagder]

The extracting of the help texts is still a little crude: because we typically have 270KB of text zlib compressed into a single blob, we have to scan for the text to show.

The searching can be made to use Boyer-Moore or similar to speed things up but leaving that for later.

Tasks

• basic functionality
• build integration, both compressed and uncompressed
• verify a --disable-manual build
• documentation
• test cases
• show help for documented negative options like --no-alpn
• accept --no- prefix for boolean options
• reject --no- prefix for non-boolean options
• show --keepalive - do not match --keepalive-cnt (works because of the alpha sorting)
• make sure it does not erroneously find a ^ -- combo before the first option in the manpage

Example command lines.

Short cmdline option

$ curl -h -k
    -k, --insecure
        (TLS SFTP SCP) By default,  every secure connection curl makes  is
        verified to  be  secure  before the  transfer  takes  place.  This
        option makes curl skip the  verification step and proceed  without
        checking.

        When this  option  is  not  used for  protocols  using  TLS,  curl
        verifies the server's  TLS certificate before  it continues:  that
        the  certificate  contains  the  right  name  which  matches   the
        hostname used in the URL and that the certificate has  been signed
        by a CA  certificate present in  the cert  store. See this  online
        resource for further details: https://curl.se/docs/sslcerts.html

        For SFTP  and SCP,  this option  makes curl  skip the  known_hosts
        verification. known_hosts is a file normally stored in the  user's
        home  directory  in  the   ".ssh"  subdirectory,  which   contains
        hostnames and their public keys.

        WARNING: using this option makes the transfer insecure.

        When curl uses  secure protocols  it trusts  responses and  allows
        for example HSTS  and Alt-Svc  information to be  stored and  used
        subsequently. Using --insecure  can make curl  trust and use  such
        information from malicious servers.

        Providing --insecure multiple times  has no extra effect.  Disable
        it again with --no-insecure.

        Example:
         curl --insecure https://example.com

        See also --proxy-insecure, --cacert and --capath.

Long cmdline option

$ curl -h --hsts
    --hsts <filename>
        (HTTPS) Enable HSTS for  the transfer. If  the filename points  to
        an existing  HSTS cache  file,  that is  used. After  a  completed
        transfer, the cache is saved to the filename again if it  has been
        modified.

        If curl  is  told  to  use  HTTP:// for  a  transfer  involving  a
        hostname that exists in the  HSTS cache, it upgrades the  transfer
        to use HTTPS. Each  HSTS cache entry  has an individual life  time
        after which the upgrade is no longer performed.

        Specify a ""  filename (zero length)  to avoid loading/saving  and
        make curl just handle HSTS in memory.

        If this option  is used  several times, curl  loads contents  from
        all the files but the last one is used for saving.

        --hsts can be used several times in a command line

        Example:
         curl --hsts cache.txt https://example.com

        See also --proto. Added in 7.74.0.

Non-existing cmdline option

$ curl -h --foo
Incorrect option name to show help for, see curl -h

[bagder]

I did a quick comparison with brotli and zstd to see how big the gains would be if we would compress the data differently - since most/many builds already use those compression libs.

It turns out the differences are not revolutionary. When using -9 compression for each on the text version of the manpage as of right now:

size	file
274917	curl.txt
72019	curl.txt.gz
66328	curl.txt.zstd
63572	curl.txt.br

[bagder]

Left for future improvement: the displayed manpage section ends with a newline too many.

[yedayak]

It seems it's impossible to show the help for options that are negated in the documentation, since they aren't kept that way in the aliases list. If for example you search for --alpn, than it doesn't find it since it doesn't exist in huge_help, and --no-alpn doesn't match one of the aliases so it fails before searching in the help.

Another side affect of this is that when you look for --keepalive, which appears negated in the man page, it finds --keepalive-cnt, which start matches --keepalive. This specifically can be prevented by adding a space at the end of the search string:

msnprintf(cmdbuf, sizeof(cmdbuf), "\n    %s ", category);

[bagder]

It seems it's impossible to show the help for options that are negated in the documentation, since they aren't kept that way in the aliases list. If for example you search for --alpn, than it doesn't find it since it doesn't exist in huge_help, and --no-alpn doesn't match one of the aliases so it fails before searching in the help.

Oh, so it needs some extra magic. I'll add this as a TODO to fix.

Another side affect of this is that when you look for --keepalive, which appears negated in the man page, it finds --keepalive-cnt, which start matches --keepalive. This specifically can be prevented by adding a space at the end of the search string:

Actually, that trick only works if there actually is a space afterwards in the manpage, which for example --create-dirs does not. So it needs a better fix.

[dfandrich]

Analysis of PR #13997:
Test 1705 failed,
which has NOT been flaky recently, so there could be a real issue in the PR.

Generated by Testclutch