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

Kyle Meyer· Apr 16, 2017, 04:07 UTC · lore

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.

Signed-off-by: Kyle Meyer <kyle@kyleam.com>
---
 Documentation/revisions.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Show changes to Documentation/revisions.txt +2 −2

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 75d211f1a..61277469c 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -295,7 +295,7 @@ The 'r1{caret}@' notation means all parents of 'r1'.
 The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.
 By itself, this notation denotes the single commit 'r1'.
 
-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
 not given. This is typically useful for merge commits where you
 can just pass '<commit>{caret}-' to get all the commits in the branch
@@ -337,7 +337,7 @@ Revision Range Summary
   as giving commit '<rev>' and then all its parents prefixed with
   '{caret}' to exclude them (and their ancestors).
 
-'<rev>{caret}-{<n>}', e.g. 'HEAD{caret}-, HEAD{caret}-2'::
+'<rev>{caret}-<n>', e.g. 'HEAD{caret}-, HEAD{caret}-2'::
 	Equivalent to '<rev>{caret}<n>..<rev>', with '<n>' = 1 if not
 	given.

-- 
2.12.2

Jeff King· Apr 16, 2017, 04:32 UTC · re: Kyle Meyer · lore

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

patchdoc/revisions: remove brackets from rev^-n shorthand