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

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

[Jason Sewall]

A few unescaped tilde characters were causing long parts of the html documentation to be formatted as footnotes. This patch fixes them; I think I found all of them, but no promises.

Signed-off-by: Jason Sewall <jasonsewall@gmail.com>
---
 My second attempt at submitting a patch, this time with git-send-email rather than copy-and-paste into gmail; let me know if this is a reasonably presented patch. It is truly  trivial, but getting those docs cleaned up is important!

 Documentation/git-bundle.txt |    8 ++++----
 Documentation/git-daemon.txt |    2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 5051e2b..d89f350 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -61,7 +61,7 @@ unbundle <file>::
 [git-rev-list-args...]::
        A list of arguments, acceptable to git-rev-parse and
        git-rev-list, that specify the specific objects and references
-       to transport.  For example, "master~10..master" causes the
+       to transport.  For example, "master\~10..master" causes the
        current master reference to be packaged along with all objects
        added since its 10th ancestor commit.  There is no explicit
        limit to the number of references and objects that may be
@@ -80,12 +80,12 @@ SPECIFYING REFERENCES

 git-bundle will only package references that are shown by
 git-show-ref: this includes heads, tags, and remote heads.  References
-such as master~1 cannot be packaged, but are perfectly suitable for
+such as master\~1 cannot be packaged, but are perfectly suitable for
 defining the basis.  More than one reference may be packaged, and more
 than one basis can be specified.  The objects packaged are those not
 contained in the union of the given bases.  Each basis can be
-specified explicitly (e.g., ^master~10), or implicitly (e.g.,
-master~10..master, master --since=10.days.ago).
+specified explicitly (e.g., ^master\~10), or implicitly (e.g.,
+master\~10..master, master --since=10.days.ago).

 It is very important that the basis used be held by the destination.
 It is okay to err on the side of conservatism, causing the bundle file
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index 4b30b18..3f9cec5 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -98,7 +98,7 @@ OPTIONS
 	--verbose, thus by default only error conditions will be logged.

 --user-path, --user-path=path::
-	Allow ~user notation to be used in requests.  When
+	Allow \~user notation to be used in requests.  When
 	specified with no parameter, requests to
 	git://host/~alice/foo is taken as a request to access
 	'foo' repository in the home directory of user `alice`.
--
1.5.2.1.280.g38570

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

[Johannes Schindelin]

Hi,

On Sat, 23 Jun 2007, Jason Sewall wrote:

>  My second attempt at submitting a patch, this time with git-send-email 
> rather than copy-and-paste into gmail; let me know if this is a 
> reasonably presented patch. It is truly trivial, but getting those docs 
> cleaned up is important!

Applies cleanly (although the commit message now consists of one single 
long line).

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?

Ciao,
Dscho

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

[Jason Sewall]

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.

Thanks for your help,
Jason

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

[Johannes Schindelin]

Hi,

On Sat, 23 Jun 2007, Jason Sewall wrote:

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

Oh yes, definitely, if it fixes a bug that you encountered! I was just 
asking out of curiousity; I did not think that the patch was not 
necessary...

Ciao,
Dscho

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

[Junio C Hamano]

"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?

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

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

[Jason Sewall]

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

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

[Jason Sewall]

On 6/24/07, Jason Sewall <jasonsewall@gmail.com> wrote:
> 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.

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

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

[Junio C Hamano]

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

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

Does that work with AsciiDoc 7?

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

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

[Jason Sewall]

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

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

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

[Junio C Hamano]

Jason Sewall <jasonsewall@gmail.com> writes:

> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
> index 5051e2b..d89f350 100644
> --- a/Documentation/git-bundle.txt
> +++ b/Documentation/git-bundle.txt
> @@ -61,7 +61,7 @@ unbundle <file>::
>  [git-rev-list-args...]::
>         A list of arguments, acceptable to git-rev-parse and
>         git-rev-list, that specify the specific objects and references
> -       to transport.  For example, "master~10..master" causes the
> +       to transport.  For example, "master\~10..master" causes the
>         current master reference to be packaged along with all objects
>         added since its 10th ancestor commit.  There is no explicit
>         limit to the number of references and objects that may be

We seem to have {tilde} defined in Documentation/asciidoc.conf.
I wonder which is better.  We should pick one that gives more
reasonable format, and is less susceptible to differences
between AsciiDoc 7 and 8.