threads / patch / 25927

patchdocumentation: escape '~' in git revert

Subject: [PATCH] documentation: escape '~' in git revert

## tl;dr

7 messages between Dec 2, 2010 and Dec 2, 2010. Diffs are folded; open one to read it.

replies: 6people: 4as markdown or json

Sylvain Rabot· Dec 2, 2010, 17:36 UTC · lore

backslashing '~' characters do not have any effect, quoting with +++ has.

Signed-off-by: Sylvain Rabot <sylvain.rabot@f-secure.com>
---
 Documentation/git-revert.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

Show changes to Documentation/git-revert.txt +2 −2

diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index f40984d..9368892 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -82,12 +82,12 @@ effect to your index in a row.
 
 EXAMPLES
 --------
-git revert HEAD~3::
+git revert HEAD+++~+++3::
 
 	Revert the changes specified by the fourth last commit in HEAD
 	and create a new commit with the reverted changes.
 
-git revert -n master\~5..master~2::
+git revert -n master+++~+++5..master+++~+++2::
 
 	Revert the changes done by commits from the fifth last commit
 	in master (included) to the third last commit in master

-- 
1.7.3.2

Jonathan Nieder· Dec 2, 2010, 17:50 UTC · re: Sylvain Rabot · lore

Re: [PATCH] documentation: escape '~' in git revert

Hi,

Sylvain Rabot wrote:

> backslashing '~' characters do not have any effect, quoting with +++ has.

Odd.  The first example already looks okay here.

> +++ b/Documentation/git-revert.txt

[...]

> -git revert -n master\~5..master~2::
> +git revert -n master+++~+++5..master+++~+++2::

Please use the {tilde} entity instead of +++, since the former (1) does not make text monospace and (2) works with older asciidoc.

Good catch, thanks.

Junio C Hamano· Dec 2, 2010, 18:23 UTC · re: Jonathan Nieder · lore

Re: [PATCH] documentation: escape '~' in git revert

Here is what I have right now, identified by

    $ git grep -e '~[0-9].*~.*::$' Documentation/

There is one funny I do not understand (oh, well, I admit that I do not understand many funnies around AsciiDoc). The two extra lines you would find if you drop "::$" from the above, namely,

    git-rebase.txt:    git rebase --onto topicA~5 topicA~3 topicA
    user-manual.txt:$ git merge-file hello.c~2 hello.c~1 hello.c~3

do not seem to suffer from this issue. IOW, it seems to affect only the enumeration head items.

 Documentation/git-cherry-pick.txt |    2 +-
 Documentation/git-revert.txt      |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

Show changes to 2 files +2 −2

Documentation/git-cherry-pick.txt, Documentation/git-revert.txt

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 3c96fa8..7300870 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -92,7 +92,7 @@ git cherry-pick ^HEAD master::
 	Apply the changes introduced by all commits that are ancestors
 	of master but not of HEAD to produce new commits.
 
-git cherry-pick master\~4 master~2::
+git cherry-pick master{tilde}4 master{tilde}2::
 
 	Apply the changes introduced by the fifth and third last
 	commits pointed to by master and create 2 new commits with
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index f40984d..752fc88 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -87,7 +87,7 @@ git revert HEAD~3::
 	Revert the changes specified by the fourth last commit in HEAD
 	and create a new commit with the reverted changes.
 
-git revert -n master\~5..master~2::
+git revert -n master{tilde}5..master{tilde}2::
 
 	Revert the changes done by commits from the fifth last commit
 	in master (included) to the third last commit in master

Jonathan Nieder· Dec 2, 2010, 18:32 UTC · re: Junio C Hamano · lore

Re: [PATCH] documentation: escape '~' in git revert

Junio C Hamano wrote:

Show 9 quoted lines

> There is one funny I do not understand (oh, well, I admit that I do not
> understand many funnies around AsciiDoc).  The two extra lines you would
> find if you drop "::$" from the above, namely,
> 
>     git-rebase.txt:    git rebase --onto topicA~5 topicA~3 topicA
>     user-manual.txt:$ git merge-file hello.c~2 hello.c~1 hello.c~3
> 
> do not seem to suffer from this issue.  IOW, it seems to affect only the
> enumeration head items.

FWIW I suspect those are both "literal" environments, thus governed by the rule described in v1.6.0-rc0~152 (git-format-patch(1): fix stray \ in output, 2008-07-02).

Based on "git grep -e '~[^~].*~' -- Documentation/", I think you found them all, unless there are some examples span multiple lines.

Junio C Hamano· Dec 2, 2010, 19:23 UTC · re: Jonathan Nieder · lore

Re: [PATCH] documentation: escape '~' in git revert

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 6 quoted lines

> FWIW I suspect those are both "literal" environments, thus governed
> by the rule described in v1.6.0-rc0~152 (git-format-patch(1): fix
> stray \ in output, 2008-07-02).
>
> Based on "git grep -e '~[^~].*~' -- Documentation/", I think you found
> them all, unless there are some examples span multiple lines.

Thanks.  I'll queue this on 'maint' then.

-- >8 --
Subject: [PATCH] Documentation: Fix mark-up of lines with more than one tilde

The manual pages of cherry-pick and revert had examples with two revisions on the same line in the examples section, that looked like this:

    git cherry-pick master~4 master~2::

Unfortunately, this is taken as a mark-up to make the part between two tildes, "4 master", subscript. Use {tilde} to make it explicit that we do want ~ characters in these places (backslash does not help).

Reported-by: Sylvain Rabot <sylvain.rabot@f-secure.com>
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-cherry-pick.txt |    2 +-
 Documentation/git-revert.txt      |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

Show changes to 2 files +2 −2

Documentation/git-cherry-pick.txt, Documentation/git-revert.txt

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 3c96fa8..7300870 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -92,7 +92,7 @@ git cherry-pick ^HEAD master::
 	Apply the changes introduced by all commits that are ancestors
 	of master but not of HEAD to produce new commits.
 
-git cherry-pick master\~4 master~2::
+git cherry-pick master{tilde}4 master{tilde}2::
 
 	Apply the changes introduced by the fifth and third last
 	commits pointed to by master and create 2 new commits with
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index f40984d..752fc88 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -87,7 +87,7 @@ git revert HEAD~3::
 	Revert the changes specified by the fourth last commit in HEAD
 	and create a new commit with the reverted changes.
 
-git revert -n master\~5..master~2::
+git revert -n master{tilde}5..master{tilde}2::
 
 	Revert the changes done by commits from the fifth last commit
 	in master (included) to the third last commit in master

-- 
1.7.3.2.642.g8b3da

Sylvain Rabot· Dec 2, 2010, 19:15 UTC · re: Junio C Hamano · lore

[PATCH] documentation: replace wrongly evalutated backslashed '~' characters

Sometimes when there is more than one '~' on a line it gets evaluated even if being backslashed and cause '~' characters to be removed in the man pages.

Signed-off-by: Sylvain Rabot <sylvain@abstraction.fr>
---
 Documentation/git-cherry-pick.txt |    2 +-
 Documentation/git-revert.txt      |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

Show changes to 2 files +2 −2

Documentation/git-cherry-pick.txt, Documentation/git-revert.txt

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 3c96fa8..7300870 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -92,7 +92,7 @@ git cherry-pick ^HEAD master::
 	Apply the changes introduced by all commits that are ancestors
 	of master but not of HEAD to produce new commits.
 
-git cherry-pick master\~4 master~2::
+git cherry-pick master{tilde}4 master{tilde}2::
 
 	Apply the changes introduced by the fifth and third last
 	commits pointed to by master and create 2 new commits with
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index f40984d..752fc88 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -87,7 +87,7 @@ git revert HEAD~3::
 	Revert the changes specified by the fourth last commit in HEAD
 	and create a new commit with the reverted changes.
 
-git revert -n master\~5..master~2::
+git revert -n master{tilde}5..master{tilde}2::
 
 	Revert the changes done by commits from the fifth last commit
 	in master (included) to the third last commit in master

-- 
1.7.3.2

Junio C Hamano· Dec 2, 2010, 18:05 UTC · re: Sylvain Rabot · lore

Re: [PATCH] documentation: escape '~' in git revert

Sylvain Rabot <sylvain.rabot@f-secure.com> writes:

> backslashing '~' characters do not have any effect, quoting with +++ has.

I vaguely recall that we tried to avoid using '+++' because versions of AsciiDoc that were widely used back when the bulk of documentation was written either did not handle the construct correctly, or did not know about it at all. So I would be very hesitant to take this patch as-is.

Giving a cursory look at:

    http://www.kernel.org/pub/software/scm/git/docs/git-revert.html

the first instance (HEAD~3) seems to be formatted Ok there (they run AsciiDoc 8.4.5 with xmlto 0.0.23 on F13), but it seems that we do need to do something with the second one (~5..master~2).

I think the problem is that AsciiDoc takes ~something~ as a mark-up for something. Does it work to drop the backslash before ~5 and replace ~ with {tilde}, which was invented to deal with problems like this?

Show 26 quoted lines

> Signed-off-by: Sylvain Rabot <sylvain.rabot@f-secure.com>
> ---
>  Documentation/git-revert.txt |    4 ++--
>  1 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
> index f40984d..9368892 100644
> --- a/Documentation/git-revert.txt
> +++ b/Documentation/git-revert.txt
> @@ -82,12 +82,12 @@ effect to your index in a row.
>  
>  EXAMPLES
>  --------
> -git revert HEAD~3::
> +git revert HEAD+++~+++3::
>  
>  	Revert the changes specified by the fourth last commit in HEAD
>  	and create a new commit with the reverted changes.
>  
> -git revert -n master\~5..master~2::
> +git revert -n master+++~+++5..master+++~+++2::
>  
>  	Revert the changes done by commits from the fifth last commit
>  	in master (included) to the third last commit in master
> -- 
> 1.7.3.2