{"thread":{"id":"8695","subject":"[PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","startedAt":"2007-06-23T23:51:13Z","lastAt":"2007-06-24T23:33:22Z","messageCount":10,"participants":["Jason Sewall","Johannes Schindelin","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"45633","messageId":"11826426733115-git-send-email-jasonsewall@gmail.com","threadId":"8695","inReplyTo":null,"subject":"[PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Jason Sewall","fromEmail":"jasonsewall@gmail.com","sentAt":"2007-06-23T23:51:13Z","receivedAt":"2007-06-23T23:51:13Z","isPatch":true,"sender":{"key":"jasonsewall@gmail.com","avatar":null},"body":"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.\n\nSigned-off-by: Jason Sewall \n---\n 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!\n\n Documentation/git-bundle.txt | 8 ++++----\n Documentation/git-daemon.txt | 2 +-\n 2 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 5051e2b..d89f350 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -61,7 +61,7 @@ unbundle ::\n [git-rev-list-args...]::\n A list of arguments, acceptable to git-rev-parse and\n git-rev-list, that specify the specific objects and references\n- to transport. For example, \"master~10..master\" causes the\n+ to transport. For example, \"master\\~10..master\" causes the\n current master reference to be packaged along with all objects\n added since its 10th ancestor commit. There is no explicit\n limit to the number of references and objects that may be\n@@ -80,12 +80,12 @@ SPECIFYING REFERENCES\n\n git-bundle will only package references that are shown by\n git-show-ref: this includes heads, tags, and remote heads. References\n-such as master~1 cannot be packaged, but are perfectly suitable for\n+such as master\\~1 cannot be packaged, but are perfectly suitable for\n defining the basis. More than one reference may be packaged, and more\n than one basis can be specified. The objects packaged are those not\n contained in the union of the given bases. Each basis can be\n-specified explicitly (e.g., ^master~10), or implicitly (e.g.,\n-master~10..master, master --since=10.days.ago).\n+specified explicitly (e.g., ^master\\~10), or implicitly (e.g.,\n+master\\~10..master, master --since=10.days.ago).\n\n It is very important that the basis used be held by the destination.\n It is okay to err on the side of conservatism, causing the bundle file\ndiff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt\nindex 4b30b18..3f9cec5 100644\n--- a/Documentation/git-daemon.txt\n+++ b/Documentation/git-daemon.txt\n@@ -98,7 +98,7 @@ OPTIONS\n \t--verbose, thus by default only error conditions will be logged.\n\n --user-path, --user-path=path::\n-\tAllow ~user notation to be used in requests. When\n+\tAllow \\~user notation to be used in requests. When\n \tspecified with no parameter, requests to\n \tgit://host/~alice/foo is taken as a request to access\n \t'foo' repository in the home directory of user `alice`.\n--\n1.5.2.1.280.g38570\n"},{"id":"45634","messageId":"Pine.LNX.4.64.0706240109540.4059@racer.site","threadId":"8695","inReplyTo":"11826426733115-git-send-email-jasonsewall@gmail.com","subject":"Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-06-24T00:11:30Z","receivedAt":"2007-06-24T00:11:30Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sat, 23 Jun 2007, Jason Sewall wrote:\n\n> My second attempt at submitting a patch, this time with git-send-email \n> rather than copy-and-paste into gmail; let me know if this is a \n> reasonably presented patch. It is truly trivial, but getting those docs \n> cleaned up is important!\n\nApplies cleanly (although the commit message now consists of one single \nlong line).\n\nI just checked with my copy of asciidoc, though, and there is no mangling \ngoing on, at least in git-bundle.html (which is the only file I checked). \nMy asciidoc is version 8.2.1. What is yours?\n\nCiao,\nDscho\n"},{"id":"45635","messageId":"31e9dd080706231722v760b5a0cnc31e24b83deafb90@mail.gmail.com","threadId":"8695","inReplyTo":"Pine.LNX.4.64.0706240109540.4059@racer.site","subject":"Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Jason Sewall","fromEmail":"jasonsewall@gmail.com","sentAt":"2007-06-24T00:22:00Z","receivedAt":"2007-06-24T00:22:00Z","isPatch":true,"sender":{"key":"jasonsewall@gmail.com","avatar":null},"body":"On 6/23/07, Johannes Schindelin wrote:\n\n> I just checked with my copy of asciidoc, though, and there is no mangling\n> going on, at least in git-bundle.html (which is the only file I checked).\n> My asciidoc is version 8.2.1. What is yours?\n\nI've got 8.1.0; perhaps that's the problem. I wasn't so surprised to\nhear the asciidoc 7 and 8 don't get along, but I'm surprised to see\nthat 8.1 and 8.2 are so different.\n\nAnyway, 8.1.0 is apparently what's in Fedora 7 (the distro I'm using\nright now) so it might be worth hanging on to the patch.\n\nThanks for your help,\nJason\n"},{"id":"45636","messageId":"Pine.LNX.4.64.0706240154090.4059@racer.site","threadId":"8695","inReplyTo":"31e9dd080706231722v760b5a0cnc31e24b83deafb90@mail.gmail.com","subject":"Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-06-24T00:55:11Z","receivedAt":"2007-06-24T00:55:11Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sat, 23 Jun 2007, Jason Sewall wrote:\n\n> Anyway, 8.1.0 is apparently what's in Fedora 7 (the distro I'm using \n> right now) so it might be worth hanging on to the patch.\n\nOh yes, definitely, if it fixes a bug that you encountered! I was just \nasking out of curiousity; I did not think that the patch was not \nnecessary...\n\nCiao,\nDscho\n"},{"id":"45637","messageId":"7vhcoy2mj3.fsf@assigned-by-dhcp.cox.net","threadId":"8695","inReplyTo":"11826426733115-git-send-email-jasonsewall@gmail.com","subject":"Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-06-24T01:01:36Z","receivedAt":"2007-06-24T01:01:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jason Sewall writes:\n\n> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\n> index 5051e2b..d89f350 100644\n> --- a/Documentation/git-bundle.txt\n> +++ b/Documentation/git-bundle.txt\n> @@ -61,7 +61,7 @@ unbundle ::\n> [git-rev-list-args...]::\n> A list of arguments, acceptable to git-rev-parse and\n> git-rev-list, that specify the specific objects and references\n> - to transport. For example, \"master~10..master\" causes the\n> + to transport. For example, \"master\\~10..master\" causes the\n> current master reference to be packaged along with all objects\n> added since its 10th ancestor commit. There is no explicit\n> limit to the number of references and objects that may be\n\nWe seem to have {tilde} defined in Documentation/asciidoc.conf.\nI wonder which is better. We should pick one that gives more\nreasonable format, and is less susceptible to differences\nbetween AsciiDoc 7 and 8.\n"},{"id":"45657","messageId":"7vbqf5wtrb.fsf@assigned-by-dhcp.cox.net","threadId":"8695","inReplyTo":"31e9dd080706231722v760b5a0cnc31e24b83deafb90@mail.gmail.com","subject":"Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-06-24T10:07:20Z","receivedAt":"2007-06-24T10:07:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jason Sewall\" writes:\n\n> On 6/23/07, Johannes Schindelin wrote:\n>\n>> I just checked with my copy of asciidoc, though, and there is no mangling\n>> going on, at least in git-bundle.html (which is the only file I checked).\n>> My asciidoc is version 8.2.1. What is yours?\n>\n> I've got 8.1.0; perhaps that's the problem. I wasn't so surprised to\n> hear the asciidoc 7 and 8 don't get along, but I'm surprised to see\n> that 8.1 and 8.2 are so different.\n>\n> Anyway, 8.1.0 is apparently what's in Fedora 7 (the distro I'm using\n> right now) so it might be worth hanging on to the patch.\n\nFWIW, 7.1.2, 8.2.1 and 7.0.2 all seem to be Ok (the last one is\nused to format the pages in html and man branches of git.git).\nIt is a bit annoying having to use name\\~num at some places and\nno backslash all others.\n\nTwo requests:\n\n - Documentation/git-rev-parse.txt has '{tilde}'. If you\n replace that {tilde} with a \"~\", how does your AsciiDoc\n format it? Do you see the same breakage?\n\n - If it breaks, does it fix the breakage if you prefix the \"~\"\n with a backslash, instead of using {tilde}?\n\nIf the answer to both questions are \"yes\", then perhaps we\nshould get rid of the {tilde} macro we define in \nDocumentation/asciidoc.conf file, and use your \"\\~\" solution\neverywhere.\n\nAlso do you see any pattern? It does not seem that all the\n\"master~3\" are broken for you but only some. If your commit\nmessage can describe when quoting is needed, that would help\npeople who would modify the documentation in the future.\n"},{"id":"45679","messageId":"31e9dd080706241031m64c6be37sb4437036fda543c9@mail.gmail.com","threadId":"8695","inReplyTo":"7vbqf5wtrb.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Jason Sewall","fromEmail":"jasonsewall@gmail.com","sentAt":"2007-06-24T17:31:33Z","receivedAt":"2007-06-24T17:31:33Z","isPatch":true,"sender":{"key":"jasonsewall@gmail.com","avatar":null},"body":"On 6/24/07, Junio C Hamano wrote:\n> \"Jason Sewall\" writes:\n>\n> > On 6/23/07, Johannes Schindelin wrote:\n> >\n> >> I just checked with my copy of asciidoc, though, and there is no mangling\n> >> going on, at least in git-bundle.html (which is the only file I checked).\n> >> My asciidoc is version 8.2.1. What is yours?\n> >\n> > I've got 8.1.0; perhaps that's the problem. I wasn't so surprised to\n> > hear the asciidoc 7 and 8 don't get along, but I'm surprised to see\n> > that 8.1 and 8.2 are so different.\n> >\n> > Anyway, 8.1.0 is apparently what's in Fedora 7 (the distro I'm using\n> > right now) so it might be worth hanging on to the patch.\n>\n> FWIW, 7.1.2, 8.2.1 and 7.0.2 all seem to be Ok (the last one is\n> used to format the pages in html and man branches of git.git).\n> It is a bit annoying having to use name\\~num at some places and\n> no backslash all others.\n>\n> Two requests:\n>\n> - Documentation/git-rev-parse.txt has '{tilde}'. If you\n> replace that {tilde} with a \"~\", how does your AsciiDoc\n> format it? Do you see the same breakage?\n\nKinda. Replacing {tilde} with ~ actually causes asciidoc to fail while\nprocessing the file; that tilde is 'unmatched' and ends up crossing\nanother tag or somesuch.\n\n> - If it breaks, does it fix the breakage if you prefix the \"~\"\n> with a backslash, instead of using {tilde}?\n\nThe escaped tilde works fine.\n\n> If the answer to both questions are \"yes\", then perhaps we\n> should get rid of the {tilde} macro we define in\n> Documentation/asciidoc.conf file, and use your \"\\~\" solution\n> everywhere.\n>\n> Also do you see any pattern? It does not seem that all the\n> \"master~3\" are broken for you but only some. If your commit\n> message can describe when quoting is needed, that would help\n> people who would modify the documentation in the future.\n\nI clearly need to read up on Asciidoc formatting directives before I\ncould do that with confidence, but I look over it today and see what I\ncan do.\n\nJason\n"},{"id":"45696","messageId":"31e9dd080706241440s21025c26p68fda1595d531f1e@mail.gmail.com","threadId":"8695","inReplyTo":"31e9dd080706241031m64c6be37sb4437036fda543c9@mail.gmail.com","subject":"Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Jason Sewall","fromEmail":"jasonsewall@gmail.com","sentAt":"2007-06-24T21:40:01Z","receivedAt":"2007-06-24T21:40:01Z","isPatch":true,"sender":{"key":"jasonsewall@gmail.com","avatar":null},"body":"On 6/24/07, Jason Sewall wrote:\n> On 6/24/07, Junio C Hamano wrote:\n> > \"Jason Sewall\" writes:\n> >\n> > > On 6/23/07, Johannes Schindelin wrote:\n> > >\n> > >> I just checked with my copy of asciidoc, though, and there is no mangling\n> > >> going on, at least in git-bundle.html (which is the only file I checked).\n> > >> My asciidoc is version 8.2.1. What is yours?\n> > >\n> > > I've got 8.1.0; perhaps that's the problem. I wasn't so surprised to\n> > > hear the asciidoc 7 and 8 don't get along, but I'm surprised to see\n> > > that 8.1 and 8.2 are so different.\n> > >\n> > > Anyway, 8.1.0 is apparently what's in Fedora 7 (the distro I'm using\n> > > right now) so it might be worth hanging on to the patch.\n> >\n> > FWIW, 7.1.2, 8.2.1 and 7.0.2 all seem to be Ok (the last one is\n> > used to format the pages in html and man branches of git.git).\n> > It is a bit annoying having to use name\\~num at some places and\n> > no backslash all others.\n> >\n> > Two requests:\n> >\n> > - Documentation/git-rev-parse.txt has '{tilde}'. If you\n> > replace that {tilde} with a \"~\", how does your AsciiDoc\n> > format it? Do you see the same breakage?\n>\n> Kinda. Replacing {tilde} with ~ actually causes asciidoc to fail while\n> processing the file; that tilde is 'unmatched' and ends up crossing\n> another tag or somesuch.\n>\n> > - If it breaks, does it fix the breakage if you prefix the \"~\"\n> > with a backslash, instead of using {tilde}?\n>\n> The escaped tilde works fine.\n>\n> > If the answer to both questions are \"yes\", then perhaps we\n> > should get rid of the {tilde} macro we define in\n> > Documentation/asciidoc.conf file, and use your \"\\~\" solution\n> > everywhere.\n> >\n> > Also do you see any pattern? It does not seem that all the\n> > \"master~3\" are broken for you but only some. If your commit\n> > message can describe when quoting is needed, that would help\n> > people who would modify the documentation in the future.\n>\n> I clearly need to read up on Asciidoc formatting directives before I\n> could do that with confidence, but I look over it today and see what I\n> can do.\n\nFrankly, I don't see any pattern. The git documentation is very fond\nof ~ and ^, naturally, and these are inline delimiters in Asciidoc.\nSometimes the places these appear in are unquoted, sometimes\ndouble-quoted, grave-quoted, or single-quoted; any of these can cause\n and tags in the html output.\n\nI'd suggest that we put all inline revspecs inside $$...$$; this\n\"inline passthrough\" quote obeys outside quoting, and it's what\nAsciiMathML uses to avoid fighting reserved characters. Since ~, ^, {,\n}, [, ] and more all appear with great frequency in refspecs, this\nwill save us a lot of escape characters.\n\nThere's also a few places where ~ appears in a path name; perhaps we\ncould put $$...$$ around paths too.\n\nIs there a documentation 'style' file or something like that for git?\nSomething like that might be useful to help solve this sort of\nproblem; in addition to unintentional formatting problems like the one\nunder discussion, there doesn't seem to be a consensus on what sort of\nquoting to use for special literal text, like git commands, refspecs,\npathnames, etc. - `, ', and \" abound interchangeably.\n\nJason\n\nP.S. I got smarter about how to find some of these formatting problems\nand have found some more 'doc bugs' that I'll put into a patch once\nwe've decided how to handle this stuff\n"},{"id":"45700","messageId":"7v8xa9q9mb.fsf@assigned-by-dhcp.cox.net","threadId":"8695","inReplyTo":"31e9dd080706241440s21025c26p68fda1595d531f1e@mail.gmail.com","subject":"Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-06-24T22:18:52Z","receivedAt":"2007-06-24T22:18:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jason Sewall\" writes:\n\n> I'd suggest that we put all inline revspecs inside $$...$$; this\n> \"inline passthrough\" quote obeys outside quoting,...\n\nDoes that work with AsciiDoc 7?\n\n> Is there a documentation 'style' file or something like that for git?\n\nWell, there isn't one as nobody really knows AsciiDoc well\nenough, and actually my message was to con you into writing one ;-).\n"},{"id":"45717","messageId":"31e9dd080706241633v38c090f7m6302e32145fe8db7@mail.gmail.com","threadId":"8695","inReplyTo":"7v8xa9q9mb.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH][RESEND] Escape some tilde characters causing spurious subscripts in documentation","fromName":"Jason Sewall","fromEmail":"jasonsewall@gmail.com","sentAt":"2007-06-24T23:33:22Z","receivedAt":"2007-06-24T23:33:22Z","isPatch":true,"sender":{"key":"jasonsewall@gmail.com","avatar":null},"body":"On 6/24/07, Junio C Hamano wrote:\n> \"Jason Sewall\" writes:\n>\n> > I'd suggest that we put all inline revspecs inside $$...$$; this\n> > \"inline passthrough\" quote obeys outside quoting,...\n>\n> Does that work with AsciiDoc 7?\n\nI just downloaded AsciiDoc-7.2.1 and it seems to work fine (there are\nsome warnings missing tag definitions, but that's something else, I'm\npretty sure).\n\n> > Is there a documentation 'style' file or something like that for git?\n>\n> Well, there isn't one as nobody really knows AsciiDoc well\n> enough, and actually my message was to con you into writing one ;-).\n>\nI was afraid you were going to say that :)\n\nI've wanted to contribute to this project for a while now, but I just\nhaven't had the time to familiarize myself with the codebase enough to\nhelp out; I don't have to tell you that there's a lot of code in git,\nand a fair amount of it is production-grade\n'make-it-fast-screw-legibility' stuff that I'm not so good at reading\nyet :p\n\nSo sure, I'll try to help out with this documentation stuff. I think\ndeveloping a style file and making the git docs conform to it would be\na good start.\n\nTo begin with:\n1. What versions of Asciidoc are we interested in targeting? 7.0.2 and\nup, or something else?\n2. I think we should put all of the path, revspec stuff, and command\nexamples in monospace (grave quotes or plus delimiters) rather than\nemphasis (single quotes) or what have you. This will make them\nconsistent with the way they are formatted in blocks. What's the\nconsensus?\n\nThe almost-markup-free nature of asciidoc does us more harm than good\nin this particular case, since a little abstraction like\nHEAD^^ or whatever would let us just convert\neverything and fight about presentation later.\n\nJason\n"}]}