More clearly seeing which flags are required vs optional in help

[josephschmitt]

When you run help, you get a full list of flags, but it's not super clear which ones are optional versus required:

Usage: test-app --required <command>
A test app.
Flags:
  -h, --help                 Show context-sensitive help.
      --string=STRING        A string flag.
      --bool                 A bool flag with very long help that wraps a lot
                             and is verbose and is really verbose.
      --slice=STR,...        A slice of strings.
      --map=KEY=VALUE;...    A map of strings to ints.
      --required             A required flag.
  -s, --[no-]sort            Is sortable or not.

While the required flags do get printed out in the usage section, it's a bit subtle and easy to miss.

I'm thinking of contributing some sort of syntax that clearly shows which flags are which, but am wondering if there's already a standard for this. Any ideas on what good standardized syntax would look like?

[joseph-galindo]

Following unix's conventions might be a place to start. For builtin help text showing usage, optional flags are also shown, but wrapped in [].

So maybe the flags section in kong could stay the same, but the usage text should change to also include the optional flags. For example, in unix it'd look something like this:

$ man -h
man, version 1.6g

usage: man [-adfhktwW] [section] [-M path] [-P pager] [-S list]
	[-m system] [-p string] name ...

  a : find all matching entries
  c : do not use cat file
  d : print gobs of debugging information
  D : as for -d, but also display the pages
  f : same as whatis(1)
  h : print this help message
  k : same as apropos(1)
  K : search for a string in all pages
  t : use troff to format pages for printing
  w : print location of man page(s) that would be displayed
      (if no name given: print directories that would be searched)
  W : as for -w, but display filenames only

  C file   : use `file' as configuration file
  M path   : set search path for manual pages to `path'
  P pager  : use program `pager' to display pages
  S list   : colon separated section list
  m system : search for alternate system's man pages
  p string : string tells which preprocessors to run
               e - [n]eqn(1)   p - pic(1)    t - tbl(1)
               g - grap(1)     r - refer(1)  v - vgrind(1)

There's some more details about it here: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html

So for your example it might look more like this:

Usage: test-app [--bool] [--help] [--map key=value...] [--slice string...] [--string string] --required command
A test app.
Flags:
  -h, --help                 Show context-sensitive help.
      --string=STRING        A string flag.
      --bool                 A bool flag with very long help that wraps a lot
                             and is verbose and is really verbose.
      --slice=STR,...        A slice of strings.
      --map=KEY=VALUE;...    A map of strings to ints.
      --required             A required flag.
  -s, --[no-]sort            Is sortable or not.

[alecthomas]

This should already be the case IIRC - Kong should be printing required flags in the summary.

[josephschmitt]

@alecthomas Yea I noted that above in my post. I think the usage section is a bit easy to miss. It's also maybe a little bit more complicated than what Joe posted here since it only lists required flags, so you have to do your own comparison. Maybe we can list all flags in the usage section and use [] syntax as suggested, as well as noting the optional status in the flags list as well since at least for me that's where my eyes are drawn and I never look back up to the Usage.

[alecthomas]

That doesn't scale well to large number of flags unfortunately.

[alecthomas]

I think the underlying issue is that there's no "single help" that everybody will be happy with :)

Kong's help is extensible, but it's quite a lot of work in reality. I don't have a better solution, but I'm open to ideas.

[josephschmitt]

Yea the only thing I can think of is surrounding them with [], but that kind of conflicts with my last feature addition which was using those for the [no] negatable flags 🤦. But maybe it would look like

Usage: test-app --required command
A test app.
Flags:
  [-h, --help]                 Show context-sensitive help.
      [--string=STRING]        A string flag.
      [--bool]                 A bool flag with very long help that wraps a lot
                               and is verbose and is really verbose.
      [--slice=STR,...]        A slice of strings.
      [--map=KEY=VALUE;...]    A map of strings to ints.
       --required              A required flag.
  [-s, --[no-]sort]            Is sortable or not.

Which doesn't look super great 🤔

[josephschmitt]

Thinking my best bet for now is to just group together optional flags using the group:"X" tags and go from there.