From leo.gaskin.extra at gmail.com Fri Nov 13 13:26:05 2020 From: leo.gaskin.extra at gmail.com (Leo Gaskin) Date: Mon Nov 16 08:39:44 2020 Subject: [cli-users] Use comma instead of vertical bar to separate flag names in documentation Message-ID: Hello Boris! 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. 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? Many thanks Leo Gaskin From boris at codesynthesis.com Mon Nov 16 08:52:30 2020 From: boris at codesynthesis.com (Boris Kolpackov) Date: Mon Nov 16 08:53:12 2020 Subject: [cli-users] Use comma instead of vertical bar to separate flag names in documentation In-Reply-To: References: Message-ID: Sorry for the delay on getting this through, for some reason it was caught by our spam filter. Leo Gaskin 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. From petedietl at gmail.com Thu Nov 19 05:03:32 2020 From: petedietl at gmail.com (Pete Dietl) Date: Thu Nov 19 10:12:29 2020 Subject: [cli-users] Contributing and Feature Idea Message-ID: Hey there. I was wondering if this project is mirrored on GitHub? If not, can I contribute via patches? I was browsing some of the issues for build2 and noticed that someone wanted Bash completion scripts. I think I could take on the work of adding a feature to cli to optionally generate bash completion files as an output. What do you all think? From boris at codesynthesis.com Thu Nov 19 10:16:07 2020 From: boris at codesynthesis.com (Boris Kolpackov) Date: Fri Nov 20 09:29:37 2020 Subject: [cli-users] Contributing and Feature Idea In-Reply-To: References: Message-ID: Pete Dietl writes: > I was wondering if this project is mirrored on GitHub? If not, can I > contribute via patches? Yes, sure. Also feel free to point to a branch on GitHub if this is easier (we should mirror but just haven't gotten around to it yet). > I was browsing some of the issues for build2 and noticed that someone > wanted Bash completion scripts. I think I could take on the work of adding > a feature to cli to optionally generate bash completion files as an output. > What do you all think? Sounds good.