Re: [libgpiod][PATCH] tools: clarify the non-option arguments in help text

[Kent Gibson <warthog618@xxxxxxxxx>]

On Tue, Jul 04, 2023 at 02:12:22PM +0200, Bartosz Golaszewski wrote:
> From: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
> 
> We already use [] for optional and <> for required arguments in help text
> but let's make it clear that we can pass multiple chips/lines and in most
> tools only the first one is required.
> 
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@xxxxxxxxxx>
> ---
>  tools/gpiodetect.c | 2 +-
>  tools/gpioget.c    | 2 +-
>  tools/gpioinfo.c   | 2 +-
>  tools/gpiomon.c    | 2 +-
>  tools/gpionotify.c | 2 +-
>  tools/gpioset.c    | 2 +-
>  6 files changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/tools/gpiodetect.c b/tools/gpiodetect.c
> index 0a3461b..569cdfe 100644
> --- a/tools/gpiodetect.c
> +++ b/tools/gpiodetect.c
> @@ -12,7 +12,7 @@
>  
>  static void print_help(void)
>  {
> -	printf("Usage: %s [OPTIONS] [chip]...\n", get_prog_name());
> +	printf("Usage: %s [OPTIONS] [chip1] [chip2] ...\n", get_prog_name());

I prefer the first form myself.  It can be argued that the second form is
more confusing.  In both cases you need to parse the ellipsis, but the
second is close to:
    "Usage: %s [OPTIONS] <chip1> <chip2> ...\n"

which means something very different.

What does git do?

"git log [<options>] [<revision-range>] [[--] <path>...]"

"git branch (-d | -D) [-r] <branchname>..."

So it uses the first form for required parameters, and a variant of the
first form (i.e. "[<pattern>...]" where we use "[pattern]...") for
optional parameters.

Cheers,
Kent.