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

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

[Sylvain Rabot]

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(-)

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

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

[Jonathan Nieder]

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.

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

[Junio C Hamano]

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?

> 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

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

[Junio C Hamano]

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(-)

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

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

[Jonathan Nieder]

Junio C Hamano wrote:

> 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.

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

[Sylvain Rabot]

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(-)

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

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

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> 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(-)

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