[PATCH] escape tilde in Documentation/git-rev-parse.txt

[PATCH] escape tilde in Documentation/git-rev-parse.txt

[Stefan Richter]

fixes a failure to build the git-rev-parse manpage,
seen with asciidoc 8.0.0

Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>
---
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index b761b4b..671b4e3 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -138,7 +138,7 @@ syntax.
   'rev{caret}0' means the commit itself and is used when 'rev' is the
   object name of a tag object that refers to a commit object.
 
-* A suffix '~<n>' to a revision parameter means the commit
+* A suffix '$$~$$<n>' to a revision parameter means the commit
   object that is the <n>th generation grand-parent of the named
   commit object, following only the first parent.  I.e. rev~3 is
   equivalent to rev{caret}{caret}{caret} which is equivalent to\

Re: [PATCH] escape tilde in Documentation/git-rev-parse.txt

[Junio C Hamano]

Stefan Richter <stefanr@s5r6.in-berlin.de> writes:

> fixes a failure to build the git-rev-parse manpage,
> seen with asciidoc 8.0.0
>
> Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>
> ---
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index b761b4b..671b4e3 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -138,7 +138,7 @@ syntax.
>    'rev{caret}0' means the commit itself and is used when 'rev' is the
>    object name of a tag object that refers to a commit object.
>  
> -* A suffix '~<n>' to a revision parameter means the commit
> +* A suffix '$$~$$<n>' to a revision parameter means the commit
>    object that is the <n>th generation grand-parent of the named
>    commit object, following only the first parent.  I.e. rev~3 is
>    equivalent to rev{caret}{caret}{caret} which is equivalent to\

But this makes it asciidoc 7.1 barf, so we need an alternative
compatible to both.

This works for me on 7.1; is your 8.0 happy with it?

-- >8 --

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 8196d78..44b1ce4 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -11,6 +11,7 @@ # the command.
 caret=^
 startsb=&#91;
 endsb=&#93;
+tilde=&#126;
 
 ifdef::backend-docbook[]
 [gitlink-inlinemacro]
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index b761b4b..2f1306c 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -138,7 +138,7 @@ syntax.
   'rev{caret}0' means the commit itself and is used when 'rev' is the
   object name of a tag object that refers to a commit object.
 
-* A suffix '~<n>' to a revision parameter means the commit
+* A suffix '{tilde}<n>' to a revision parameter means the commit
   object that is the <n>th generation grand-parent of the named
   commit object, following only the first parent.  I.e. rev~3 is
   equivalent to rev{caret}{caret}{caret} which is equivalent to\

Re: [PATCH] escape tilde in Documentation/git-rev-parse.txt

[Stefan Richter]

Junio C Hamano wrote:
...
> This works for me on 7.1; is your 8.0 happy with it?
...
> +tilde=~
...
> -* A suffix '~<n>' to a revision parameter means the commit
> +* A suffix '{tilde}<n>' to a revision parameter means the commit
...

Yes, this works as intended. Thanks,
-- 
Stefan Richter
-=====-=-==- =-=- ---==
http://arcgraph.de/sr/

Re: [PATCH] escape tilde in Documentation/git-rev-parse.txt

[Junio C Hamano]

Stefan Richter <stefanr@s5r6.in-berlin.de> writes:

> Junio C Hamano wrote:
> ...
>> This works for me on 7.1; is your 8.0 happy with it?
> ...
>> +tilde=&#126;
> ...
>> -* A suffix '~<n>' to a revision parameter means the commit
>> +* A suffix '{tilde}<n>' to a revision parameter means the commit
> ...
>
> Yes, this works as intended. Thanks,

Thanks.  It's a bit sad that asciidoc's nicer quoting features
are not backward compatible.

pull-fetch-param.txt (was Re: [PATCH] escape tilde in Documentation/git-rev-parse.txt)

[Stefan Richter]

Junio C Hamano wrote:
> It's a bit sad that asciidoc's nicer quoting features
> are not backward compatible.

Yes, this is awkward. Here comes the next candidate for quoting.
In pull-fetch-param.txt:

----8<----
<refspec>::
	The canonical format of a <refspec> parameter is
	`+?<src>:<dst>`; that is, an optional plus `+`, followed
	by the source ref, followed by a colon `:`, followed by
	the destination ref.
+
The remote ref that matches <src>
is fetched, and if <dst> is not empty string, the local
ref that matches it is fast forwarded using <src>.
Again, if the optional plus `+` is used, the local ref
---->8----

"man git-fetch" and "man git-pull" show:
----8<----
       <refspec>
              The  canonical  format of a <refspec> parameter is ?<src>:<dst>;
              that is, an optional plus, followed by the source ref,  followed
              by a colon :, followed by the destination ref.

              The  remote  ref  that matches <src> is fetched, and if <dst> is
              not empty string, the local ref that matches  it  is  fast  for-
              warded  using  <src>. Again, if the optional plus + is used, the
---->8----

I.e. the first and second + were swallowed, but not the third one.
This is the fix for asciidoc 8.0.0:
	`$$+$$?<src>:<dst>`; that is, an optional plus `+`, followed

Here is another fix that works with asciidoc 8.0.0:
	`\+?<src>:<dst>`; that is, an optional plus `+`, followed

Results in
----8<----
       <refspec>
              The  canonical format of a <refspec> parameter is +?<src>:<dst>;
              that is, an optional plus +, followed by the  source  ref,  fol-
              lowed by a colon :, followed by the destination ref.

              The  remote  ref  that matches <src> is fetched, and if <dst> is
              not empty string, the local ref that matches  it  is  fast  for-
              warded  using  <src>. Again, if the optional plus + is used, the
---->8----

Does the backslash notation work with asciidoc 7?
-- 
Stefan Richter
-=====-=-==- =-=- ---==
http://arcgraph.de/sr/

Re: pull-fetch-param.txt

[Junio C Hamano]

Stefan Richter <stefanr@s5r6.in-berlin.de> writes:

> Junio C Hamano wrote:
>> It's a bit sad that asciidoc's nicer quoting features
>> are not backward compatible.
>
> Yes, this is awkward. Here comes the next candidate for quoting.

[Stuart Rackham CC'ed]

At this point I have to say

	What the h*ck AsciiDoc people are thinking?

Heck, I thought we were one of the more important customers of
asciidoc project and not breaking us meant at least something to
them; our name is at the top of "Project using AsciiDoc" section
of their website, http:/www.methods.co.nz/asciidoc/.  Apparently
I was delusional.

Introducing nicer new features is a good thing, but you do not
break existing documents without a good reason and an escape
hatch.

Put it more mildly, I think we need to find out what their
policy on backward compatibility is, and if it is "screw it --
you should re-mark-up your documents to match the newer rule
every time we have a new release.  By the way, you always have
the option to stay at older releases of ours", then we should
seriously consider switching the documentation format to
something else.  I honestly hope it does not have to come to
that.

> In pull-fetch-param.txt:
>
> ----8<----
> <refspec>::
> 	The canonical format of a <refspec> parameter is
> 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
> 	by the source ref, followed by a colon `:`, followed by
> 	the destination ref.
> +
> The remote ref that matches <src>
> is fetched, and if <dst> is not empty string, the local
> ref that matches it is fast forwarded using <src>.
> Again, if the optional plus `+` is used, the local ref
> ---->8----
>
> "man git-fetch" and "man git-pull" show:
> ----8<----
>        <refspec>
>               The  canonical  format of a <refspec> parameter is ?<src>:<dst>;
>               that is, an optional plus, followed by the source ref,  followed
>               by a colon :, followed by the destination ref.
>
>               The  remote  ref  that matches <src> is fetched, and if <dst> is
>               not empty string, the local ref that matches  it  is  fast  for-
>               warded  using  <src>. Again, if the optional plus + is used, the
> ---->8----
>
> I.e. the first and second + were swallowed, but not the third one.
> This is the fix for asciidoc 8.0.0:
> 	`$$+$$?<src>:<dst>`; that is, an optional plus `+`, followed

Without looking at asciidoc 8.0 source, my guess is that it
treats _anything_ that has two pluses on the same input line as
quoted by some magical '+'-pair quote.   Can you try
reformatting the original

> <refspec>::
> 	The canonical format of a <refspec> parameter is
> 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
> 	by the source ref, followed by a colon `:`, followed by
> 	the destination ref.

to something like

> <refspec>::
> 	The canonical format of a <refspec> parameter is
> 	`+?<src>:<dst>`; that is, an optional plus
>	`+`, followed
> 	by the source ref, followed by a colon `:`, followed by
> 	the destination ref.

and verify that conjecture?

We already had to deal with this with your patch for tilde.
Arguably tilde and caret are rare enough in plain text so we can
live with having to spell it as {caret} and {tilde}, but if my
guess is correct, that means we have to spell plus '+' as {plus}
with an appropriate entry in asciidoc.conf (or "\+" if it works
in both older and newer versions).  As more ordinary characters
are taken for special mark-up purposes, we would need to keep
adding them to our list.  Where does the madness end?

Fortunately AsciiDoc 8.0 is still young.  Maybe they can find a
fix for this in a way that does not break documents written for
(at least recent versions of) AsciiDoc 7; it might have to break
documents written for early betas and the initial release of
8.0, but that is _much_ better than breaking existing documents,
in my extremely biased opinion as a very unhappy user.

Re: pull-fetch-param.txt

[Stuart Rackham]

 From the AsciiDoc User Guide 
(http://www.methods.co.nz/asciidoc/userguide.html#X53):

If you want to disable unconstrained quotes, the new alternative 
constrained quotes syntax and the new index entry syntax then you can 
define the attribute asciidoc7compatible (for example by using the -a 
asciidoc7compatible command-line option).

--
Stuart Rackham


Junio C Hamano wrote:
> Stefan Richter <stefanr@s5r6.in-berlin.de> writes:
> 
>> Junio C Hamano wrote:
>>> It's a bit sad that asciidoc's nicer quoting features
>>> are not backward compatible.
>> Yes, this is awkward. Here comes the next candidate for quoting.
> 
> [Stuart Rackham CC'ed]
> 
> At this point I have to say
> 
> 	What the h*ck AsciiDoc people are thinking?
> 
> Heck, I thought we were one of the more important customers of
> asciidoc project and not breaking us meant at least something to
> them; our name is at the top of "Project using AsciiDoc" section
> of their website, http:/www.methods.co.nz/asciidoc/.  Apparently
> I was delusional.
> 
> Introducing nicer new features is a good thing, but you do not
> break existing documents without a good reason and an escape
> hatch.
> 
> Put it more mildly, I think we need to find out what their
> policy on backward compatibility is, and if it is "screw it --
> you should re-mark-up your documents to match the newer rule
> every time we have a new release.  By the way, you always have
> the option to stay at older releases of ours", then we should
> seriously consider switching the documentation format to
> something else.  I honestly hope it does not have to come to
> that.
> 
>> In pull-fetch-param.txt:
>>
>> ----8<----
>> <refspec>::
>> 	The canonical format of a <refspec> parameter is
>> 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
>> 	by the source ref, followed by a colon `:`, followed by
>> 	the destination ref.
>> +
>> The remote ref that matches <src>
>> is fetched, and if <dst> is not empty string, the local
>> ref that matches it is fast forwarded using <src>.
>> Again, if the optional plus `+` is used, the local ref
>> ---->8----
>>
>> "man git-fetch" and "man git-pull" show:
>> ----8<----
>>        <refspec>
>>               The  canonical  format of a <refspec> parameter is ?<src>:<dst>;
>>               that is, an optional plus, followed by the source ref,  followed
>>               by a colon :, followed by the destination ref.
>>
>>               The  remote  ref  that matches <src> is fetched, and if <dst> is
>>               not empty string, the local ref that matches  it  is  fast  for-
>>               warded  using  <src>. Again, if the optional plus + is used, the
>> ---->8----
>>
>> I.e. the first and second + were swallowed, but not the third one.
>> This is the fix for asciidoc 8.0.0:
>> 	`$$+$$?<src>:<dst>`; that is, an optional plus `+`, followed
> 
> Without looking at asciidoc 8.0 source, my guess is that it
> treats _anything_ that has two pluses on the same input line as
> quoted by some magical '+'-pair quote.   Can you try
> reformatting the original
> 
>> <refspec>::
>> 	The canonical format of a <refspec> parameter is
>> 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
>> 	by the source ref, followed by a colon `:`, followed by
>> 	the destination ref.
> 
> to something like
> 
>> <refspec>::
>> 	The canonical format of a <refspec> parameter is
>> 	`+?<src>:<dst>`; that is, an optional plus
>> 	`+`, followed
>> 	by the source ref, followed by a colon `:`, followed by
>> 	the destination ref.
> 
> and verify that conjecture?
> 
> We already had to deal with this with your patch for tilde.
> Arguably tilde and caret are rare enough in plain text so we can
> live with having to spell it as {caret} and {tilde}, but if my
> guess is correct, that means we have to spell plus '+' as {plus}
> with an appropriate entry in asciidoc.conf (or "\+" if it works
> in both older and newer versions).  As more ordinary characters
> are taken for special mark-up purposes, we would need to keep
> adding them to our list.  Where does the madness end?
> 
> Fortunately AsciiDoc 8.0 is still young.  Maybe they can find a
> fix for this in a way that does not break documents written for
> (at least recent versions of) AsciiDoc 7; it might have to break
> documents written for early betas and the initial release of
> 8.0, but that is _much_ better than breaking existing documents,
> in my extremely biased opinion as a very unhappy user.
> 

Re: pull-fetch-param.txt

[Junio C Hamano]

Stuart Rackham <srackham@methods.co.nz> writes:

> From the AsciiDoc User Guide
> (http://www.methods.co.nz/asciidoc/userguide.html#X53):
>
> If you want to disable unconstrained quotes, the new alternative
> constrained quotes syntax and the new index entry syntax then you can
> define the attribute asciidoc7compatible (for example by using the -a
> asciidoc7compatible command-line option).
>
> --
> Stuart Rackham

Thank you for a quick reply.

Stefan, can you try it with the earlier commit to escape tilde
reverted and see if our documentation set behaves well?

asciidoc 7--8 compatibility (was Re: pull-fetch-param.txt)

[Stefan Richter]

Stuart Rackham wrote:
> From the AsciiDoc User Guide
> (http://www.methods.co.nz/asciidoc/userguide.html#X53):
> 
> If you want to disable unconstrained quotes, the new alternative
> constrained quotes syntax and the new index entry syntax then you can
> define the attribute asciidoc7compatible (for example by using the -a
> asciidoc7compatible command-line option).

Stuart,

the actual issues were:

1.) Input which works with asciidoc 7 fails to build with asciidoc 8
(after the intermediary XML step). This pair of tildes broke (but other
occurences of tilde did not):

| * A suffix '~<n>' to a revision parameter means the commit
|   object that is the <n>th generation grand-parent of the named
|   commit object, following only the first parent.  I.e. rev~3 is

2.) Asciidoc 8 silently swallows characters from input which works with
asciidoc 7. The two pluses in the following line vanished (but instances
of single pluses per input line did not vanish):

| 	`+?<src>:<dst>`; that is, an optional plus `+`, followed

I wonder:

 - Are tilde and plus new special characters in asciidoc 8, or were they
already special characters in asciidoc 7?
       [ A pair of single pluses encloses monospaced text in asciidoc 8.
         A pair of single tildes encloses subscripts. ]

 - If they were already special characters in asciidoc 7, what is the
canonical way to escape them in asciidoc 7, 8, and hopefully 9?
       [ If they weren't special characters in asciidoc 7, then we need
         to use the asciidoc7compatible attribute. ]

 - Does asciidoc 7 accept the asciidoc7compatible attribute?

Thanks.


PS:

Junio, Stuart, here is another inconsistency between asciidoc 7 and 8.
Please have a look at
http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html .
See the ASCII art above "SPECIFYING RANGES". The input
       \  |  / \
        \ | /   |
produced
   \  |  /         \ | /   |
I.e. backslash-newline was interpreted by asciidoc 7 (or whatever you
use to generate what is put online) as an escaped thus swallowed
newline. But the output that I got here from asciidoc 8 (manpage as well
as the html file) still has backslash and newline printed out.
-- 
Stefan Richter
-=====-=-==- =-=- --=--
http://arcgraph.de/sr/

Re: asciidoc 7--8 compatibility (was Re: pull-fetch-param.txt)

[Stuart Rackham]

[-- Attachment #1: Type: text/plain, Size: 2624 bytes --]

Hi Stefan

Stefan Richter wrote:
> Stuart Rackham wrote:
>> From the AsciiDoc User Guide
>> (http://www.methods.co.nz/asciidoc/userguide.html#X53):
>>
>> If you want to disable unconstrained quotes, the new alternative
>> constrained quotes syntax and the new index entry syntax then you can
>> define the attribute asciidoc7compatible (for example by using the -a
>> asciidoc7compatible command-line option).
> 
> Stuart,
> 
> the actual issues were:
> 
> 1.) Input which works with asciidoc 7 fails to build with asciidoc 8
> (after the intermediary XML step). This pair of tildes broke (but other
> occurences of tilde did not):
> 
> | * A suffix '~<n>' to a revision parameter means the commit
> |   object that is the <n>th generation grand-parent of the named
> |   commit object, following only the first parent.  I.e. rev~3 is

I've conditionally redefined subscript (tilde) and superscripting so 
they use the old replacements mechanism when asciidoc7compatible is 
defined rather than the asciidoc 8 default unconstrained quoting (patch 
for affected files attached).


> 
> 2.) Asciidoc 8 silently swallows characters from input which works with
> asciidoc 7. The two pluses in the following line vanished (but instances
> of single pluses per input line did not vanish):
> 
> | 	`+?<src>:<dst>`; that is, an optional plus `+`, followed

Fixed by asciidoc7compatible.


> 
> I wonder:
> 
>  - Are tilde and plus new special characters in asciidoc 8, or were they
> already special characters in asciidoc 7?
>        [ A pair of single pluses encloses monospaced text in asciidoc 8.
>          A pair of single tildes encloses subscripts. ]
> 
>  - If they were already special characters in asciidoc 7, what is the
> canonical way to escape them in asciidoc 7, 8, and hopefully 9?
>        [ If they weren't special characters in asciidoc 7, then we need
>          to use the asciidoc7compatible attribute. ]
> 
>  - Does asciidoc 7 accept the asciidoc7compatible attribute?

No.


> 
> Thanks.
> 
> 
> PS:
> 
> Junio, Stuart, here is another inconsistency between asciidoc 7 and 8.
> Please have a look at
> http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html .
> See the ASCII art above "SPECIFYING RANGES". The input
>        \  |  / \
>         \ | /   |
> produced
>    \  |  /         \ | /   |
> I.e. backslash-newline was interpreted by asciidoc 7 (or whatever you
> use to generate what is put online) as an escaped thus swallowed
> newline. But the output that I got here from asciidoc 8 (manpage as well
> as the html file) still has backslash and newline printed out.


Cheers, Stuart

[-- Attachment #2: asciidoc.patch --]
[-- Type: text/plain, Size: 1621 bytes --]

Index: asciidoc.conf
===================================================================
--- asciidoc.conf	(revision 53)
+++ asciidoc.conf	(working copy)
@@ -62,9 +62,9 @@
 __=#emphasis
 ++=#monospaced
 \##=#unquoted
-endif::asciidoc7compatible[]
 ^=#superscript
 ~=#subscript
+endif::asciidoc7compatible[]
 
 [specialwords]
 emphasizedwords=
Index: xhtml11.conf
===================================================================
--- xhtml11.conf	(revision 53)
+++ xhtml11.conf	(working copy)
@@ -22,6 +22,12 @@
 \$=\$
 `=\`
 endif::asciimath[]
+ifdef::asciidoc7compatible[]
+# Superscripts.
+\^(.+?)\^=<sup>\1</sup>
+# Subscripts.
+~(.+?)~=<sub>\1</sub>
+endif::asciidoc7compatible[]
 
 [ruler-blockmacro]
 <hr />
Index: docbook.conf
===================================================================
--- docbook.conf	(revision 53)
+++ docbook.conf	(working copy)
@@ -18,6 +18,12 @@
 [replacements]
 # Line break markup is dropped (there is no DocBook line break tag).
 (?m)^(.*)\s\+$=\1
+ifdef::asciidoc7compatible[]
+# Superscripts.
+\^(.+?)\^=<superscript>\1</superscript>
+# Subscripts.
+~(.+?)~=<subscript>\1</subscript>
+endif::asciidoc7compatible[]
 
 [ruler-blockmacro]
 # Only applies to HTML so don't output anything.
Index: html4.conf
===================================================================
--- html4.conf	(revision 53)
+++ html4.conf	(working copy)
@@ -18,6 +18,12 @@
 [replacements]
 # Line break.
 (?m)^(.*)\s\+$=\1<br />
+ifdef::asciidoc7compatible[]
+# Superscripts.
+\^(.+?)\^=<sup>\1</sup>
+# Subscripts.
+~(.+?)~=<sub>\1</sub>
+endif::asciidoc7compatible[]
 
 [ruler-blockmacro]
 <hr />

Re: asciidoc 7--8 compatibility

[Stefan Richter]

Stuart Rackham wrote:
> --- asciidoc.conf	(revision 53)
> +++ asciidoc.conf	(working copy)
> @@ -62,9 +62,9 @@
>  __=#emphasis
>  ++=#monospaced
>  \##=#unquoted
> -endif::asciidoc7compatible[]
>  ^=#superscript
>  ~=#subscript
> +endif::asciidoc7compatible[]

Could git/Documentation/asciidoc.conf just kill all the various meanings
of +, ~, ^ and make them into regular characters? In a way that works
with all versions of asciidoc?

(Frankly, using + as a special character may sound like a neat idea if
all one wants to do is to typeset poems.)
-- 
Stefan Richter
-=====-=-==- =-=- --=--
http://arcgraph.de/sr/

Re: asciidoc 7--8 compatibility

[Stuart Rackham]

Stefan Richter wrote:
> Stuart Rackham wrote:
>> --- asciidoc.conf	(revision 53)
>> +++ asciidoc.conf	(working copy)
>> @@ -62,9 +62,9 @@
>>  __=#emphasis
>>  ++=#monospaced
>>  \##=#unquoted
>> -endif::asciidoc7compatible[]
>>  ^=#superscript
>>  ~=#subscript
>> +endif::asciidoc7compatible[]
> 
> Could git/Documentation/asciidoc.conf just kill all the various meanings
> of +, ~, ^ and make them into regular characters? In a way that works
> with all versions of asciidoc?

[quotes]
^=
~=
+=

 From the AsciiDoc User Guide: "A configuration file [quotes] entry can 
be subsequently undefined by setting it to a blank value."


> 
> (Frankly, using + as a special character may sound like a neat idea if
> all one wants to do is to typeset poems.)

The rationale for the + is discussed in the AsciiDoc changelog 
(http://www.methods.co.nz/asciidoc/CHANGELOG.html). It also brings 
AsciiDoc in line with the Ruby RDoc source code documentation system syntax.


--
Stuart Rackham

Re: pull-fetch-param.txt

[Stefan Richter]

Junio C Hamano wrote:
> Stefan Richter <stefanr@s5r6.in-berlin.de> writes:
...
>> I.e. the first and second + were swallowed, but not the third one.
...
> Without looking at asciidoc 8.0 source, my guess is that it
> treats _anything_ that has two pluses on the same input line as
> quoted by some magical '+'-pair quote.   Can you try
> reformatting the original
> 
>> <refspec>::
>> 	The canonical format of a <refspec> parameter is
>> 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
>> 	by the source ref, followed by a colon `:`, followed by
>> 	the destination ref.
> 
> to something like
> 
>> <refspec>::
>> 	The canonical format of a <refspec> parameter is
>> 	`+?<src>:<dst>`; that is, an optional plus
>> 	`+`, followed
>> 	by the source ref, followed by a colon `:`, followed by
>> 	the destination ref.
> 
> and verify that conjecture?

This hack does not help. The two `+` are still absent from the manpage
(but as before, the `+` in the next paragraph is printed as desired).
-- 
Stefan Richter
-=====-=-==- =-=- --=--
http://arcgraph.de/sr/

Re: pull-fetch-param.txt

[Stefan Richter]

I wrote:
> Junio C Hamano wrote:
>> Can you try reformatting the original
>>
>>> <refspec>::
>>> 	The canonical format of a <refspec> parameter is
>>> 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
>>> 	by the source ref, followed by a colon `:`, followed by
>>> 	the destination ref.
>> to something like
>>
>>> <refspec>::
>>> 	The canonical format of a <refspec> parameter is
>>> 	`+?<src>:<dst>`; that is, an optional plus
>>> 	`+`, followed
>>> 	by the source ref, followed by a colon `:`, followed by
>>> 	the destination ref.
>> and verify that conjecture?
> 
> This hack does not help. The two `+` are still absent from the manpage
> (but as before, the `+` in the next paragraph is printed as desired).

After a few more experiments with different placements of backticks et
cetera, I found only the following variants to work with asciidoc 8:

(as mentioned, not compatible to asciidoc 7):
	`$$+$$?<src>:<dst>`; that is, an optional plus `+`, followed

(as mentioned, compatible)
	`\+?<src>:<dst>`; that is, an optional plus `+`, followed

(also OK, and this is probably the only really correct syntax)
	`\+?<src>:<dst>`; that is, an optional plus `\+`, followed

(also OK but misses the monospace formatting on the plus or on the plus
and questionmark)
	\+`?<src>:<dst>`; that is, an optional plus `+`, followed
	\+?`<src>:<dst>`; that is, an optional plus `+`, followed
	\+?`<src>:<dst>`; that is, an optional plus \+, followed
	`\+?<src>:<dst>`; that is, an optional plus +, followed

Note,
	`+``?<src>:<dst>`; that is, an optional plus `+`, followed
does _not_ work. It stops on invalid syntax in the intermediary xml
file. Also
	+\+?<src>:<dst>+; that is, an optional plus `+`, followed
or
	`+`+?<src>:<dst>+; that is, an optional plus `+`, followed
do _not_ work. They don't print what we want to see.
-- 
Stefan Richter
-=====-=-==- =-=- --=--
http://arcgraph.de/sr/

Re: pull-fetch-param.txt (was Re: [PATCH] escape tilde in Documentation/git-rev-parse.txt)

[Gerrit Pape]

On Tue, Oct 03, 2006 at 11:19:20AM +0200, Stefan Richter wrote:
> Junio C Hamano wrote:
> > It's a bit sad that asciidoc's nicer quoting features
> > are not backward compatible.
> 
> Yes, this is awkward. Here comes the next candidate for quoting.
> In pull-fetch-param.txt:
> 
> ----8<----
> <refspec>::
> 	The canonical format of a <refspec> parameter is
> 	`+?<src>:<dst>`; that is, an optional plus `+`, followed
> 	by the source ref, followed by a colon `:`, followed by
> 	the destination ref.
> +
> The remote ref that matches <src>
> is fetched, and if <dst> is not empty string, the local
> ref that matches it is fast forwarded using <src>.
> Again, if the optional plus `+` is used, the local ref
> ---->8----
> 
> "man git-fetch" and "man git-pull" show:
> ----8<----
>        <refspec>
>               The  canonical  format of a <refspec> parameter is ?<src>:<dst>;
>               that is, an optional plus, followed by the source ref,  followed
>               by a colon :, followed by the destination ref.
> 
>               The  remote  ref  that matches <src> is fetched, and if <dst> is
>               not empty string, the local ref that matches  it  is  fast  for-
>               warded  using  <src>. Again, if the optional plus + is used, the
> ---->8----

Hi, this still is a problem, at least on Debian/unstable; with asciidoc
8.2.1, the git-push(1) and git-fetch(1) man pages have this 'broken'
refspec description[0].

Additionally there're problems with callouts, whereever <n> is used to
refer to a callout list, it renders broken man pages[1], e.g.:

 $ man git-reset
 [...]
 EXAMPLES
        Undo a commit and redo
 
                $ git commit ...
                $ git reset --soft HEAD^      \fB(1)\fR
                $ edit                        \fB(2)\fR
                $ git commit -a -c ORIG_HEAD  \fB(3)\fR
            .sp \fB1. \fRThis is most often done when you remembered what you
            just committed is incomplete, or you misspelled your commit
            message, or both. Leaves working tree as it was before "reset".
 
            .br \fB2. \fRmake corrections to working tree files.
 
            .br \fB3. \fR"reset" copies the old head to .git/ORIG_HEAD; redo
            the commit by starting with its log message. If you do not need to
            edit the message further, you can give -C option instead.
 
            See also the --amend option to git-commit(1).
 
            .br
 
        Undo commits permanently
 
                $ git commit ...
                $ git reset --hard HEAD~3   \fB(1)\fR
            .sp \fB1. \fRThe last three commits (HEAD, HEAD^, and HEAD~2) were
            bad and you do not want to ever see them again. Do not do this if
            you have already given these commits to somebody else.
 
            .br
 
        Undo a commit, making it a topic branch
 [...]


Regards, Gerrit.

[0] http://bugs.debian.org/432560
[1] http://bugs.debian.org/420114

Re: pull-fetch-param.txt

[Junio C Hamano]

Gerrit Pape <pape@smarden.org> writes:

> Hi, this still is a problem, at least on Debian/unstable; with asciidoc
> 8.2.1, the git-push(1) and git-fetch(1) man pages have this 'broken'
> refspec description[0].

Quick question.  Is the build done with "make
ASCIIDOC8=YesPlease"?

Re: pull-fetch-param.txt

[Gerrit Pape]

On Thu, Jul 12, 2007 at 02:58:08PM -0700, Junio C Hamano wrote:
> Gerrit Pape <pape@smarden.org> writes:
> > Hi, this still is a problem, at least on Debian/unstable; with asciidoc
> > 8.2.1, the git-push(1) and git-fetch(1) man pages have this 'broken'
> > refspec description[0].
> 
> Quick question.  Is the build done with "make
> ASCIIDOC8=YesPlease"?

No, must have missed that.  This solves the first issue with the refspec
in git-push(1), git-fetch(1), but not the second one with callout lists.

Thanks, Gerrit.

Re: pull-fetch-param.txt

[Junio C Hamano]

Gerrit Pape <pape@smarden.org> writes:

>> Quick question.  Is the build done with "make
>> ASCIIDOC8=YesPlease"?
>
> No, must have missed that.  This solves the first issue ...
> ..., but not the second one with callout lists.

Sorry, does not reproduce for me, with asciidoc 8.2.1.  There
must be something different between our environments.

Here is an excerpt from what I get for git-reset.txt in
git-reset.1:

-- >8 --
.\"     Title: git\-reset
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.71.0 <http://docbook.sf.net/>
.\"      Date: 07/13/2007
.\"    Manual: Git Manual
.\"    Source: Git 1.5.3.rc1.4.gaf83

    ...

.SH "EXAMPLES"
.PP
Undo a commit and redo
.RS 3n
.sp
.RS 3n
.nf
$ git commit ...
$ git reset \-\-soft HEAD^      \fB(1)\fR
$ edit                        \fB(2)\fR
$ git commit \-a \-c ORIG_HEAD  \fB(3)\fR
.fi
.RE
.sp
\fB1. \fRThis is most often done when you remembered what you just committed is incomplete, or you misspelled your commit message, or both. Leaves working tree as it was before "reset".
.br
\fB2. \fRmake corrections to working tree files.
.br
\fB3. \fR"reset" copies the old head to .git/ORIG_HEAD; redo the commit by starting with its log message. If you do not need to edit the message further, you can give \-C option instead.

See also the \-\-amend option to \fBgit\-commit\fR(1).
.br
.RE
-- 8< --

and "man -l git-reset.1" seems to show the callouts just fine.

-- >8 --
 ...
EXAMPLES
       Undo a commit and redo

             $ git commit ...
             $ git reset --soft HEAD^      (1)
             $ edit                        (2)
             $ git commit -a -c ORIG_HEAD  (3)

          1. This is most often done when you remembered what you just
          committed is incomplete, or you misspelled your commit message,
          or both. Leaves working tree as it was before "reset".
          2. make corrections to working tree files.
          3. "reset" copies the old head to .git/ORIG_HEAD; redo the
          commit by starting with its log message. If you do not need to
          edit the message further, you can give -C option instead.

          See also the --amend option to git-commit(1).
-- 8< --

Re: pull-fetch-param.txt

[Gerrit Pape]

On Fri, Jul 13, 2007 at 12:17:34AM -0700, Junio C Hamano wrote:
> Gerrit Pape <pape@smarden.org> writes:
> >> Quick question.  Is the build done with "make
> >> ASCIIDOC8=YesPlease"?
> >
> > No, must have missed that.  This solves the first issue ...
> > ..., but not the second one with callout lists.
> 
> Sorry, does not reproduce for me, with asciidoc 8.2.1.  There
> must be something different between our environments.

Yes, I have docbook-xsl 1.72.0.

> Here is an excerpt from what I get for git-reset.txt in
> git-reset.1:
> 
> -- >8 --
> .\"     Title: git\-reset
> .\"    Author: 
> .\" Generator: DocBook XSL Stylesheets v1.71.0 <http://docbook.sf.net/>
> .\"      Date: 07/13/2007
> .\"    Manual: Git Manual
> .\"    Source: Git 1.5.3.rc1.4.gaf83
> 
>     ...
> 
> .SH "EXAMPLES"
> .PP
> Undo a commit and redo
> .RS 3n
> .sp
> .RS 3n
> .nf
> $ git commit ...
> $ git reset \-\-soft HEAD^      \fB(1)\fR
> $ edit                        \fB(2)\fR
> $ git commit \-a \-c ORIG_HEAD  \fB(3)\fR

I get the same with docbook-xsl 1.71.0, but with 1.72.0:

.\"     Title: git-reset
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.72.0 <http://docbook.sf.net/>
.\"      Date: 07/13/2007
.\"    Manual: Git Manual
.\"    Source: Git 1.5.3.rc0.104.g71f98
[...]
.SH "EXAMPLES"
.PP
Undo a commit and redo
.RS 4
.sp
.RS 4
.nf
$ git commit ...
$ git reset \-\-soft HEAD^      \efB(1)\efR
$ edit                        \efB(2)\efR
$ git commit \-a \-c ORIG_HEAD  \efB(3)\efR
.fi
.RE
\&.sp
\efB1. \efRThis is most often done when you remembered what you just committed is incomplete, or you misspelled your commit message, or both. Leaves working tree as it was before "reset".

\&.br
\efB2. \efRmake corrections to working tree files.

\&.br
\efB3. \efR"reset" copies the old head to .git/ORIG_HEAD; redo the commit by starting with its log message. If you do not need to edit the message further, you can give \-C option instead.


I'll check with the docbook-xsl Debian maintainer.

Thanks, Gerrit.

Re: pull-fetch-param.txt

[Gerrit Pape]

On Fri, Jul 13, 2007 at 07:48:24AM +0000, Gerrit Pape wrote:
> On Fri, Jul 13, 2007 at 12:17:34AM -0700, Junio C Hamano wrote:
> > Sorry, does not reproduce for me, with asciidoc 8.2.1.  There
> > must be something different between our environments.
> 
> Yes, I have docbook-xsl 1.72.0.

> > $ git commit \-a \-c ORIG_HEAD  \fB(3)\fR
> 
> I get the same with docbook-xsl 1.71.0, but with 1.72.0:

> $ git commit \-a \-c ORIG_HEAD  \efB(3)\efR

> I'll check with the docbook-xsl Debian maintainer.

The change in docbook-xsl was by intention, please see
 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=420114#22

Regards, Gerrit.

Re: pull-fetch-param.txt

[Junio C Hamano]

Gerrit Pape <pape@smarden.org> writes:

>> I'll check with the docbook-xsl Debian maintainer.
>
> The change in docbook-xsl was by intention, please see
>  http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=420114#22

Hmph. Where does that leave us poor users who would want to
support both 1.71 and 1.72, I wonder...

Will they have the same revert in 1.73 for that House Sign, too?

Re: pull-fetch-param.txt

[Julian Phillips]

On Fri, 20 Jul 2007, Junio C Hamano wrote:

> Gerrit Pape <pape@smarden.org> writes:
>
>>> I'll check with the docbook-xsl Debian maintainer.
>>
>> The change in docbook-xsl was by intention, please see
>>  http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=420114#22
>
> Hmph. Where does that leave us poor users who would want to
> support both 1.71 and 1.72, I wonder...
>
> Will they have the same revert in 1.73 for that House Sign, too?

It looks like they do, so perhaps we could just say that you will have 
issues building the git docs with 1.72 and ignore my last patch?

(comparing http://docbook.xml-doc.org/snapshots/xsl/manpages/utility.xsl 
which has today's date and uses . and \ against 
http://docbook.sourceforge.net/release/xsl/1.72.0/manpages/utility.xsl 
which uses U+2302 and U+2593)

-- 
Julian

  ---
Old MacDonald had an agricultural real estate tax abatement.

Re: pull-fetch-param.txt

[Junio C Hamano]

Julian Phillips <julian@quantumfyre.co.uk> writes:

> On Fri, 20 Jul 2007, Junio C Hamano wrote:
> ...
>> Hmph. Where does that leave us poor users who would want to
>> support both 1.71 and 1.72, I wonder...
>>
>> Will they have the same revert in 1.73 for that House Sign, too?
>
> It looks like they do, so perhaps we could just say that you will have
> issues building the git docs with 1.72 and ignore my last patch?

That actually sounds a very tempting thing to do, especially
considering we are past -rc2.