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

On 6/24/07, Junio C Hamano [off-list ref] wrote:

"Jason Sewall" [off-list ref] writes:

quoted

I'd suggest that we put all inline revspecs inside $$...$$; this
"inline passthrough" quote  obeys outside quoting,...

Does that work with AsciiDoc 7?

I just downloaded AsciiDoc-7.2.1 and it seems to work fine (there are
some warnings missing tag definitions, but that's something else, I'm
pretty sure).

quoted

Is there a documentation 'style' file or something like that for git?

Well, there isn't one as nobody really knows AsciiDoc well
enough, and actually my message was to con you into writing one ;-).

I was afraid you were going to say that :)

I've wanted to contribute to this project for a while now, but I just
haven't had the time to familiarize myself with the codebase enough to
help out; I don't have to tell you that there's a lot of code in git,
and a fair amount of it is production-grade
'make-it-fast-screw-legibility' stuff that I'm not so good at reading
yet :p

So sure, I'll try to help out with this documentation stuff. I think
developing a style file and making the git docs conform to it would be
a good start.

To begin with:
1. What versions of Asciidoc are we interested in targeting? 7.0.2 and
up, or something else?
2. I think we should put all of the path, revspec stuff, and command
examples in monospace (grave quotes or plus delimiters) rather than
emphasis (single quotes) or what have you. This will make them
consistent with the way they are formatted in blocks. What's the
consensus?

The almost-markup-free nature of asciidoc does us more harm than good
in this particular case, since a little abstraction like
<revspec>HEAD^^</revspec> or whatever would let us just convert
everything and fight about presentation later.

Jason