Web lists-archives.com

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




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