review clig.dev for CLI guidelines

[williballenthin]

take inspiration from https://clig.dev/ for best practices when it comes to CLI tools, like capa.

don't necessarily re-write things to adhere to the style, especially when we already have a working solution. however, if they have some good suggestions, see if we can incorporate them as appropriate.

i'll mark this as #help-wanted and #good-first-issue so that contributors can take suggestions from the items below and propose changes in dedicated PRs and issues. note: before spending a lot of time addressing one of these points, please coordinate with us to ensure we all agree on the design and/or wording.

[williballenthin]

validate that our current implementation has a short and long help text.

[williballenthin]

ensure that our help text links to the website and support places, like github.

[williballenthin]

ensure we have a link to the github documentation pages.

[williballenthin]

add some basic examples to our detailed help output, to show users how to invoke the tool correctly.

[williballenthin]

consider adding a footer to the default output that suggests to the user that they can use -v or -vv or the IDA explorer for more details.

[williballenthin]

given that capa frequently produces many pages of output, it would be nice to use a page by default. but we don't want to dissuade users from piping to their own pagers. and we want to be cross platform, not Linux-only.

[williballenthin]

consider adding a footer to the default output that says things like "XXX rule matches in YYY functions across ZZZ namespaces, including AAA, BBB, and CCC".

[errorxyz]

ensure that our help text links to the website and support places, like github.

I'm thinking of making the following changes in the help message: Old:

└─$ capa -h       
usage: capa [-h] [--version] [-v] [-vv] [-d] [-q] [--color {auto,always,never}] [-f {auto,pe,dotnet,elf,sc32,sc64,freeze}] [-b {vivisect,binja,pefile}]
            [--os {auto,linux,macos,windows}] [-r RULES] [-s SIGNATURES] [-t TAG] [-j]
            sample

The FLARE team's open-source tool to identify capabilities in executable files.

positional arguments:
  sample                path to sample to analyze

optional arguments:

New:

└─$ capa -h       
usage: capa [-h] [--version] [-v] [-vv] [-d] [-q] [--color {auto,always,never}] [-f {auto,pe,dotnet,elf,sc32,sc64,freeze}] [-b {vivisect,binja,pefile}]
            [--os {auto,linux,macos,windows}] [-r RULES] [-s SIGNATURES] [-t TAG] [-j]
            sample

The FLARE team's open-source tool to identify capabilities in executable files.
Github: https://github.com/mandiant/capa
Website: https://www.mandiant.com/

positional arguments:
  sample                path to sample to analyze

optional arguments:

[mr-tz]

I think the GitHub link is good. The Mandiant website doesn't really help for capa.