tools: clarify the non-option arguments in help text
PATCH 1/1 tools: clarify the non-option arguments in help text
From: Bartosz Golaszewski <[email protected]>
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.
--- 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(-)
tools/gpiodetect.c +1 -1
@@ -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" );
tools/gpioget.c +1 -1
@@ -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" );
tools/gpioinfo.c +1 -1
@@ -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" );
tools/gpiomon.c +1 -1
@@ -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" );
tools/gpionotify.c +1 -1
@@ -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" );
tools/gpioset.c +1 -1
@@ -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" );
Signature · 1 line
2.39.2
Quoted 21 lines · Bartosz Golaszewski
From: Bartosz Golaszewski <[email protected]>
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 <[email protected]>--- 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(-)tools/gpiodetect.c +0
-0
tools/gpiodetect.c line 15
Quoted 5 lines
tools/gpiodetect.c +1
-1@@ -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.
Quoted 5 lines · Bartosz Golaszewski
From: Bartosz Golaszewski <[email protected]>
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.
Signature · 2 lines
With Best Regards, Andy Shevchenko