[cli-users] Use comma instead of vertical bar to separate flag names in documentation

[Boris Kolpackov]

Sorry for the delay on getting this through, for some reason it
was caught by our spam filter.

Leo Gaskin <leo.gaskin.extra at gmail.com> writes:

> I have been using your CLI description language to implement a
> small command line tool. Working with the language, especially in
> conjunction with your build2 build system has so far been an
> absolute pleasure, as far as C++ is concerned.

Thanks for the kind words, I am glad you are enjoying it.


> However, one thing I have noticed is that, when specifying
> multiple alternate flag names, e.g `--verbose` and `-v` the CLI
> compiler separates them with the vertical bar `|` in generated
> documentation.
> 
> It seems customary to instead use a comma and space to separate
> them. (See `man 1 make`, `man 1 git`, ...). Some tools that parse
> manual pages also rely on this convention.
> 
> Do you have a strong preference for the vertical bar, or would
> you be willing use the more common comma style?

Hm, good question. That decision was made many years ago and I
honestly don't remember the exact reasons. I did a bit of looking
around and while you are right, in options description comma is
commonly used, in synopsis it is the vertical bar. For example,
git-checkout(1):

SYNOPSIS
  git checkout (-p|--patch) ...

OPTIONS
  -p, --patch
    ...

My guess is we just wanted to be consistent.

While I don't think we will be changing all our man pages just yet (we
also use the --patch|-p notation in other documentation, diagnostics,
etc), we can add an option to cli to use comma instead of the vertical
bar.