"Jason Sewall" [off-list ref] writes:
On 6/23/07, Johannes Schindelin [off-list ref] wrote:
quoted
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.
On 6/24/07, Junio C Hamano [off-list ref] wrote:
"Jason Sewall" [off-list ref] writes:
quoted
On 6/23/07, Johannes Schindelin [off-list ref] wrote:
quoted
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
On 6/24/07, Jason Sewall [off-list ref] wrote:
On 6/24/07, Junio C Hamano [off-list ref] wrote:
quoted
"Jason Sewall" [off-list ref] writes:
quoted
On 6/23/07, Johannes Schindelin [off-list ref] wrote:
quoted
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.
quoted
- If it breaks, does it fix the breakage if you prefix the "~"
with a backslash, instead of using {tilde}?
The escaped tilde works fine.
quoted
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