Usage message [options] could be better placed

[Mark Shuttleworth]

I see this at the moment:

mark@mark-XPS-15-9550:~$ snapcraft reserve
Usage:
  snapcraft [options] [--enable-geoip --no-parallel-build]
  snapcraft [options] init
  snapcraft [options] pull [<part> ...] [--enable-geoip]
  snapcraft [options] build [<part> ...] [--no-parallel-build]
  snapcraft [options] stage [<part> ...]
  snapcraft [options] strip [<part> ...]
  snapcraft [options] clean [<part> ...] [--step <step>]
  snapcraft [options] snap [<directory> --output <snap-file>]
  snapcraft [options] cleanbuild
  snapcraft [options] login
  snapcraft [options] logout
  snapcraft [options] upload <snap-file>
  snapcraft [options] list-plugins
  snapcraft [options] help (topics | <plugin> | <topic>) [--devel]
  snapcraft (-h | --help)
  snapcraft --version

The successive [options] sections make this message much less readable. Can we drop the [options] piece up front and put explicit lists of options behind the commands, or alternatively, just document each command options in the specific help for the specific command?

In the end I would like to see:

mark@mark-XPS-15-9550:~$ snapcraft reserve
Usage:
  snapcraft [--enable-geoip --no-parallel-build]
  snapcraft init
  snapcraft pull [<part> ...] [--enable-geoip]
  snapcraft build [<part> ...] [--no-parallel-build]
  snapcraft stage [<part> ...]
  snapcraft strip [<part> ...]
  snapcraft clean [<part> ...] [--step <step>]
  snapcraft snap [<directory> --output <snap-file>]
  snapcraft cleanbuild
  snapcraft login
  snapcraft logout
  snapcraft upload <snap-file>
  snapcraft list-plugins
  snapcraft help (topics | <plugin> | <topic>) [--devel]
  snapcraft (-h | --help)
  snapcraft --version

[Sergio Schvezov (sergiusens)]

We are using this http://docopt.org/ which forces a couple of conventions on us. If this is required, we would need to migrate away from docopt

[Mark Shuttleworth (sabdfl)]

Nice site. I note that none of their examples say:

  program [OPTION] command [command-OPTIONS]

In other words, we're using their stuff in a way that is much uglier
than the way they advertise their stuff :)

What I object to is the huge [OPTION] and the ugly [command-OPTIONS].
What I would prefer is:

  program [command] [options]

So:

  Usage:
    snap [ -h | --help ]
    snap install [-f] [-t]

  Try 'snap help' or 'man snap-install'.

I'm sure this is achievable with docopt since their examples look more
like that.

Mark

[Gustavo Niemeyer (niemeyer)]

I've reported before this and a few suggestions for --help here:

https://bugs.launchpad.net/bugs/1582506

[Leo Arias (elopio)]

The sad thing about those [options] is that in most of the cases it's just -h.
Maybe we can talk to the docopt guys and get tips or a patch upstream.

[Mark Shuttleworth (sabdfl)]

I really, really bet you don't need to patch it.

[Leo Arias (elopio)]

I'm going to raise the priority of this, because we keep adding commands to snapcraft and now the help is pretty ugly.

[Sergio Schvezov (sergiusens)]

https://github.com/snapcore/snapcraft/pull/1307