Discussion:
[PATCH] doc: fix 'git status --help' character quoting
Philip Oakley
2014-10-19 14:17:15 UTC
Permalink
Correct backtick quoting for some of the modification states to give
consistent web rendering.

While at it, use 00 for ASCII NUL to avoid any confusion with the letter O.

Signed-off-by: Philip Oakley <***@iee.org>
---

Noticed when reviewing a stackoverflow problem where the OP actually
desired to just list those files with merge indicators present.
---
Documentation/git-status.txt | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index def635f..1c01d3ac 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -116,7 +116,7 @@ In the short-format, the status of each path is shown as

where `PATH1` is the path in the `HEAD`, and the " `-> PATH2`" part is
shown only when `PATH1` corresponds to a different path in the
-index/worktree (i.e. the file is renamed). The 'XY' is a two-letter
+index/worktree (i.e. the file is renamed). The `XY` is a two-letter
status code.

The fields (including the `->`) are separated from each other by a
@@ -125,7 +125,7 @@ characters, that field will be quoted in the manner of a C string
literal: surrounded by ASCII double quote (34) characters, and with
interior special characters backslash-escaped.

-For paths with merge conflicts, `X` and 'Y' show the modification
+For paths with merge conflicts, `X` and `Y` show the modification
states of each side of the merge. For paths that do not have merge
conflicts, `X` shows the status of the index, and `Y` shows the status
of the work tree. For untracked paths, `XY` are `??`. Other status
@@ -189,7 +189,7 @@ There is also an alternate -z format recommended for machine parsing. In
that format, the status field is the same, but some other things
change. First, the '\->' is omitted from rename entries and the field
order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
-(ASCII 0) follows each filename, replacing space as a field separator
+(ASCII 00) follows each filename, replacing space as a field separator
and the terminating newline (but a space still separates the status
field from the first filename). Third, filenames containing special
characters are not specially formatted; no quoting or
--
1.9.4.msysgit.0
Junio C Hamano
2014-10-19 22:26:00 UTC
Permalink
Post by Philip Oakley
Correct backtick quoting for some of the modification states to give
consistent web rendering.
This is to match the way how "XY PATH1 -> PATH2" is typeset, I
presume. Some in the body text are already `XY` to match, but some
others are not, and you are fixing them, all of which look good.
Post by Philip Oakley
While at it, use 00 for ASCII NUL to avoid any confusion with the letter O.
I do not think this is particularly a good change. We try to follow
the convention of spelling ASCII value in decimal (e.g. "ASCII
double quote (34)"), and "00" is not the way how you usually spell a
number in decimal. Existing description is perfectly fine; there is
no risk for anybody to mistake "O" (oh) as part of digits, whether
you use decimal or hexadecimal.

If you have an aversion to mentioning ASCII when clarifying which
character we talk about, you could of course do s/ASCII 0/'\0'/ but
I do not know if that is an improvement.

Thanks.
Post by Philip Oakley
---
Noticed when reviewing a stackoverflow problem where the OP actually
desired to just list those files with merge indicators present.
---
Documentation/git-status.txt | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index def635f..1c01d3ac 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -116,7 +116,7 @@ In the short-format, the status of each path is shown as
where `PATH1` is the path in the `HEAD`, and the " `-> PATH2`" part is
shown only when `PATH1` corresponds to a different path in the
-index/worktree (i.e. the file is renamed). The 'XY' is a two-letter
+index/worktree (i.e. the file is renamed). The `XY` is a two-letter
status code.
The fields (including the `->`) are separated from each other by a
@@ -125,7 +125,7 @@ characters, that field will be quoted in the manner of a C string
literal: surrounded by ASCII double quote (34) characters, and with
interior special characters backslash-escaped.
-For paths with merge conflicts, `X` and 'Y' show the modification
+For paths with merge conflicts, `X` and `Y` show the modification
states of each side of the merge. For paths that do not have merge
conflicts, `X` shows the status of the index, and `Y` shows the status
of the work tree. For untracked paths, `XY` are `??`. Other status
@@ -189,7 +189,7 @@ There is also an alternate -z format recommended for machine parsing. In
that format, the status field is the same, but some other things
change. First, the '\->' is omitted from rename entries and the field
order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
-(ASCII 0) follows each filename, replacing space as a field separator
+(ASCII 00) follows each filename, replacing space as a field separator
and the terminating newline (but a space still separates the status
field from the first filename). Third, filenames containing special
characters are not specially formatted; no quoting or
Philip Oakley
2014-10-20 10:46:30 UTC
Permalink
Post by Junio C Hamano
Post by Philip Oakley
Correct backtick quoting for some of the modification states to give
consistent web rendering.
This is to match the way how "XY PATH1 -> PATH2" is typeset, I
presume. Some in the body text are already `XY` to match, but some
others are not,
and you are fixing them, all of which look good.
Do you need me to add this to the commit message?
Post by Junio C Hamano
Post by Philip Oakley
While at it, use 00 for ASCII NUL to avoid any confusion with the letter O.
I do not think this is particularly a good change. We try to follow
the convention of spelling ASCII value in decimal (e.g. "ASCII
double quote (34)"), and "00" is not the way how you usually spell a
number in decimal. Existing description is perfectly fine;
there is
no risk for anybody to mistake "O" (oh) as part of digits, whether
you use decimal or hexadecimal.
The reason I proposed the change is because on the web view, on my
machine, I questioned whether the specially formatted character
(remember its quotation is consumed by ascidoc) looked too much like an
Oh, so I specially checked on the original .txt to see if it was correct
there, which led me to the proposal for '00' in this case.

I'd be just as happy with a single zero, as long as it's distinct from O
(as you probably know, in the depths of hsitory typewriters didn't even
have 0 and 1 keys - the O and l were used interchangably and many fonts
keep too much to that pattern of undifferetiability!)

Note the more recent http://git-scm.com/docs/git-status has the
formatted round o and
https://www.kernel.org/pub/software/scm/git/docs/git-status.html (which
IIUC is out of date) has an unformatted 0.

Looking around some more, it's as if "0)" is special cased in some
conversion to HTML.
Post by Junio C Hamano
If you have an aversion to mentioning ASCII when clarifying which
character we talk about, you could of course do s/ASCII 0/'\0'/ but
I do not know if that is an improvement.
--
Philip
Philip Oakley
2014-10-20 11:31:06 UTC
Permalink
..
Post by Philip Oakley
Post by Philip Oakley
While at it, use 00 for ASCII NUL to avoid any confusion with the letter O.
(remember its quotation is consumed by ascidoc) looked too much like an
I mis-remembered. It's not quoted.
Post by Philip Oakley
Looking around some more, it's as if "0)" is special cased in some
conversion to HTML.
This looks to be an issue of the browser display font
(Chrome/Chromium/Firefox) where it's almost impossible to distinguish 0
and o without other numbers or letters being present for context. The
old kernel.org page appears to specify the font differently and thus
provides a clear rendering.

Philip
Junio C Hamano
2014-10-20 17:14:31 UTC
Permalink
Post by Philip Oakley
Post by Junio C Hamano
Post by Philip Oakley
Correct backtick quoting for some of the modification states to give
consistent web rendering.
This is to match the way how "XY PATH1 -> PATH2" is typeset, I
presume. Some in the body text are already `XY` to match, but some
others are not,
and you are fixing them, all of which look good.
Do you need me to add this to the commit message?
Nah, it already mentions "consistent"; I was just double checking
that I correctly understod consistency with what part of existing
doc is achieved with the patch.
Post by Philip Oakley
The reason I proposed the change is because on the web view, on my
machine, I questioned whether the specially formatted character
(remember its quotation is consumed by ascidoc) looked too much like
an Oh, so I specially checked on the original .txt to see if it was
correct there, which led me to the proposal for '00' in this case.
I'd be just as happy with a single zero, as long as it's distinct from
O (as you probably know, in the depths of hsitory typewriters didn't
even have 0 and 1 keys - the O and l were used interchangably and many
fonts keep too much to that pattern of undifferetiability!)
Yes, and that is why I said
Post by Philip Oakley
Post by Junio C Hamano
there is
no risk for anybody to mistake "O" (oh) as part of digits, whether
you use decimal or hexadecimal.
;-)
Post by Philip Oakley
Note the more recent http://git-scm.com/docs/git-status has the
formatted round o and
I think it is just the font. I just opened the above page with
Chrome and futzed the text from '0' to '0123456789' to see how it
look. That round thing is consistent with how other digits are
rendered.

https://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K

(sorry for a URL to plus)
Post by Philip Oakley
https://www.kernel.org/pub/software/scm/git/docs/git-status.html
(which IIUC is out of date) has an unformatted 0.
Philip Oakley
2014-10-20 19:28:09 UTC
Permalink
...
[ (ASCII 0) change]
Post by Philip Oakley
The reason I proposed the change is because on the web view, on my
machine, I questioned whether the specially formatted character
(remember its quotation is consumed by ascidoc) looked too much like
an Oh, so I specially checked on the original .txt to see if it was
correct there, which led me to the proposal for '00' in this case.
I'd be just as happy with a single zero, as long as it's distinct from
O (as you probably know, in the depths of hsitory typewriters didn't
even have 0 and 1 keys - the O and l were used interchangably and many
fonts keep too much to that pattern of undifferetiability!)
Yes, and that is why I said
Post by Philip Oakley
Post by Junio C Hamano
there is
no risk for anybody to mistake "O" (oh) as part of digits, whether
you use decimal or hexadecimal.
;-)
Post by Philip Oakley
Note the more recent http://git-scm.com/docs/git-status has the
formatted round o and
I think it is just the font. I just opened the above page with
Chrome and futzed the text from '0' to '0123456789' to see how it
look. That round thing is consistent with how other digits are
rendered.
https://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K
(sorry for a URL to plus)
Post by Philip Oakley
https://www.kernel.org/pub/software/scm/git/docs/git-status.html
(which IIUC is out of date) has an unformatted 0.
--
I've just had a look at how it formats when the zero is back-tick quoted
s /ASCII 0/ASCII `0`/ and it looks OK with both Chromium and Firefox on
my hack Ubuntu laptop - the character is colourised and full sized, and
the --man page output looks unchanged and clearly a zero.

my hacky attempt at an in-line patch (squash in?) below:
--
Philip
----->8----
commit 51ec35a196057eae60bb9285c38fb22e49aae1b0
Author: Philip Oakley <***@iee.org>
Date: Mon Oct 20 20:21:56 2014 +0100

doc: 'git status' quote the zero (NUL) character

Newer web rendering of 'git status --help --web' shows the zero in
"NUL (ASCII 0)" as if it is a small 'o' character. Back-tick quote
the
zero to ensure it is displayed as a full size mono-spaced font.

Signed-off-by: Philip Oakley <***@iee.org>

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 4d8d530..379aa08 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -189,7 +189,7 @@ There is also an alternate -z format recommended for
machine parsing. In
that format, the status field is the same, but some other things
change. First, the '\->' is omitted from rename entries and the field
order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
-(ASCII 0) follows each filename, replacing space as a field separator
+(ASCII `0`) follows each filename, replacing space as a field separator
and the terminating newline (but a space still separates the status
field from the first filename). Third, filenames containing special
characters are not specially formatted; no quoting or
Junio C Hamano
2014-10-20 19:54:10 UTC
Permalink
Post by Philip Oakley
...
Post by Junio C Hamano
I think it is just the font. I just opened the above page with
Chrome and futzed the text from '0' to '0123456789' to see how it
look. That round thing is consistent with how other digits are
rendered.
https://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K
(sorry for a URL to plus)
Post by Philip Oakley
https://www.kernel.org/pub/software/scm/git/docs/git-status.html
(which IIUC is out of date) has an unformatted 0.
--
I've just had a look at how it formats when the zero is back-tick
quoted s /ASCII 0/ASCII `0`/ and it looks OK with both Chromium and
Firefox on my hack Ubuntu laptop - the character is colourised and
full sized, and the --man page output looks unchanged and clearly a
zero.
You'd need a matching change to 34 in the same document to preserve
the consistency the original patch sought, though ;-)
Junio C Hamano
2014-10-20 20:02:42 UTC
Permalink
Post by Junio C Hamano
Post by Philip Oakley
...
Post by Junio C Hamano
I think it is just the font. I just opened the above page with
Chrome and futzed the text from '0' to '0123456789' to see how it
look. That round thing is consistent with how other digits are
rendered.
https://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K
(sorry for a URL to plus)
Post by Philip Oakley
https://www.kernel.org/pub/software/scm/git/docs/git-status.html
(which IIUC is out of date) has an unformatted 0.
--
I've just had a look at how it formats when the zero is back-tick
quoted s /ASCII 0/ASCII `0`/ and it looks OK with both Chromium and
Firefox on my hack Ubuntu laptop - the character is colourised and
full sized, and the --man page output looks unchanged and clearly a
zero.
You'd need a matching change to 34 in the same document to preserve
the consistency the original patch sought, though ;-)
Not that I think such a change makes much sense.

If there was a way to force use of a font whose numerals and I/O are
more clearly distinguishable and we do so for all HTML documents we
generate, that would be a good change that is not limited to these
places, though.
Philip Oakley
2014-10-21 22:08:53 UTC
Permalink
Post by Junio C Hamano
Post by Junio C Hamano
Post by Philip Oakley
...
Post by Junio C Hamano
I think it is just the font. I just opened the above page with
Chrome and futzed the text from '0' to '0123456789' to see how it
look. That round thing is consistent with how other digits are
rendered.
https://plus.google.com/u/0/+JunioCHamano/posts/dzNXV2FwP6K
(sorry for a URL to plus)
Post by Philip Oakley
https://www.kernel.org/pub/software/scm/git/docs/git-status.html
(which IIUC is out of date) has an unformatted 0.
--
I've just had a look at how it formats when the zero is back-tick
quoted s /ASCII 0/ASCII `0`/ and it looks OK with both Chromium and
Firefox on my hack Ubuntu laptop - the character is colourised and
full sized, and the --man page output looks unchanged and clearly a
zero.
You'd need a matching change to 34 in the same document to preserve
the consistency the original patch sought, though ;-)
Not that I think such a change makes much sense.
If there was a way to force use of a font whose numerals and I/O are
more clearly distinguishable and we do so for all HTML documents we
generate, that would be a good change that is not limited to these
places, though.
I've generated a patch for the 'git status --help' that can act as a
reference. (to follow)

For me it's only those pages that have a lone zero that cause problems
due to lack of context. It'll still be a slow burner problem as lone
zeros are spotted.

Philip

Loading...