{"thread":{"id":"37760","subject":"[PATCH] doc: fix 'git status --help' character quoting","startedAt":"2014-10-19T14:17:15Z","lastAt":"2014-10-21T22:08:53Z","messageCount":9,"participants":["Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"250828","messageId":"1413728235-1504-1-git-send-email-philipoakley@iee.org","threadId":"37760","inReplyTo":null,"subject":"[PATCH] doc: fix 'git status --help' character quoting","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-19T14:17:15Z","receivedAt":"2014-10-19T14:17:15Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Correct backtick quoting for some of the modification states to give\nconsistent web rendering.\n\nWhile at it, use 00 for ASCII NUL to avoid any confusion with the letter O.\n\nSigned-off-by: Philip Oakley \n---\n\nNoticed when reviewing a stackoverflow problem where the OP actually\ndesired to just list those files with merge indicators present.\n---\n Documentation/git-status.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex def635f..1c01d3ac 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -116,7 +116,7 @@ In the short-format, the status of each path is shown as\n \n where `PATH1` is the path in the `HEAD`, and the \" `-> PATH2`\" part is\n shown only when `PATH1` corresponds to a different path in the\n-index/worktree (i.e. the file is renamed). The 'XY' is a two-letter\n+index/worktree (i.e. the file is renamed). The `XY` is a two-letter\n status code.\n \n The fields (including the `->`) are separated from each other by a\n@@ -125,7 +125,7 @@ characters, that field will be quoted in the manner of a C string\n literal: surrounded by ASCII double quote (34) characters, and with\n interior special characters backslash-escaped.\n \n-For paths with merge conflicts, `X` and 'Y' show the modification\n+For paths with merge conflicts, `X` and `Y` show the modification\n states of each side of the merge. For paths that do not have merge\n conflicts, `X` shows the status of the index, and `Y` shows the status\n of the work tree. For untracked paths, `XY` are `??`. Other status\n@@ -189,7 +189,7 @@ There is also an alternate -z format recommended for machine parsing. In\n that format, the status field is the same, but some other things\n change. First, the '\\->' is omitted from rename entries and the field\n order is reversed (e.g 'from \\-> to' becomes 'to from'). Second, a NUL\n-(ASCII 0) follows each filename, replacing space as a field separator\n+(ASCII 00) follows each filename, replacing space as a field separator\n and the terminating newline (but a space still separates the status\n field from the first filename). Third, filenames containing special\n characters are not specially formatted; no quoting or\n-- \n1.9.4.msysgit.0\n"},{"id":"250834","messageId":"xmqqwq7vr91j.fsf@gitster.dls.corp.google.com","threadId":"37760","inReplyTo":"1413728235-1504-1-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH] doc: fix 'git status --help' character quoting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-19T22:26:00Z","receivedAt":"2014-10-19T22:26:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> Correct backtick quoting for some of the modification states to give\n> consistent web rendering.\n\nThis is to match the way how \"XY PATH1 -> PATH2\" is typeset, I\npresume. Some in the body text are already `XY` to match, but some\nothers are not, and you are fixing them, all of which look good.\n\n> While at it, use 00 for ASCII NUL to avoid any confusion with the letter O.\n\nI do not think this is particularly a good change. We try to follow\nthe convention of spelling ASCII value in decimal (e.g. \"ASCII\ndouble quote (34)\"), and \"00\" is not the way how you usually spell a\nnumber in decimal. Existing description is perfectly fine; there is\nno risk for anybody to mistake \"O\" (oh) as part of digits, whether\nyou use decimal or hexadecimal.\n\nIf you have an aversion to mentioning ASCII when clarifying which\ncharacter we talk about, you could of course do s/ASCII 0/'\\0'/ but\nI do not know if that is an improvement.\n\nThanks.\n\n>\n> Signed-off-by: Philip Oakley \n> ---\n>\n> Noticed when reviewing a stackoverflow problem where the OP actually\n> desired to just list those files with merge indicators present.\n> ---\n> Documentation/git-status.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\n> index def635f..1c01d3ac 100644\n> --- a/Documentation/git-status.txt\n> +++ b/Documentation/git-status.txt\n> @@ -116,7 +116,7 @@ In the short-format, the status of each path is shown as\n> \n> where `PATH1` is the path in the `HEAD`, and the \" `-> PATH2`\" part is\n> shown only when `PATH1` corresponds to a different path in the\n> -index/worktree (i.e. the file is renamed). The 'XY' is a two-letter\n> +index/worktree (i.e. the file is renamed). The `XY` is a two-letter\n> status code.\n> \n> The fields (including the `->`) are separated from each other by a\n> @@ -125,7 +125,7 @@ characters, that field will be quoted in the manner of a C string\n> literal: surrounded by ASCII double quote (34) characters, and with\n> interior special characters backslash-escaped.\n> \n> -For paths with merge conflicts, `X` and 'Y' show the modification\n> +For paths with merge conflicts, `X` and `Y` show the modification\n> states of each side of the merge. For paths that do not have merge\n> conflicts, `X` shows the status of the index, and `Y` shows the status\n> of the work tree. For untracked paths, `XY` are `??`. Other status\n> @@ -189,7 +189,7 @@ There is also an alternate -z format recommended for machine parsing. In\n> that format, the status field is the same, but some other things\n> change. First, the '\\->' is omitted from rename entries and the field\n> order is reversed (e.g 'from \\-> to' becomes 'to from'). Second, a NUL\n> -(ASCII 0) follows each filename, replacing space as a field separator\n> +(ASCII 00) follows each filename, replacing space as a field separator\n> and the terminating newline (but a space still separates the status\n> field from the first filename). Third, filenames containing special\n> characters are not specially formatted; no quoting or\n"},{"id":"250850","messageId":"8D139BC1FB1E4335B4375FB0F056BB0B@PhilipOakley","threadId":"37760","inReplyTo":"xmqqwq7vr91j.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: fix 'git status --help' character quoting","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-20T10:46:30Z","receivedAt":"2014-10-20T10:46:30Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n>\n>> Correct backtick quoting for some of the modification states to give\n>> consistent web rendering.\n>\n> This is to match the way how \"XY PATH1 -> PATH2\" is typeset, I\n> presume. Some in the body text are already `XY` to match, but some\n> others are not,\n> and you are fixing them, all of which look good.\n\nDo you need me to add this to the commit message?\n\n>\n>> While at it, use 00 for ASCII NUL to avoid any confusion with the \n>> letter O.\n>\n> I do not think this is particularly a good change. We try to follow\n> the convention of spelling ASCII value in decimal (e.g. \"ASCII\n> double quote (34)\"), and \"00\" is not the way how you usually spell a\n> number in decimal. Existing description is perfectly fine;\n\n> there is\n> no risk for anybody to mistake \"O\" (oh) as part of digits, whether\n> you use decimal or hexadecimal.\n\nThe reason I proposed the change is because on the web view, on my \nmachine, I questioned whether the specially formatted character \n(remember its quotation is consumed by ascidoc) looked too much like an \nOh, so I specially checked on the original .txt to see if it was correct \nthere, which led me to the proposal for '00' in this case.\n\nI'd be just as happy with a single zero, as long as it's distinct from O \n(as you probably know, in the depths of hsitory typewriters didn't even \nhave 0 and 1 keys - the O and l were used interchangably and many fonts \nkeep too much to that pattern of undifferetiability!)\n\nNote the more recent http://git-scm.com/docs/git-status has the \nformatted round o and \nhttps://www.kernel.org/pub/software/scm/git/docs/git-status.html (which \nIIUC is out of date) has an unformatted 0.\n\nLooking around some more, it's as if \"0)\" is special cased in some \nconversion to HTML.\n\n>\n> If you have an aversion to mentioning ASCII when clarifying which\n> character we talk about, you could of course do s/ASCII 0/'\\0'/ but\n> I do not know if that is an improvement.\n>\n--\nPhilip \n"},{"id":"250851","messageId":"9FDB0D39D62C46ABA8D2C5356E497BE1@PhilipOakley","threadId":"37760","inReplyTo":"8D139BC1FB1E4335B4375FB0F056BB0B@PhilipOakley","subject":"Re: [PATCH] doc: fix 'git status --help' character quoting","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-20T11:31:06Z","receivedAt":"2014-10-20T11:31:06Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Philip Oakley\" \n> From: \"Junio C Hamano\" \n>> Philip Oakley writes:\n..\n>>\n>>> While at it, use 00 for ASCII NUL to avoid any confusion with the \n>>> letter O.\n\n> (remember its quotation is consumed by ascidoc) looked too much like \n> an\nI mis-remembered. It's not quoted.\n\n> Looking around some more, it's as if \"0)\" is special cased in some \n> conversion to HTML.\n\nThis looks to be an issue of the browser display font \n(Chrome/Chromium/Firefox) where it's almost impossible to distinguish 0 \nand o without other numbers or letters being present for context. The \nold kernel.org page appears to specify the font differently and thus \nprovides a clear rendering.\n\nPhilip \n"},{"id":"250862","messageId":"xmqqy4sa3bpk.fsf@gitster.dls.corp.google.com","threadId":"37760","inReplyTo":"8D139BC1FB1E4335B4375FB0F056BB0B@PhilipOakley","subject":"Re: [PATCH] doc: fix 'git status --help' character quoting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-20T17:14:31Z","receivedAt":"2014-10-20T17:14:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> From: \"Junio C Hamano\" \n>> Philip Oakley writes:\n>>\n>>> Correct backtick quoting for some of the modification states to give\n>>> consistent web rendering.\n>>\n>> This is to match the way how \"XY PATH1 -> PATH2\" is typeset, I\n>> presume. Some in the body text are already `XY` to match, but some\n>> others are not,\n>> and you are fixing them, all of which look good.\n>\n> Do you need me to add this to the commit message?\n\nNah, it already mentions \"consistent\"; I was just double checking\nthat I correctly understod consistency with what part of existing\ndoc is achieved with the patch.\n\n> The reason I proposed the change is because on the web view, on my\n> machine, I questioned whether the specially formatted character\n> (remember its quotation is consumed by ascidoc) looked too much like\n> an Oh, so I specially checked on the original .txt to see if it was\n> correct there, which led me to the proposal for '00' in this case.\n>\n> I'd be just as happy with a single zero, as long as it's distinct from\n> O (as you probably know, in the depths of hsitory typewriters didn't\n> even have 0 and 1 keys - the O and l were used interchangably and many\n> fonts keep too much to that pattern of undifferetiability!)\n\nYes, and that is why I said\n\n>> there is\n>> no risk for anybody to mistake \"O\" (oh) as part of digits, whether\n>> you use decimal or hexadecimal.\n\n;-)\n\n> Note the more recent http://git-scm.com/docs/git-status has the\n> formatted round o and\n\nI think it is just the font. I just opened the above page with\nChrome and futzed the text from '0' to '0123456789' to see how it\nlook. That round thing is consistent with how other digits are\nrendered.\n\nhttps://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K\n\n(sorry for a URL to plus)\n\n> https://www.kernel.org/pub/software/scm/git/docs/git-status.html\n> (which IIUC is out of date) has an unformatted 0.\n"},{"id":"250870","messageId":"DB0FCB7CEC8C453D9237CA4FFA687EDC@PhilipOakley","threadId":"37760","inReplyTo":"xmqqy4sa3bpk.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: fix 'git status --help' character quoting","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-20T19:28:09Z","receivedAt":"2014-10-20T19:28:09Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> \"Philip Oakley\" writes:\n>\n>> From: \"Junio C Hamano\" \n>>> Philip Oakley writes:\n>>>\n...\n> [ (ASCII 0) change]\n>> The reason I proposed the change is because on the web view, on my\n>> machine, I questioned whether the specially formatted character\n>> (remember its quotation is consumed by ascidoc) looked too much like\n>> an Oh, so I specially checked on the original .txt to see if it was\n>> correct there, which led me to the proposal for '00' in this case.\n>>\n>> I'd be just as happy with a single zero, as long as it's distinct \n>> from\n>> O (as you probably know, in the depths of hsitory typewriters didn't\n>> even have 0 and 1 keys - the O and l were used interchangably and \n>> many\n>> fonts keep too much to that pattern of undifferetiability!)\n>\n> Yes, and that is why I said\n>\n>>> there is\n>>> no risk for anybody to mistake \"O\" (oh) as part of digits, whether\n>>> you use decimal or hexadecimal.\n>\n> ;-)\n>\n>> Note the more recent http://git-scm.com/docs/git-status has the\n>> formatted round o and\n>\n> I think it is just the font. I just opened the above page with\n> Chrome and futzed the text from '0' to '0123456789' to see how it\n> look. That round thing is consistent with how other digits are\n> rendered.\n>\n> https://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K\n>\n> (sorry for a URL to plus)\n>\n>> https://www.kernel.org/pub/software/scm/git/docs/git-status.html\n>> (which IIUC is out of date) has an unformatted 0.\n> --\n\nI've just had a look at how it formats when the zero is back-tick quoted \ns /ASCII 0/ASCII `0`/ and it looks OK with both Chromium and Firefox on \nmy hack Ubuntu laptop - the character is colourised and full sized, and \nthe --man page output looks unchanged and clearly a zero.\n\nmy hacky attempt at an in-line patch (squash in?) below:\n--\nPhilip\n----->8----\ncommit 51ec35a196057eae60bb9285c38fb22e49aae1b0\nAuthor: Philip Oakley \nDate: Mon Oct 20 20:21:56 2014 +0100\n\n doc: 'git status' quote the zero (NUL) character\n\n Newer web rendering of 'git status --help --web' shows the zero in\n \"NUL (ASCII 0)\" as if it is a small 'o' character. Back-tick quote \nthe\n zero to ensure it is displayed as a full size mono-spaced font.\n\n Signed-off-by: Philip Oakley \n\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 4d8d530..379aa08 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -189,7 +189,7 @@ There is also an alternate -z format recommended for \nmachine parsing. In\n that format, the status field is the same, but some other things\n change. First, the '\\->' is omitted from rename entries and the field\n order is reversed (e.g 'from \\-> to' becomes 'to from'). Second, a NUL\n-(ASCII 0) follows each filename, replacing space as a field separator\n+(ASCII `0`) follows each filename, replacing space as a field separator\n and the terminating newline (but a space still separates the status\n field from the first filename). Third, filenames containing special\n characters are not specially formatted; no quoting or \n"},{"id":"250872","messageId":"xmqq38ai34bh.fsf@gitster.dls.corp.google.com","threadId":"37760","inReplyTo":"DB0FCB7CEC8C453D9237CA4FFA687EDC@PhilipOakley","subject":"Re: [PATCH] doc: fix 'git status --help' character quoting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-20T19:54:10Z","receivedAt":"2014-10-20T19:54:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> From: \"Junio C Hamano\" \n> ...\n>> I think it is just the font. I just opened the above page with\n>> Chrome and futzed the text from '0' to '0123456789' to see how it\n>> look. That round thing is consistent with how other digits are\n>> rendered.\n>>\n>> https://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K\n>>\n>> (sorry for a URL to plus)\n>>\n>>> https://www.kernel.org/pub/software/scm/git/docs/git-status.html\n>>> (which IIUC is out of date) has an unformatted 0.\n>> --\n>\n> I've just had a look at how it formats when the zero is back-tick\n> quoted s /ASCII 0/ASCII `0`/ and it looks OK with both Chromium and\n> Firefox on my hack Ubuntu laptop - the character is colourised and\n> full sized, and the --man page output looks unchanged and clearly a\n> zero.\n>\n> my hacky attempt at an in-line patch (squash in?) below:\n\nYou'd need a matching change to 34 in the same document to preserve\nthe consistency the original patch sought, though ;-)\n"},{"id":"250873","messageId":"xmqqy4sa1pct.fsf@gitster.dls.corp.google.com","threadId":"37760","inReplyTo":"xmqq38ai34bh.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: fix 'git status --help' character quoting","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-20T20:02:42Z","receivedAt":"2014-10-20T20:02:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> \"Philip Oakley\" writes:\n>\n>> From: \"Junio C Hamano\" \n>> ...\n>>> I think it is just the font. I just opened the above page with\n>>> Chrome and futzed the text from '0' to '0123456789' to see how it\n>>> look. That round thing is consistent with how other digits are\n>>> rendered.\n>>>\n>>> https://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K\n>>>\n>>> (sorry for a URL to plus)\n>>>\n>>>> https://www.kernel.org/pub/software/scm/git/docs/git-status.html\n>>>> (which IIUC is out of date) has an unformatted 0.\n>>> --\n>>\n>> I've just had a look at how it formats when the zero is back-tick\n>> quoted s /ASCII 0/ASCII `0`/ and it looks OK with both Chromium and\n>> Firefox on my hack Ubuntu laptop - the character is colourised and\n>> full sized, and the --man page output looks unchanged and clearly a\n>> zero.\n>>\n>> my hacky attempt at an in-line patch (squash in?) below:\n>\n> You'd need a matching change to 34 in the same document to preserve\n> the consistency the original patch sought, though ;-)\n\nNot that I think such a change makes much sense.\n\nIf there was a way to force use of a font whose numerals and I/O are\nmore clearly distinguishable and we do so for all HTML documents we\ngenerate, that would be a good change that is not limited to these\nplaces, though.\n"},{"id":"250951","messageId":"F862A78B765340E9B18BFDC2A9C2E96F@PhilipOakley","threadId":"37760","inReplyTo":"xmqqy4sa1pct.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: fix 'git status --help' character quoting","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-10-21T22:08:53Z","receivedAt":"2014-10-21T22:08:53Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Junio C Hamano writes:\n>\n>> \"Philip Oakley\" writes:\n>>\n>>> From: \"Junio C Hamano\" \n>>> ...\n>>>> I think it is just the font. I just opened the above page with\n>>>> Chrome and futzed the text from '0' to '0123456789' to see how it\n>>>> look. That round thing is consistent with how other digits are\n>>>> rendered.\n>>>>\n>>>> https://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K\n>>>>\n>>>> (sorry for a URL to plus)\n>>>>\n>>>>> https://www.kernel.org/pub/software/scm/git/docs/git-status.html\n>>>>> (which IIUC is out of date) has an unformatted 0.\n>>>> --\n>>>\n>>> I've just had a look at how it formats when the zero is back-tick\n>>> quoted s /ASCII 0/ASCII `0`/ and it looks OK with both Chromium and\n>>> Firefox on my hack Ubuntu laptop - the character is colourised and\n>>> full sized, and the --man page output looks unchanged and clearly a\n>>> zero.\n>>>\n>>> my hacky attempt at an in-line patch (squash in?) below:\n>>\n>> You'd need a matching change to 34 in the same document to preserve\n>> the consistency the original patch sought, though ;-)\n>\n> Not that I think such a change makes much sense.\n>\n> If there was a way to force use of a font whose numerals and I/O are\n> more clearly distinguishable and we do so for all HTML documents we\n> generate, that would be a good change that is not limited to these\n> places, though.\n>\nI've generated a patch for the 'git status --help' that can act as a \nreference. (to follow)\n\nFor me it's only those pages that have a lone zero that cause problems \ndue to lack of context. It'll still be a slow burner problem as lone \nzeros are spotted.\n\nPhilip \n"}]}