From: Robert P. J. Day <rpjday@crashcourse.ca>
Date: Thu, 24 May 2018 20:07:18 GMT
Subject: Re: [PATCH] Use proper syntax for replaceables in command docs
Message-ID: <alpine.LFD.2.21.1805241606310.7010@localhost.localdomain>
In-Reply-To: <CAPig+cR91cEj1EdA4JvQQED0HJ2Db-LyrWCB_8VdC6uwT47KbA@mail.gmail.com>

On Thu, 24 May 2018, Eric Sunshine wrote:

> On Thu, May 24, 2018 at 3:54 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> > The standard for command documentation synopses appears to be:
> >
> >   [...] means optional
> >   <...> means replaceable
> >   [<...>] means both optional and replaceable
> >
> > So fix a number of doc pages that use incorrect variations of the
> > above.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> > ---
> > diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
> > @@ -9,7 +9,7 @@ git-check-attr - Display gitattributes information
> > -'git check-attr' [-a | --all | attr...] [--] pathname...
> > +'git check-attr' [-a | --all | attr...] [--] <pathname>...
> >  'git check-attr' --stdin [-z] [-a | --all | attr...]
>
> Don't you also want "<attr>"?
>
> > diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
> > @@ -9,8 +9,8 @@ git-check-ignore - Debug gitignore / exclude files
> > -'git check-ignore' [options] pathname...
> > +'git check-ignore' [<options>] <paths>...
>
> Earlier in the patch, you changed "pathname" to "<pathname>", but here
> you change "pathname" to "<paths>", which is inconsistent.
>
> It's also inconsistent and odd to say "<paths>..." (with the "...").
> Seems better just to say "<pathname>..." to match existing practice.

  points taken. note that this is not even close to a comprehensive
fix; i just did the stuff i ran across. there is almost certainly much
more, but i'll fix the above.

rday