From: Jason Sewall <jasonsewall@gmail.com>
Date: Sun, 24 Jun 2007 17:31:33 GMT
Subject: Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation
Message-ID: <31e9dd080706241031m64c6be37sb4437036fda543c9@mail.gmail.com>
In-Reply-To: <7vbqf5wtrb.fsf@assigned-by-dhcp.cox.net>

On 6/24/07, Junio C Hamano <gitster@pobox.com> wrote:
> "Jason Sewall" <jasonsewall@gmail.com> writes:
>
> > 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?

Kinda. Replacing {tilde} with ~ actually causes asciidoc to fail while
processing the file; that tilde is 'unmatched' and ends up crossing
another tag or somesuch.

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

The escaped tilde works fine.

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

I clearly need to read up on Asciidoc formatting directives before I
could do that with confidence, but I look over it today and see what I
can do.

Jason