| Message ID | 20190619221315.7343-1-chriscool@tuxfamily.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: improve usage string in MyFirstContribution | expand |
On Thu, Jun 20, 2019 at 12:13:15AM +0200, Christian Couder wrote: > SYNOPSIS > -------- > [verse] > -'git-psuh' > +'git-psuh <arg>...' It doesn't require 1 or more args - you can run it with no args. So it might be better suited to state the args as optional: 'git psuh [arg]...' > ---- > static const char * const psuh_usage[] = { > - N_("git psuh"), > + N_("git psuh <arg>..."), ...and here too. - Emily
On Thu, Jun 20, 2019 at 11:29 PM Emily Shaffer <emilyshaffer@google.com> wrote: > > On Thu, Jun 20, 2019 at 12:13:15AM +0200, Christian Couder wrote: > > SYNOPSIS > > -------- > > [verse] > > -'git-psuh' > > +'git-psuh <arg>...' > > It doesn't require 1 or more args - you can run it with no args. So it > might be better suited to state the args as optional: > > 'git psuh [arg]...' > > > ---- > > static const char * const psuh_usage[] = { > > - N_("git psuh"), > > + N_("git psuh <arg>..."), > > ...and here too. Yeah sure, I will will resend soon with such changes.
On Fri, Jun 21, 2019 at 6:43 AM Christian Couder <christian.couder@gmail.com> wrote: > On Thu, Jun 20, 2019 at 11:29 PM Emily Shaffer <emilyshaffer@google.com> wrote: > > It doesn't require 1 or more args - you can run it with no args. So it > > might be better suited to state the args as optional: > > > > 'git psuh [arg]...' > > Yeah sure, I will will resend soon with such changes. More correct would be "git psuh [<arg>]".
Eric Sunshine <sunshine@sunshineco.com> writes: > On Fri, Jun 21, 2019 at 6:43 AM Christian Couder > <christian.couder@gmail.com> wrote: >> On Thu, Jun 20, 2019 at 11:29 PM Emily Shaffer <emilyshaffer@google.com> wrote: >> > It doesn't require 1 or more args - you can run it with no args. So it >> > might be better suited to state the args as optional: >> > >> > 'git psuh [arg]...' >> >> Yeah sure, I will will resend soon with such changes. > > More correct would be "git psuh [<arg>]". I think this takes 0 or more, not 0 or 1, so "git psuh [<arg>...]", no?
On Fri, Jun 21, 2019 at 1:19 PM Junio C Hamano <gitster@pobox.com> wrote: > Eric Sunshine <sunshine@sunshineco.com> writes: > > On Fri, Jun 21, 2019 at 6:43 AM Christian Couder > > <christian.couder@gmail.com> wrote: > >> On Thu, Jun 20, 2019 at 11:29 PM Emily Shaffer <emilyshaffer@google.com> wrote: > >> > It doesn't require 1 or more args - you can run it with no args. So it > >> > might be better suited to state the args as optional: > >> > > >> > 'git psuh [arg]...' > >> > >> Yeah sure, I will will resend soon with such changes. > > > > More correct would be "git psuh [<arg>]". > > I think this takes 0 or more, not 0 or 1, so "git psuh [<arg>...]", > no? I hadn't read the tutorial, but looking at it now, I see that it indeed takes zero or more, so "git psuh [<arg>...]" would be best.
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 895b7cfd4f..7512a35ba3 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -428,7 +428,7 @@ git-psuh - Delight users' typo with a shy horse SYNOPSIS -------- [verse] -'git-psuh' +'git-psuh <arg>...' DESCRIPTION ----------- @@ -491,14 +491,16 @@ Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy tool for pulling out options you need to be able to handle, and it takes a usage string. -In order to use it, we'll need to prepare a NULL-terminated usage string and a -`builtin_psuh_options` array. Add a line to `#include "parse-options.h"`. +In order to use it, we'll need to prepare a NULL-terminated array of usage +strings and a `builtin_psuh_options` array. -At global scope, add your usage: +Add a line to `#include "parse-options.h"`. + +At global scope, add your array of usage strings: ---- static const char * const psuh_usage[] = { - N_("git psuh"), + N_("git psuh <arg>..."), NULL, }; ----
We implement a command called git-psuh which accept arguments, so let's show that it accepts arguments in the doc and the usage string. While at it, we need to prepare "a NULL-terminated array of usage strings", not just "a NULL-terminated usage string". Signed-off-by: Christian Couder <chriscool@tuxfamily.org> --- Documentation/MyFirstContribution.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-)