threads / patch / 37186

patchDocumentation: fix missing text for rev-parse --verify

Subject: [PATCH] Documentation: fix missing text for rev-parse --verify

## tl;dr

5 messages between Jul 21, 2014 and Jul 22, 2014. Diffs are folded; open one to read it.

replies: 4people: 2as markdown or json

brian m. carlson· Jul 21, 2014, 23:00 UTC · lore

The caret (^) is used as a markup symbol in AsciiDoc. Due to the inability of AsciiDoc to parse a line containing an unmatched caret, it omitted the line from the output, resulting in the man page missing the end of a sentence. Escape this caret so that the man page ends up with the complete text.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-rev-parse.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/git-rev-parse.txt +1 −1
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 9bd76a5..0b84769 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
 +
 If you want to make sure that the output actually names an object in
 your object database and/or can be used as a specific type of object
-you require, you can add "^{type}" peeling operator to the parameter.
+you require, you can add "\^{type}" peeling operator to the parameter.
 For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
 names an existing object that is a commit-ish (i.e. a commit, or an
 annotated tag that points at a commit).  To make sure that `$VAR`

-- 
2.0.1
Jonathan Nieder· Jul 21, 2014, 23:14 UTC · re: brian m. carlson · lore

Re: [PATCH] Documentation: fix missing text for rev-parse --verify

brian m. carlson wrote:
> The caret (^) is used as a markup symbol in AsciiDoc.  Due to the
> inability of AsciiDoc to parse a line containing an unmatched caret, it
> omitted the line from the output, resulting in the man page missing the
> end of a sentence.

Wow. Usually asciidoc is more forgiving than that. Are there other pages affected by this too (e.g., "the commit HEAD^" in user-manual.txt)?

[...]
Show 8 quoted lines
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
>  +
>  If you want to make sure that the output actually names an object in
>  your object database and/or can be used as a specific type of object
> -you require, you can add "^{type}" peeling operator to the parameter.
> +you require, you can add "\^{type}" peeling operator to the parameter.

Does using {caret} for ^ work, too? Generally in asciidoc using a backslash to escape delimiter characters leads to trouble when the number of delimiters changes or the text is copy+pasted, since in a context where the backslash is unneeded it ends up being rendered as a literal backslash.

Alternatively, does "`^{type}`" work?

Thanks, Jonathan

brian m. carlson· Jul 21, 2014, 23:35 UTC · re: Jonathan Nieder · lore

Re: [PATCH] Documentation: fix missing text for rev-parse --verify

On Mon, Jul 21, 2014 at 04:14:38PM -0700, Jonathan Nieder wrote:
Show 10 quoted lines
> brian m. carlson wrote:
> 
> > The caret (^) is used as a markup symbol in AsciiDoc.  Due to the
> > inability of AsciiDoc to parse a line containing an unmatched caret, it
> > omitted the line from the output, resulting in the man page missing the
> > end of a sentence.
> 
> Wow.  Usually asciidoc is more forgiving than that.  Are there other
> pages affected by this too (e.g., "the commit HEAD^" in
> user-manual.txt)?

I didn't look at any other pages before submitting this. I noticed when I was looking up git rev-parse --verify on my Debian sid laptop at work.

I just looked, and the place you mentioned in user-manual.txt wasn't affected. It looks like this is the only place in running text that we don't use backticks around the caret-containing text.

Show 14 quoted lines
> > --- a/Documentation/git-rev-parse.txt
> > +++ b/Documentation/git-rev-parse.txt
> > @@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
> >  +
> >  If you want to make sure that the output actually names an object in
> >  your object database and/or can be used as a specific type of object
> > -you require, you can add "^{type}" peeling operator to the parameter.
> > +you require, you can add "\^{type}" peeling operator to the parameter.
> 
> Does using {caret} for ^ work, too?  Generally in asciidoc using a
> backslash to escape delimiter characters leads to trouble when the
> number of delimiters changes or the text is copy+pasted, since in a
> context where the backslash is unneeded it ends up being rendered as a
> literal backslash.

{caret} does not work; it leaves the sentence broken still. `^{type}` does work. Since that seems a bit cleaner, and I think the resultant formatting is fine, I'll reroll with that change.

-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187
brian m. carlson· Jul 22, 2014, 23:38 UTC · re: brian m. carlson · lore

[PATCH v2] Documentation: fix missing text for rev-parse --verify

The caret (^) is used as a markup symbol in AsciiDoc. Due to the inability of AsciiDoc to parse a line containing an unmatched caret, it omitted the line from the output, resulting in the man page missing the end of a sentence. The rest of the documentation uses backticks whenever a caret is encountered in running text, so do the same here.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-rev-parse.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/git-rev-parse.txt +1 −1
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 9bd76a5..074030f 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
 +
 If you want to make sure that the output actually names an object in
 your object database and/or can be used as a specific type of object
-you require, you can add "^{type}" peeling operator to the parameter.
+you require, you can add "`^{type}`" peeling operator to the parameter.
 For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
 names an existing object that is a commit-ish (i.e. a commit, or an
 annotated tag that points at a commit).  To make sure that `$VAR`

-- 
2.0.1
Jonathan Nieder· Jul 22, 2014, 23:41 UTC · re: brian m. carlson · lore

Re: [PATCH v2] Documentation: fix missing text for rev-parse --verify

brian m. carlson wrote:
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
>  Documentation/git-rev-parse.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
Thanks again for catching and fixing it.
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

← back to recent threads