From: Jeff King <peff@peff.net>
Date: Sun, 16 Apr 2017 04:32:12 GMT
Subject: Re: [PATCH] doc/revisions: remove brackets from rev^-n shorthand
Message-ID: <20170416043211.cctkxmjgijk3mtps@sigill.intra.peff.net>
In-Reply-To: <20170416040757.32104-1-kyle@kyleam.com>

On Sun, Apr 16, 2017 at 12:07:57AM -0400, Kyle Meyer wrote:

> Given that other instances of "{...}" in the revision documentation
> represent literal characters of revision specifications, describing
> the rev^-n shorthand as "<rev>^-{<n>}" incorrectly suggests that
> something like "master^-{1}" is an acceptable form.

I wondered at first if this was some weird asciidoc quoting thing. But
no, the curly braces make it through to the rendered version. I agree
they are confusing.

> -The '<rev>{caret}-{<n>}' notation includes '<rev>' but excludes the <n>th
> +The '<rev>{caret}-<n>' notation includes '<rev>' but excludes the <n>th
>  parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if

This _could_ be:

  <rev>^-[<n>]

to show that the <n> parameter is optional. I think the extra
punctuation in a situation like this just makes things harder to read,
though. The text already mentions the default for <n> and gives an
example that omits it, so I think the paragraph is clear as-is (well,
after your patch removes the confusing "{}").

-Peff