On 6/24/07, Jason Sewall <jasonsewall@xxxxxxxxx> wrote:
On 6/24/07, Junio C Hamano <gitster@xxxxxxxxx> wrote:
> "Jason Sewall" <jasonsewall@xxxxxxxxx> writes:
>
> > On 6/23/07, Johannes Schindelin <Johannes.Schindelin@xxxxxx> 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.
Frankly, I don't see any pattern. The git documentation is very fond
of ~ and ^, naturally, and these are inline delimiters in Asciidoc.
Sometimes the places these appear in are unquoted, sometimes
double-quoted, grave-quoted, or single-quoted; any of these can cause
<sub> and <sup> tags in the html output.
I'd suggest that we put all inline revspecs inside $$...$$; this
"inline passthrough" quote obeys outside quoting, and it's what
AsciiMathML uses to avoid fighting reserved characters. Since ~, ^, {,
}, [, ] and more all appear with great frequency in refspecs, this
will save us a lot of escape characters.
There's also a few places where ~ appears in a path name; perhaps we
could put $$...$$ around paths too.
Is there a documentation 'style' file or something like that for git?
Something like that might be useful to help solve this sort of
problem; in addition to unintentional formatting problems like the one
under discussion, there doesn't seem to be a consensus on what sort of
quoting to use for special literal text, like git commands, refspecs,
pathnames, etc. - `, ', and " abound interchangeably.
Jason
P.S. I got smarter about how to find some of these formatting problems
and have found some more 'doc bugs' that I'll put into a patch once
we've decided how to handle this stuff
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
