Option groups in command-line help

[cameel]

Related to #9075. The current command-line help is a big list with very little organization and this does not make it easy to see which options will be ignored when used in combination. While this PR does not solve this problem, I think that grouping the options makes relations between them a bit clearer.

Here's how it would look like if this PR was merged. This is the best I could come up with on my own but some choices are pretty arbitrary so feedback is welcome:

solc, the Solidity commandline compiler.

This program comes with ABSOLUTELY NO WARRANTY. This is free software, and you
are welcome to redistribute it under certain conditions. See 'solc --license'
for details.

Usage: solc [options] [input_file...]
Compiles the given Solidity input files (or the standard input if none given or
"-" is used as a file name) and outputs the components specified in the options
at standard output or in files in the output directory, if specified.
Imports are automatically read from the filesystem, but it is also possible to
remap paths using the context:prefix=path syntax.
Example:
solc --bin -o /tmp/solcoutput dapp-bin=/usr/local/lib/dapp-bin contract.sol

General Information:
  --help               Show help message and exit.
  --version            Show version and exit.
  --license            Show licensing information and exit.

Input Options:
  --base-path path     Use the given path as the root of the source tree 
                       instead of the root of the filesystem.
  --allow-paths path(s)
                       Allow a given path for imports. A list of paths can be 
                       supplied by separating them with a comma.
  --ignore-missing     Ignore missing files.
  --error-recovery     Enables additional parser error recovery.

Output Options:
  -o [ --output-dir ] path
                       If given, creates one file per component and 
                       contract/file at the specified directory.
  --overwrite          Overwrite existing files (used together with -o).
  --evm-version version
                       Select desired EVM version. Either homestead, 
                       tangerineWhistle, spuriousDragon, byzantium, 
                       constantinople, petersburg, istanbul (default) or 
                       berlin.
  --revert-strings debug,default,strip,verboseDebug
                       Strip revert (and require) reason strings or add 
                       additional debugging information.

Alternative Input Modes:
  --standard-json      Switch to Standard JSON input / output mode, ignoring 
                       all options. It reads from standard input, if no input 
                       file was given, otherwise it reads from the provided 
                       input file. The result will be written to standard 
                       output.
  --link               Switch to linker mode, ignoring all options apart from 
                       --libraries and modify binaries in place.
  --assemble           Switch to assembly mode, ignoring all options except 
                       --machine, --yul-dialect, --optimize and 
                       --yul-optimizations and assumes input is assembly.
  --yul                Switch to Yul mode, ignoring all options except 
                       --machine, --yul-dialect, --optimize and 
                       --yul-optimizations and assumes input is Yul.
  --strict-assembly    Switch to strict assembly mode, ignoring all options 
                       except --machine, --yul-dialect, --optimize and 
                       --yul-optimizations and assumes input is strict 
                       assembly.
  --import-ast         Import ASTs to be compiled, assumes input holds the AST 
                       in compact JSON format. Supported Inputs is the output 
                       of the --standard-json or the one produced by 
                       --combined-json ast,compact-format

Assembly Mode Options:
  --machine evm,evm15,ewasm
                       Target machine in assembly or Yul mode.
  --yul-dialect evm,ewasm
                       Input dialect to use in assembly or yul mode.

Linker Mode Options:
  --libraries libs     Direct string or file containing library addresses.
                       Syntax: <libraryName>:<address> [, or whitespace] ...
                       Address is interpreted as a hex string optionally
                       prefixed by 0x.

Output Formatting:
  --pretty-json        Output JSON in pretty format. Currently it only works
                       with the combined JSON output.
  --color              Force colored output.
  --no-color           Explicitly disable colored output, disabling terminal
                       auto-detection.
  --old-reporter       Enables old diagnostics reporter (legacy option, will be
                       removed).

Output Components:
  --ast-json           AST of all source files in JSON format.
  --ast-compact-json   AST of all source files in a compact JSON format.
  --asm                EVM assembly of the contracts.
  --asm-json           EVM assembly of the contracts in JSON format.
  --opcodes            Opcodes of the contracts.
  --bin                Binary of the contracts in hex.
  --bin-runtime        Binary of the runtime part of the contracts in hex.
  --abi                ABI specification of the contracts.
  --ir                 Intermediate Representation (IR) of all contracts
                       (EXPERIMENTAL).
  --ir-optimized       Optimized intermediate Representation (IR) of all
                       contracts (EXPERIMENTAL).
  --ewasm              Ewasm text representation of all contracts
                       (EXPERIMENTAL).
  --hashes             Function signature hashes of the contracts.
  --userdoc            Natspec user documentation of all contracts.
  --devdoc             Natspec developer documentation of all contracts.
  --metadata           Combined Metadata JSON whose Swarm hash is stored
                       on-chain.
  --storage-layout     Slots, offsets and types of the contract's state
                       variables.

Extra Output:
  --gas                Print an estimate of the maximal gas usage for each
                       function.
  --combined-json abi,asm,ast,bin,bin-runtime,compact-format,devdoc,hashes,interface,metadata,opcodes,srcmap,srcmap-runtime,storage-layout,userdoc
                       Output a single json document containing the specified
                       information.

Metadata Options:
  --metadata-hash ipfs,none,swarm
                       Choose hash method for the bytecode metadata or disable
                       it.
  --metadata-literal   Store referenced sources as literal data in the metadata
                       output.

Optimizer Options:
  --optimize           Enable bytecode optimizer.
  --optimize-runs n (=200)
                       Set for how many contract runs to optimize. Lower values
                       will optimize more for initial deployment cost, higher
                       values will optimize more for high-frequency usage.
  --optimize-yul       Legacy option, ignored. Use the general --optimize to
                       enable Yul optimizer.
  --no-optimize-yul    Disable Yul optimizer in Solidity.
  --yul-optimizations steps
                       Forces yul optimizer to use the specified sequence of
                       optimization steps instead of the built-in one.

[ekpyron]

I'm not too happy with the Diagnostics section.
--old-reporter may just be a "Legacy Option:" (it's deprecated and will be removed, might even be worth mentioning). Or if not that, then it's a Output Formatting option.

--error-recovery is maybe rather an input option...
--revert-strings is an output option - although rather in the sense of changing what we output, but in a sense that's silimar to ---evm-version.

[cameel]

OK. I'll change it.

[cameel]

• Diagnostics removed.
• Input and Output Options are now two separate sections.
• --old-reporter is now in Output Formatting (and marked as a legacy option).
• --revert-strings is now in Output Options.
• --error-recovery is now in Input Options.

The copied help text in the description has been updated. You can click the edited dropdown near the post date to see a diff.

[ekpyron]

The grouping is still not "prefect", but I think it's good enough, resp. the best we can do.

I'd be fine with merging this as is now, but are there any other opinions about this @chriseth @axic @leonardoalt ?