Re: [PATCH] doc/revisions: remove brackets from rev^-n shorthand

From: Jeff King <peff@peff.net>
Date: Apr 16, 2017, 04:32 UTC
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