Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 24, 2007, 10:07 UTC
Message-ID: <7vbqf5wtrb.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <31e9dd080706231722v760b5a0cnc31e24b83deafb90@mail.gmail.com>

"Jason Sewall" <jasonsewall@gmail.com> writes:

Show 12 quoted lines

> On 6/23/07, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
>
>> I just checked with my copy of asciidoc, though, and there is no mangling
>> going on, at least in git-bundle.html (which is the only file I checked).
>> My asciidoc is version 8.2.1. What is yours?
>
> I've got 8.1.0; perhaps that's the problem. I wasn't so surprised to
> hear the asciidoc 7 and 8 don't get along, but I'm surprised to see
> that 8.1 and 8.2 are so different.
>
> Anyway, 8.1.0 is apparently what's in Fedora 7 (the distro I'm using
> right now) so it might be worth hanging on to the patch.

FWIW, 7.1.2, 8.2.1 and 7.0.2 all seem to be Ok (the last one is used to format the pages in html and man branches of git.git). It is a bit annoying having to use name\~num at some places and no backslash all others.

Two requests:

 - Documentation/git-rev-parse.txt has '{tilde}<n>'.  If you
   replace that {tilde} with a "~", how does your AsciiDoc
   format it?  Do you see the same breakage?

 - If it breaks, does it fix the breakage if you prefix the "~"
   with a backslash, instead of using {tilde}?

If the answer to both questions are "yes", then perhaps we should get rid of the {tilde} macro we define in Documentation/asciidoc.conf file, and use your "\~" solution everywhere.

Also do you see any pattern? It does not seem that all the "master~3" are broken for you but only some. If your commit message can describe when quoting is needed, that would help people who would modify the documentation in the future.