Unhelpful "--help" output

[Ricardo Wurmus <rekado@elephly.net>]

Hi Guix,

I found the help output not to be very helpful whenever there are
sub-commands.  The output contains options that are not relevant to the
sub-command.  The options also don't appear to be ordered.

Here is an example.  I want to know more about "guix system
docker-image", so I run "guix system docker-image --help".  This is the
output I get:

--8<---------------cut here---------------start------------->8---
Usage: guix system [OPTION ...] ACTION [ARG ...] [FILE]
Build the operating system declared in FILE according to ACTION.
Some ACTIONS support additional ARGS.

The valid values for ACTION are:

   search           search for existing service types
   edit             edit the definition of an existing service type
   reconfigure      switch to a new operating system configuration
   roll-back        switch to the previous operating system configuration
   describe         describe the current system
   list-generations list the system generations
   switch-generation switch to an existing operating system configuration
   delete-generations delete old system generations
   build            build the operating system without installing anything
   container        build a container that shares the host's store
   vm               build a virtual machine image that shares the host's store
   image            build a Guix System image
   docker-image     build a Docker image
   init             initialize a root file system to run GNU
   extension-graph  emit the service extension graph in Dot format
   shepherd-graph   emit the graph of shepherd services in Dot format

  -L, --load-path=DIR    prepend DIR to the package module search path
  -K, --keep-failed      keep build tree of failed builds
  -k, --keep-going       keep going when some of the derivations fail
  -n, --dry-run          do not build the derivations
      --fallback         fall back to building when the substituter fails
      --no-substitutes   build instead of resorting to pre-built substitutes
      --substitute-urls=URLS
                         fetch substitute from URLS if they are authorized
      --no-grafts        do not graft packages
      --no-offload       do not attempt to offload builds
      --max-silent-time=SECONDS
                         mark the build as failed after SECONDS of silence
      --timeout=SECONDS  mark the build as failed after SECONDS of activity
      --rounds=N         build N times in a row to detect non-determinism
  -c, --cores=N          allow the use of up to N CPU cores for the build
  -M, --max-jobs=N       allow at most N build jobs
      --debug=LEVEL      produce debugging output at LEVEL
  -d, --derivation       return the derivation of the given system
  -e, --expression=EXPR  consider the operating-system EXPR evaluates to
                         instead of reading FILE, when applicable
      --allow-downgrades for 'reconfigure', allow downgrades to earlier
                         channel revisions
      --on-error=STRATEGY
                         apply STRATEGY (one of nothing-special, backtrace,
                         or debug) when an error occurs while reading FILE
      --list-image-types list available image types
  -t, --image-type=TYPE  for 'image', produce an image of TYPE
      --image-size=SIZE  for 'image', produce an image of SIZE
      --no-bootloader    for 'init', do not install a bootloader
      --volatile         for 'image', make the root file system volatile
      --persistent       for 'vm', make the root file system persistent
      --label=LABEL      for 'image', label disk image with LABEL
      --save-provenance  save provenance information
      --share=SPEC       for 'vm' and 'container', share host file system with
                         read/write access according to SPEC
      --expose=SPEC      for 'vm' and 'container', expose host file system
                         directory as read-only according to SPEC
  -N, --network          for 'container', allow containers to access the network
  -r, --root=FILE        for 'vm', 'image', 'container' and 'build',
                         make FILE a symlink to the result, and
                         register it as a garbage collector root
      --full-boot        for 'vm', make a full boot sequence
      --no-graphic       for 'vm', use the tty that we are started in for IO
      --skip-checks      skip file system and initrd module safety checks
  -v, --verbosity=LEVEL  use the given verbosity LEVEL

      --graph-backend=BACKEND
                         use BACKEND for 'extension-graph' and 'shepherd-graph'

  -I, --list-installed[=REGEXP]
                         for 'describe' and 'list-generations', list installed
                         packages matching REGEXP

      --list-targets     list available targets
      --target=TRIPLET   cross-build for TRIPLET--e.g., "aarch64-linux-gnu"

      --list-systems     list available systems
  -s, --system=SYSTEM    attempt to build for SYSTEM--e.g., "i686-linux"

      --help-docker-format list options specific to the docker image type.

  -h, --help             display this help and exit
  -V, --version          display version information and exit

Report bugs to: bug-guix@gnu.org.
GNU Guix home page: <https://guix.gnu.org>
General help using Guix and GNU software: <https://guix.gnu.org/en/help/>
--8<---------------cut here---------------end--------------->8---

Note that this is the same output as for "guix system --help".

I don't think it's great to see all these "for 'vm'" qualifiers on the
right-hand side.

Here is what I propose:

- In the case of commands that offer sub-commands, remove *all* the
options from the help output of the main command (e.g. "guix system
--help"), and only showing the list of available sub-commands.

- For "guix [command] [sub-command] --help" show only options to this
  sub-command.

- optionally, group all generic options (e.g. --system, --help,
  --version, etc) under a single heading.

What do you think?

-- 
Ricardo