[PATCH] doc: fix 'git status --help' character quoting

[PATCH] doc: fix 'git status --help' character quoting

[Philip Oakley]

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

Re: [PATCH] doc: fix 'git status --help' character quoting

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

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

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

>
> Signed-off-by: Philip Oakley <philipoakley@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

Re: [PATCH] doc: fix 'git status --help' character quoting

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> Philip Oakley <philipoakley@iee.org> writes:
>
>> 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?

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

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

Re: [PATCH] doc: fix 'git status --help' character quoting

[Philip Oakley]

From: "Philip Oakley" <philipoakley@iee.org>
> From: "Junio C Hamano" <gitster@pobox.com>
>> Philip Oakley <philipoakley@iee.org> writes:
..
>>
>>> 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.

> 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 

Re: [PATCH] doc: fix 'git status --help' character quoting

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> From: "Junio C Hamano" <gitster@pobox.com>
>> Philip Oakley <philipoakley@iee.org> writes:
>>
>>> 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.

> 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

>> there is
>> no risk for anybody to mistake "O" (oh) as part of digits, whether
>> you use decimal or hexadecimal.

;-)

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

> https://www.kernel.org/pub/software/scm/git/docs/git-status.html
> (which IIUC is out of date) has an unformatted 0.

Re: [PATCH] doc: fix 'git status --help' character quoting

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> From: "Junio C Hamano" <gitster@pobox.com>
>>> Philip Oakley <philipoakley@iee.org> writes:
>>>
...
> [ (ASCII 0) change]
>> 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
>
>>> there is
>>> no risk for anybody to mistake "O" (oh) as part of digits, whether
>>> you use decimal or hexadecimal.
>
> ;-)
>
>> 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)
>
>> 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 <philipoakley@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 <philipoakley@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 

Re: [PATCH] doc: fix 'git status --help' character quoting

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> From: "Junio C Hamano" <gitster@pobox.com>
> ...
>> 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)
>>
>>> 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:

You'd need a matching change to 34 in the same document to preserve
the consistency the original patch sought, though ;-)

Re: [PATCH] doc: fix 'git status --help' character quoting

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> From: "Junio C Hamano" <gitster@pobox.com>
>> ...
>>> 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)
>>>
>>>> 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:
>
> 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.

Re: [PATCH] doc: fix 'git status --help' character quoting

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> Junio C Hamano <gitster@pobox.com> writes:
>
>> "Philip Oakley" <philipoakley@iee.org> writes:
>>
>>> From: "Junio C Hamano" <gitster@pobox.com>
>>> ...
>>>> 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)
>>>>
>>>>> 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:
>>
>> 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