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

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

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

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@linaro.org>
---
 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());
 	printf("\n");
 	printf("List GPIO chips, print their labels and number of GPIO lines.\n");
 	printf("\n");
diff --git a/tools/gpioget.c b/tools/gpioget.c
index f611737..5d3092b 100644
--- a/tools/gpioget.c
+++ b/tools/gpioget.c
@@ -26,7 +26,7 @@ struct config {
 
 static void print_help(void)
 {
-	printf("Usage: %s [OPTIONS] <line>...\n", get_prog_name());
+	printf("Usage: %s [OPTIONS] <line1> [line2] ...\n", get_prog_name());
 	printf("\n");
 	printf("Read values of GPIO lines.\n");
 	printf("\n");
diff --git a/tools/gpioinfo.c b/tools/gpioinfo.c
index 44d1c8c..002d631 100644
--- a/tools/gpioinfo.c
+++ b/tools/gpioinfo.c
@@ -20,7 +20,7 @@ struct config {
 
 static void print_help(void)
 {
-	printf("Usage: %s [OPTIONS] [line]...\n", get_prog_name());
+	printf("Usage: %s [OPTIONS] [line1] [line2] ...\n", get_prog_name());
 	printf("\n");
 	printf("Print information about GPIO lines.\n");
 	printf("\n");
diff --git a/tools/gpiomon.c b/tools/gpiomon.c
index e3abb2d..cb76913 100644
--- a/tools/gpiomon.c
+++ b/tools/gpiomon.c
@@ -35,7 +35,7 @@ struct config {
 
 static void print_help(void)
 {
-	printf("Usage: %s [OPTIONS] <line>...\n", get_prog_name());
+	printf("Usage: %s [OPTIONS] <line1> [line2] ...\n", get_prog_name());
 	printf("\n");
 	printf("Wait for events on GPIO lines and print them to standard output.\n");
 	printf("\n");
diff --git a/tools/gpionotify.c b/tools/gpionotify.c
index 2c56590..71eacbb 100644
--- a/tools/gpionotify.c
+++ b/tools/gpionotify.c
@@ -28,7 +28,7 @@ struct config {
 
 static void print_help(void)
 {
-	printf("Usage: %s [OPTIONS] <line>...\n", get_prog_name());
+	printf("Usage: %s [OPTIONS] <line1> [line2] ...\n", get_prog_name());
 	printf("\n");
 	printf("Wait for changes to info on GPIO lines and print them to standard output.\n");
 	printf("\n");
diff --git a/tools/gpioset.c b/tools/gpioset.c
index 9dc5aeb..e0d971c 100644
--- a/tools/gpioset.c
+++ b/tools/gpioset.c
@@ -36,7 +36,7 @@ struct config {
 
 static void print_help(void)
 {
-	printf("Usage: %s [OPTIONS] <line=value>...\n", get_prog_name());
+	printf("Usage: %s [OPTIONS] <line1=value1> [line2=value2] ...\n", get_prog_name());
 	printf("\n");
 	printf("Set values of GPIO lines.\n");
 	printf("\n");
-- 
2.39.2

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

[Kent Gibson]

On Tue, Jul 04, 2023 at 02:12:22PM +0200, Bartosz Golaszewski wrote:
> From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
> 
> 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@linaro.org>
> ---
>  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.

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

[Andy Shevchenko]

On Tue, Jul 04, 2023 at 02:12:22PM +0200, Bartosz Golaszewski wrote:
> From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
> 
> 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.

I agree with Kent, I prefer the former over the latter.

And with this syntax the reality looks as

	[chip1 [chip2] ...]

rather than ambiguous [x] [y] where I can't understand what is the meaning
of the chip1 be omitted while chip2 is present.

-- 
With Best Regards,
Andy Shevchenko