From d664a7ad20f9cb013f4c53654b76973612a89991 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Thu, 19 Jan 2023 18:18:23 +0000 Subject: [PATCH 1/5] doc: pretty-formats: separate parameters from placeholders Commit a57523428b4 (pretty: support padding placeholders, %< %> and %><, 2013-04-19) introduced columnated place holders. These placeholders can be confusing as they contain `<` and `>` characters as part of their placeholders adjacent to the `` parameters. Add spaces either side of the `` parameters in the title line. The code (strtol) will consume any spaces around the number values (assuming they are passed as a quoted string with spaces). Note that the spaces are optional. Subsequent commits will clarify other confusions. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/pretty-formats.txt | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 0b4c1c8d98..02bec23509 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -146,24 +146,27 @@ The placeholders are: '%m':: left (`<`), right (`>`) or boundary (`-`) mark '%w([[,[,]]])':: switch line wrapping, like the -w option of linkgit:git-shortlog[1]. -'%<([,trunc|ltrunc|mtrunc])':: make the next placeholder take at +'%<( [,trunc|ltrunc|mtrunc])':: make the next placeholder take at least N columns, padding spaces on the right if necessary. Optionally truncate at the beginning (ltrunc), the middle (mtrunc) or the end (trunc) if the output is longer than - N columns. Note that truncating + N columns. + Note 1: that truncating only works correctly with N >= 2. -'%<|()':: make the next placeholder take at least until Nth + Note 2: spaces around the N + values are optional. +'%<|( )':: make the next placeholder take at least until Nth columns, padding spaces on the right if necessary -'%>()', '%>|()':: similar to '%<()', '%<|()' respectively, +'%>( )', '%>|( )':: similar to '%<( )', '%<|( )' respectively, but padding spaces on the left -'%>>()', '%>>|()':: similar to '%>()', '%>|()' +'%>>( )', '%>>|( )':: similar to '%>( )', '%>|( )' respectively, except that if the next placeholder takes more spaces than given and there are spaces on its left, use those spaces -'%><()', '%><|()':: similar to '%<()', '%<|()' +'%><( )', '%><|( )':: similar to '%<( )', '%<|( )' respectively, but padding both sides (i.e. the text is centered) From 8bcb8f8e2282ff27f7ffd106eb2fb7bf982ff2d1 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Thu, 19 Jan 2023 18:18:24 +0000 Subject: [PATCH 2/5] doc: pretty-formats: delineate `%<|(` parameter values Commit a57523428b4 (pretty: support padding placeholders, %< %> and %><, 2013-04-19) introduced column width place holders. It also added separate column position `%<|(` placeholders for display screen based placement. Change the display screen parameter reference from 'N' to 'M' and corresponding descriptives to make the distinction clearer. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/pretty-formats.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 02bec23509..8cc1072196 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -147,7 +147,7 @@ The placeholders are: '%w([[,[,]]])':: switch line wrapping, like the -w option of linkgit:git-shortlog[1]. '%<( [,trunc|ltrunc|mtrunc])':: make the next placeholder take at - least N columns, padding spaces on + least N column widths, padding spaces on the right if necessary. Optionally truncate at the beginning (ltrunc), the middle (mtrunc) or the end @@ -155,18 +155,18 @@ The placeholders are: N columns. Note 1: that truncating only works correctly with N >= 2. - Note 2: spaces around the N + Note 2: spaces around the N and M (see below) values are optional. -'%<|( )':: make the next placeholder take at least until Nth - columns, padding spaces on the right if necessary -'%>( )', '%>|( )':: similar to '%<( )', '%<|( )' respectively, +'%<|( )':: make the next placeholder take at least until Mth + display column, padding spaces on the right if necessary +'%>( )', '%>|( )':: similar to '%<( )', '%<|( )' respectively, but padding spaces on the left -'%>>( )', '%>>|( )':: similar to '%>( )', '%>|( )' +'%>>( )', '%>>|( )':: similar to '%>( )', '%>|( )' respectively, except that if the next placeholder takes more spaces than given and there are spaces on its left, use those spaces -'%><( )', '%><|( )':: similar to '%<( )', '%<|( )' +'%><( )', '%><|( )':: similar to '%<( )', '%<|( )' respectively, but padding both sides (i.e. the text is centered) From 63792c564c3a96007baf7ce876dea0a6f5f9f880 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Thu, 19 Jan 2023 18:18:25 +0000 Subject: [PATCH 3/5] doc: pretty-formats document negative column alignments Commit 066790d7cb0 (pretty.c: support |() forms, 2016-06-16) added the option for right justified column alignment without updating the documentation. Add an explanation of its use of negative column values. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/pretty-formats.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 8cc1072196..cbca60a196 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -158,7 +158,9 @@ The placeholders are: Note 2: spaces around the N and M (see below) values are optional. '%<|( )':: make the next placeholder take at least until Mth - display column, padding spaces on the right if necessary + display column, padding spaces on the right if necessary. + Use negative M values for column positions measured + from the right hand edge of the terminal window. '%>( )', '%>|( )':: similar to '%<( )', '%<|( )' respectively, but padding spaces on the left '%>>( )', '%>>|( )':: similar to '%>( )', '%>|( )' From b5cd634d7a30074452c5aa3b0ce66ce794c4d565 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Thu, 19 Jan 2023 18:18:26 +0000 Subject: [PATCH 4/5] doc: pretty-formats describe use of ellipsis in truncation Commit a7f01c6b4d (pretty: support truncating in %>, %< and %><, 2013-04-19) added the use of ellipsis when truncating placeholder values. Show our 'two dot' ellipsis, and examples for the left, middle and right truncation to avoid any confusion as to which end of the string is adjusted. (cf justification and sub-string). Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/pretty-formats.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index cbca60a196..e51f1e54e1 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -149,9 +149,9 @@ The placeholders are: '%<( [,trunc|ltrunc|mtrunc])':: make the next placeholder take at least N column widths, padding spaces on the right if necessary. Optionally - truncate at the beginning (ltrunc), - the middle (mtrunc) or the end - (trunc) if the output is longer than + truncate (with ellipsis '..') at the left (ltrunc) `..ft`, + the middle (mtrunc) `mi..le`, or the end + (trunc) `rig..`, if the output is longer than N columns. Note 1: that truncating only works correctly with N >= 2. From 540e7bc477fc9bc491221075c0fade0722e63945 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Thu, 19 Jan 2023 18:18:27 +0000 Subject: [PATCH 5/5] doc: pretty-formats note wide char limitations, and add tests The previous commits added clarifications to the column alignment placeholders, note that the spaces are optional around the parameters. Also, a proposed extension [1] to allow hard truncation (without ellipsis '..') highlighted that the existing code does not play well with wide characters, such as Asian fonts and emojis. For example, N wide characters take 2N columns so won't fit an odd number column width, causing misalignment somewhere. Further analysis also showed that decomposed characters, e.g. separate `a` + `umlaut` Unicode code-points may also be mis-counted, in some cases leaving multiple loose `umlauts` all combined together. Add some notes about these limitations, and add basic tests to demonstrate them. The chosen solution for the tests is to substitute any wide character that overlaps a splitting boundary for the unicode vertical ellipsis code point as a rare but 'obvious' substitution. An alternative could be the substitution with a single dot '.' which matches regular expression usage, and our two dot ellipsis, and further in scenarios where the bulk of the text is wide characters, would be obvious. In mainly 'ascii' scenarios a singleton emoji being substituted by a dot could be confusing. It is enough that the tests fail cleanly. The final choice for the substitute character can be deferred. [1] https://lore.kernel.org/git/20221030185614.3842-1-philipoakley@iee.email/ Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- Documentation/pretty-formats.txt | 5 +++++ t/t4205-log-pretty-formats.sh | 27 +++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index e51f1e54e1..3b71334459 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -157,6 +157,11 @@ The placeholders are: only works correctly with N >= 2. Note 2: spaces around the N and M (see below) values are optional. + Note 3: Emojis and other wide characters + will take two display columns, which may + over-run column boundaries. + Note 4: decomposed character combining marks + may be misplaced at padding boundaries. '%<|( )':: make the next placeholder take at least until Mth display column, padding spaces on the right if necessary. Use negative M values for column positions measured diff --git a/t/t4205-log-pretty-formats.sh b/t/t4205-log-pretty-formats.sh index 0404491d6e..2cba0e0c56 100755 --- a/t/t4205-log-pretty-formats.sh +++ b/t/t4205-log-pretty-formats.sh @@ -1018,4 +1018,31 @@ test_expect_success '%(describe:abbrev=...) vs git describe --abbrev=...' ' test_cmp expect actual ' +# pretty-formats note wide char limitations, and add tests +test_expect_failure 'wide and decomposed characters column counting' ' + +# from t/lib-unicode-nfc-nfd.sh hex values converted to octal + utf8_nfc=$(printf "\303\251") && # e acute combined. + utf8_nfd=$(printf "\145\314\201") && # e with a combining acute (i.e. decomposed) + utf8_emoji=$(printf "\360\237\221\250") && + +# replacement character when requesting a wide char fits in a single display colum. +# "half wide" alternative could be a plain ASCII dot `.` + utf8_vert_ell=$(printf "\342\213\256") && + +# use ${xxx} here! + nfc10="${utf8_nfc}${utf8_nfc}${utf8_nfc}${utf8_nfc}${utf8_nfc}${utf8_nfc}${utf8_nfc}${utf8_nfc}${utf8_nfc}${utf8_nfc}" && + nfd10="${utf8_nfd}${utf8_nfd}${utf8_nfd}${utf8_nfd}${utf8_nfd}${utf8_nfd}${utf8_nfd}${utf8_nfd}${utf8_nfd}${utf8_nfd}" && + emoji5="${utf8_emoji}${utf8_emoji}${utf8_emoji}${utf8_emoji}${utf8_emoji}" && +# emoji5 uses 10 display columns + + test_commit "abcdefghij" && + test_commit --no-tag "${nfc10}" && + test_commit --no-tag "${nfd10}" && + test_commit --no-tag "${emoji5}" && + printf "${utf8_emoji}..${utf8_emoji}${utf8_vert_ell}\n${utf8_nfd}..${utf8_nfd}${utf8_nfd}\n${utf8_nfc}..${utf8_nfc}${utf8_nfc}\na..ij\n" >expected && + git log --format="%<(5,mtrunc)%s" -4 >actual && + test_cmp expected actual +' + test_done