threads / patch / 8695

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

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

## tl;dr

10 messages between Jun 23, 2007 and Jun 24, 2007. Diffs are folded; open one to read it.

replies: 9people: 3as markdown or json

Jason Sewall· Jun 23, 2007, 23:51 UTC · lore
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(-)
Show changes to 2 files +5 −6

Documentation/git-bundle.txt, Documentation/git-daemon.txt

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
Johannes Schindelin· Jun 24, 2007, 00:11 UTC · re: Jason Sewall · lore

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

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

Jason Sewall· Jun 24, 2007, 00:22 UTC · re: Johannes Schindelin · lore

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

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

Johannes Schindelin· Jun 24, 2007, 00:55 UTC · re: Jason Sewall · lore

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

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

Junio C Hamano· Jun 24, 2007, 10:07 UTC · re: Jason Sewall · lore

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

"Jason Sewall" <jasonsewall@gmail.com> writes:
Show 12 quoted lines
> 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.

Jason Sewall· Jun 24, 2007, 17:31 UTC · re: Junio C Hamano · lore

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

On 6/24/07, Junio C Hamano <gitster@pobox.com> wrote:
Show 25 quoted lines
> "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.
Show 9 quoted lines
> 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
Jason Sewall· Jun 24, 2007, 21:40 UTC · re: Jason Sewall · lore

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

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

Junio C Hamano· Jun 24, 2007, 22:18 UTC · re: Jason Sewall · lore

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

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

Jason Sewall· Jun 24, 2007, 23:33 UTC · re: Junio C Hamano · lore

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

On 6/24/07, Junio C Hamano <gitster@pobox.com> wrote:
Show 6 quoted lines
> "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).

Show 5 quoted lines
> > 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
Junio C Hamano· Jun 24, 2007, 01:01 UTC · re: Jason Sewall · lore

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

Jason Sewall <jasonsewall@gmail.com> writes:
Show 13 quoted lines
> 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.

← back to recent threads