Describe subcommands in help output

[jlebon]

This is a clone of https://github.com/projectatomic/rpm-ostree/issues/806.

On "root" commands that have subcommands, we should have a short one-liner of what each command does in the -h/--help output, rather than just listing them.

Contrast with e.g. oc:

OpenShift Client

This client helps you develop, build, deploy, and run your applications on any
OpenShift or Kubernetes compatible platform. It also includes the administrative
commands for managing a cluster under the 'adm' subcommand.

Basic Commands:
  types           An introduction to concepts and types
  login           Log in to a server
  new-project     Request a new project
  new-app         Create a new application
  status          Show an overview of the current project
  project         Switch to another project
  projects        Display existing projects
  explain         Documentation of resources
  cluster         Start and stop OpenShift cluster

Build and Deploy Commands:
  rollout         Manage a Kubernetes deployment or OpenShift deployment config
  deploy          View, start, cancel, or retry a deployment
  rollback        Revert part of an application back to a previous deployment
  new-build       Create a new build configuration
  start-build     Start a new build
  cancel-build    Cancel running, pending, or new builds
  ...

[jlebon]

This was done in rpm-ostree:

[cloud-user@f26-tmp ~]$ rpm-ostree --help
Usage:
  rpm-ostree [OPTION?] COMMAND

Builtin Commands:
  compose          Commands to compose a tree
  cleanup          Clear cached/pending data
  db               Commands to query the RPM database
  deploy           Deploy a specific commit
  rebase           Switch to a different tree
  rollback         Revert to the previously booted tree
  status           Get the version of the booted system
  upgrade          Perform a system upgrade
  reload           Reload configuration
  initramfs        Enable or disable local initramfs regeneration
  install          Download and install layered RPM packages
  uninstall        Remove one or more overlay packages

Help Options:
  -h, --help       Show help options

Application Options:
  --version        Print version information and exit

[peterbaouoft]

May I take this issue and work on it? Might take some time tho due to unfamiliarity of the code base. Thanks :)

[jlebon]

Go for it! :)

[peterbaouoft]

Hmm, after reading more into the code, it feels that there are many duplicate code for subcommand handling, and for ostree_option_context_parse(), we are not able to know which command calls the function, making it harder to move the command description.

So, ... I am thinking may be we should also deduplicate the subcommand handling like what we did earlier in https://github.com/projectatomic/rpm-ostree/commit/83aeb018c1012c7a43783c09b74ec71bc9c45826, and then, for the help output, we can do a similar trick as https://github.com/projectatomic/rpm-ostree/pull/916. WDYT?, @jlebon