Using C23 digit separators not locale digit grouping characters

Using C23 digit separators not locale digit grouping characters

[Brian Inglis]

Hi folks,

Seeing the recent tv_nsec patches drop the standard locale digit grouping 
characters "," from the member range [0-999,999,999] made me regret the loss of 
the punctuation which provides better and quicker comprehension of long strings 
of digits.

It may be time to consider using the locale independent C23 digit separator 
characters "'" wherever more than a handful of digits occur, possibly convert 
grouping character uses in existing man pages as they are changed, and specify a 
future standard policy approach to provide better and quicker comprehension of 
long strings of digits: perhaps using a new digit separator register and glyph 
escape sequence \*ds \*[ds] \[ds] \(ds if not in use by base groff?

As well as the recently modified pages:

clock_getres.2
timer_settime.2
timerfd_create.2
utimensat.2

there appear to be obvious occurrences in only the following pages:

futex.2
read.2
sendfile.2
write.2
mallopt.3
keyrings.7
mq_overview.7
sched.7
time_namespaces.7

but there appear to be about 400 pages with more than 6 decimal digit strings 
(some spurious glibc hex commits and address outputs) where it could perhaps 
help, such as in POSIX version dates e.g. 2001'12L, and undoubtedly more with 
long digit strings in other radixes.

-- 
Take care. Thanks, Brian Inglis			Calgary, Alberta, Canada

La perfection est atteinte			Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter	not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer	but when there is no more to cut
			-- Antoine de Saint-Exupéry

Re: Using C23 digit separators not locale digit grouping characters

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2291 bytes --]

Hi Brian and наб!

On 1/28/23 21:40, Brian Inglis wrote:
> Hi folks,
> 
> Seeing the recent tv_nsec patches drop the standard locale digit grouping 
> characters "," from the member range [0-999,999,999] made me regret the loss of 
> the punctuation which provides better and quicker comprehension of long strings 
> of digits.

Nice! Didn't remember about that separator.  It makes a lot of sense to use it 
in comments and the likes in the pages.  Maybe we should be a bit more cautious 
in source code examples, but definitely for big numbers outside of running code 
should have them.

наб, would you please update your patches with that?  I also have a few comments 
that I'll write in a moment in answers to your patches.

Cheers,

Alex

> 
> It may be time to consider using the locale independent C23 digit separator 
> characters "'" wherever more than a handful of digits occur, possibly convert 
> grouping character uses in existing man pages as they are changed, and specify a 
> future standard policy approach to provide better and quicker comprehension of 
> long strings of digits: perhaps using a new digit separator register and glyph 
> escape sequence \*ds \*[ds] \[ds] \(ds if not in use by base groff?

The sequence for the unslanted single quote is \(aq.

We could add somewhere in man-pages(7) that decimal numbers should use a 
separator every 3 digits, and hex and binary should use it every 4 digits.

> 
> As well as the recently modified pages:
> 
> clock_getres.2
> timer_settime.2
> timerfd_create.2
> utimensat.2
> 
> there appear to be obvious occurrences in only the following pages:
> 
> futex.2
> read.2
> sendfile.2
> write.2
> mallopt.3
> keyrings.7
> mq_overview.7
> sched.7
> time_namespaces.7
> 
> but there appear to be about 400 pages with more than 6 decimal digit strings 
> (some spurious glibc hex commits and address outputs) where it could perhaps 
> help, such as in POSIX version dates e.g. 2001'12L, and undoubtedly more with 
> long digit strings in other radixes.

Would you mind preparing a patch for all of those?  If you'll do it, better wait 
until we merge наб's patches, to avoid conflicts.

Cheers,

Alex

> 

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Using C23 digit separators not locale digit grouping characters

[Brian Inglis]

On 2023-01-29 07:38, Alejandro Colomar wrote:
> On 1/28/23 21:40, Brian Inglis wrote:
>> Seeing the recent tv_nsec patches drop the standard locale digit grouping 
>> characters "," from the member range [0-999,999,999] made me regret the loss 
>> of the punctuation which provides better and quicker comprehension of long 
>> strings of digits.

> Nice! Didn't remember about that separator.  It makes a lot of sense to use it 
> in comments and the likes in the pages.  Maybe we should be a bit more cautious 
> in source code examples, but definitely for big numbers outside of running code 
> should have them.
The major compilers support them from draft C23, and the code is in examples, 
not source that has to compile on older compilers, so not much to be concerned 
about there, although some more opinions would be helpful.

> наб, would you please update your patches with that?  I also have a few
> comments that I'll write in a moment in answers to your patches.
>> It may be time to consider using the locale independent C23 digit
>> separator characters "'" wherever more than a handful of digits occur,
>> possibly convert grouping character uses in existing man pages as they are
>> changed, and specify a future standard policy approach to provide better
>> and quicker comprehension of long strings of digits: perhaps using a new
>> digit separator register and glyph escape sequence \*ds \*[ds] \[ds] \(ds
>> if not in use by base groff?
> The sequence for the unslanted single quote is \(aq.
Granted, but would it not be better to consider using a semantic digit separator 
groff man escape sequence, especially in text, whose rendering could be tweaked, 
rather than a generic literal apostrophe quote used everywhere?
If nothing else is proposed and accepted, I will use the generic \(aq, and if 
future changes are required, they can be targeted by digit context.

> We could add somewhere in man-pages(7) that decimal numbers should use a 
> separator every 3 digits, and hex and binary should use it every 4 digits.
As well as the 3 decimal, 4 binary/hex, we could use yyyy'mm['dd]L for POSIX and 
similar date digit strings, and 0x10'ffff for Unicode code points, 
distinguishing between the Basic and Supplementary Multilingual Plane indices 
and codes, just as examples from what I've seen so far.

I've also noticed a lot of apparently random decimal digit strings that are 
binary powers or close deltas: those would be more comprehensible if rendered in 
text as Ki/Mi/Gi[+/-n], so would that be preferable, using the IEC i suffix to 
avoid ambiguity?

>> As well as the recently modified pages:
>> 
 >> clock_getres.2
 >> timer_settime.2
 >> timerfd_create.2
 >> utimensat.2
>> 
>> there appear to be obvious occurrences in only the following pages:
>> 
 >> futex.2
 >> read.2
 >> sendfile.2
 >> write.2
 >> mallopt.3
 >> keyrings.7
 >> mq_overview.7
 >> sched.7
 >> time_namespaces.7
>> 
>> but there appear to be about 400 pages with more than 6 decimal digit
>> strings (some spurious glibc hex commits and address outputs) where it
>> could perhaps help, such as in POSIX version dates e.g. 2001'12L, and
>> undoubtedly more with long digit strings in other radixes.
> Would you mind preparing a patch for all of those?  If you'll do it, better
> wait until we merge наб's patches, to avoid conflicts.
I'll start anyway, need to review over 300 files with over 900 digit strings, 
having cut a bunch more pages with output examples.

Any particular subdivision of files patched into git logged patches, by section, 
by type of edit, separate logged patches for files with many edits, or...?

FYI although many hits are likely output, the top candidates so far are:

80 man5/proc.5
55 man2/statfs.2
34 man7/feature_test_macros.7
32 man3/dl_iterate_phdr.3
30 man7/units.7
30 man5/rpc.5
23 man3/termios.3
20 man3/malloc_info.3
17 man2/userfaultfd.2
16 man7/keyrings.7
15 man7/time_namespaces.7
14 man7/posixoptions.7
14 man3/mallopt.3
13 man7/utf-8.7
12 man2/reboot.2
12 man2/keyctl.2

-- 
Take care. Thanks, Brian Inglis			Calgary, Alberta, Canada

La perfection est atteinte			Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter	not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer	but when there is no more to cut
			-- Antoine de Saint-Exupéry

Re: Using C23 digit separators not locale digit grouping characters

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 5745 bytes --]

Hi Brian, Branden,

On 1/29/23 22:04, Brian Inglis wrote:
> On 2023-01-29 07:38, Alejandro Colomar wrote:
>> On 1/28/23 21:40, Brian Inglis wrote:
>>> Seeing the recent tv_nsec patches drop the standard locale digit grouping 
>>> characters "," from the member range [0-999,999,999] made me regret the loss 
>>> of the punctuation which provides better and quicker comprehension of long 
>>> strings of digits.
> 
>> Nice! Didn't remember about that separator.  It makes a lot of sense to use it 
>> in comments and the likes in the pages.  Maybe we should be a bit more 
>> cautious in source code examples, but definitely for big numbers outside of 
>> running code should have them.
> The major compilers support them from draft C23, and the code is in examples, 
> not source that has to compile on older compilers, so not much to be concerned 
> about there, although some more opinions would be helpful.

My version of gcc only supports it if you specify -std=c2x or -std=gnu2x.  It 
hasn't been backported to -std=gnu17 (the default) so far, AFAICS.

$ cc -Wall -Wextra quote.c
quote.c: In function ‘main’:
quote.c:5:18: warning: multi-character character constant [-Wmultichar]
     5 |         int x = 1'23'4;
       |                  ^~~~
quote.c:5:18: error: expected ‘,’ or ‘;’ before '\x3233'
$ cc -Wall -Wextra quote.c -std=gnu2x
$


Since most people would be compiling on default settings, I prefer avoiding 
that.  When c23 is finally released, and GCC switches to gnu23 by default, I'd 
also use it in example programs.  Does it make sense to you?

> 
>> наб, would you please update your patches with that?  I also have a few
>> comments that I'll write in a moment in answers to your patches.
>>> It may be time to consider using the locale independent C23 digit
>>> separator characters "'" wherever more than a handful of digits occur,
>>> possibly convert grouping character uses in existing man pages as they are
>>> changed, and specify a future standard policy approach to provide better
>>> and quicker comprehension of long strings of digits: perhaps using a new
>>> digit separator register and glyph escape sequence \*ds \*[ds] \[ds] \(ds
>>> if not in use by base groff?
>> The sequence for the unslanted single quote is \(aq.
> Granted, but would it not be better to consider using a semantic digit separator 
> groff man escape sequence, especially in text, whose rendering could be tweaked, 
> rather than a generic literal apostrophe quote used everywhere?
> If nothing else is proposed and accepted, I will use the generic \(aq, and if 
> future changes are required, they can be targeted by digit context.

We have little semantic things in man(7), as opposed to mdoc(7).  I think it 
will be simpler to just use \(aq.

Branden, any opinion?

> 
>> We could add somewhere in man-pages(7) that decimal numbers should use a 
>> separator every 3 digits, and hex and binary should use it every 4 digits.
> As well as the 3 decimal, 4 binary/hex, we could use yyyy'mm['dd]L for POSIX and 
> similar date digit strings, and 0x10'ffff for Unicode code points, 
> distinguishing between the Basic and Supplementary Multilingual Plane indices 
> and codes, just as examples from what I've seen so far.
> 
> I've also noticed a lot of apparently random decimal digit strings that are 
> binary powers or close deltas: those would be more comprehensible if rendered in 
> text as Ki/Mi/Gi[+/-n], so would that be preferable, using the IEC i suffix to 
> avoid ambiguity?

In running text, I'd do it case by case.  In some cases I guess that'll make 
sense.  In others, 2^32 will make more sense...  But yes, big magic fatnums are 
not nice.

> 
>>> As well as the recently modified pages:
>>>
>  >> clock_getres.2
>  >> timer_settime.2
>  >> timerfd_create.2
>  >> utimensat.2
>>>
>>> there appear to be obvious occurrences in only the following pages:
>>>
>  >> futex.2
>  >> read.2
>  >> sendfile.2
>  >> write.2
>  >> mallopt.3
>  >> keyrings.7
>  >> mq_overview.7
>  >> sched.7
>  >> time_namespaces.7
>>>
>>> but there appear to be about 400 pages with more than 6 decimal digit
>>> strings (some spurious glibc hex commits and address outputs) where it
>>> could perhaps help, such as in POSIX version dates e.g. 2001'12L, and
>>> undoubtedly more with long digit strings in other radixes.
>> Would you mind preparing a patch for all of those?  If you'll do it, better
>> wait until we merge наб's patches, to avoid conflicts.
> I'll start anyway, need to review over 300 files with over 900 digit strings, 
> having cut a bunch more pages with output examples.

Sure.

> 
> Any particular subdivision of files patched into git logged patches, by section, 
> by type of edit, separate logged patches for files with many edits, or...?

Whatever you prefer, I guess.  I think the first division I'd do is in the kind 
of change, and then in the section within a page where it appears.  But, you 
write it, so I guess you'll find the best separation.  As long as patches are 
consistent enough to not have many context switches when reviewing, it should be 
good.

> 
> FYI although many hits are likely output, the top candidates so far are:
> 
> 80 man5/proc.5
> 55 man2/statfs.2
> 34 man7/feature_test_macros.7
> 32 man3/dl_iterate_phdr.3
> 30 man7/units.7
> 30 man5/rpc.5
> 23 man3/termios.3
> 20 man3/malloc_info.3
> 17 man2/userfaultfd.2
> 16 man7/keyrings.7
> 15 man7/time_namespaces.7
> 14 man7/posixoptions.7
> 14 man3/mallopt.3
> 13 man7/utf-8.7
> 12 man2/reboot.2
> 12 man2/keyctl.2
> 

Cheers,

Alex
-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Using C23 digit separators not locale digit grouping characters

[Brian Inglis]

[-- Attachment #1: Type: text/plain, Size: 3473 bytes --]

On 2023-01-29 14:19, Alejandro Colomar wrote:
> On 1/29/23 22:04, Brian Inglis wrote:
>> On 2023-01-29 07:38, Alejandro Colomar wrote:
>>> On 1/28/23 21:40, Brian Inglis wrote:
>>>> Seeing the recent tv_nsec patches drop the standard locale digit grouping 
>>>> characters "," from the member range [0-999,999,999] made me regret the loss 
>>>> of the punctuation which provides better and quicker comprehension of long 
>>>> strings of digits.
>>> Nice! Didn't remember about that separator.  It makes a lot of sense to use 
>>> it in comments and the likes in the pages.  Maybe we should be a bit more 
>>> cautious in source code examples, but definitely for big numbers outside of 
>>> running code should have them.
> Since most people would be compiling on default settings, I prefer avoiding 
> that.  When c23 is finally released, and GCC switches to gnu23 by default, I'd 
> also use it in example programs.  Does it make sense to you?
>>>> It may be time to consider using the locale independent C23 digit
>>>> separator characters "'" wherever more than a handful of digits occur,
>>>> possibly convert grouping character uses in existing man pages as they are
>>>> changed, and specify a future standard policy approach to provide better
>>>> and quicker comprehension of long strings of digits: perhaps using a new
>>>> digit separator register and glyph escape sequence \*ds \*[ds] \[ds] \(ds
>>>> if not in use by base groff?
>>> The sequence for the unslanted single quote is \(aq.
> We have little semantic things in man(7), as opposed to mdoc(7).  I think it 
> will be simpler to just use \(aq.
>>> We could add somewhere in man-pages(7) that decimal numbers should use a 
						and octal e.g. perms
>>> separator every 3 digits, and hex and binary should use it every 4 digits >> As well as the 3 decimal, 4 binary/hex, we could use yyyy'mm['dd]L for POSIX
>> and similar date digit strings, and 0x10'ffff for Unicode code points, 
>> distinguishing between the Basic and Supplementary Multilingual Plane indices 
>> and codes, just as examples from what I've seen so far.
>> I've also noticed a lot of apparently random decimal digit strings that are 
>> binary powers or close deltas: those would be more comprehensible if rendered 
>> in text as Ki/Mi/Gi[+/-n], so would that be preferable, using the IEC i suffix 
>> to avoid ambiguity?
> In running text, I'd do it case by case.  In some cases I guess that'll make 
> sense.  In others, 2^32 will make more sense...  But yes, big magic fatnums are 
> not nice.

Hi Alex,

Took your views on board and changed man2 pages.
Attached summary only has file names and changed lines.
Would like feedback on what to continue doing and what to forget doing before 
starting man3?
Of note for review are open.2 octal perms, reboot.2 LINUX_REBOOT_MAGIC* adding 
hex birth dates (arguably should remove the decimals, or all values, and cryptic 
comment from doc?), statsf.2 hex *_MAGIC, changing large arbitrary values to 
SI/IEC suffix forms (as the exact decimal values are not as informative or 
useful), and feature docs using yyyy\(aqmmL (no example *code* was changed, 
although comments were).

-- 
Take care. Thanks, Brian Inglis			Calgary, Alberta, Canada

La perfection est atteinte			Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter	not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer	but when there is no more to cut
			-- Antoine de Saint-Exupéry

[-- Attachment #2: man2.diff --]
[-- Type: text/plain, Size: 14007 bytes --]

diff --git a/man2/add_key.2 b/man2/add_key.2
-of up to 32,767 bytes.
+of up to 32\(aq767 bytes.
diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
-the supplied value is clamped to the range (\-32768000, +32768000).
+the supplied value is clamped to the range (\-31.25Mi, +31.25Mi).
-to a value outside the range (\-33554432, +33554432).
+to a value outside the range (\-32Mi, +32Mi).
-Before Linux 2.0, the permitted range was (\-131072, +131072).
-From Linux 2.0 onwards, the permitted range was (\-512000, +512000).
+Before Linux 2.0, the permitted range was (\-128Ki, +128Ki).
+From Linux 2.0 onwards, the permitted range was (\-512k, +512k).
-.RB 900000/ HZ
+.RB 900k/ HZ
-.RB 1100000/ HZ ,
+.RB 1\(aq100k/ HZ ,
diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
-is outside the range [0..999,999,999].
+is outside the range [0..999\(aq999\(aq999].
diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
-field was not in the range 0 to 999999999 or
+field was not in the range 0 to 999\(aq999\(aq999 or
diff --git a/man2/eventfd.2 b/man2/eventfd.2
-unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe).
+unsigned 64-bit value minus 1 (i.e., 0xffff\(aqffff\(aqffff\(aqfffe).
-or if an attempt is made to write the value 0xffffffffffffffff.
+or if an attempt is made to write the value 0xffff\(aqffff\(aqffff\(aqffff.
-value (i.e., 0xffffffffffffffff).
+value (i.e., 0xffff\(aqffff\(aqffff\(aqffff).
diff --git a/man2/execve.2 b/man2/execve.2
-and the maximum number of strings is 0x7FFFFFFF.
+and the maximum number of strings is 0x7FFF\(aqFFFF.
diff --git a/man2/fcntl.2 b/man2/fcntl.2
-with the value 200809L or greater.)
+with the value 2008\(aq09L or greater.)
-with the value 200809L or greater, or
+with the value 2008\(aq09L or greater, or
diff --git a/man2/futex.2 b/man2/futex.2
-was not less than 1,000,000,000).
+was not less than 1\(aq000\(aq000\(aq000).
diff --git a/man2/getitimer.2 b/man2/getitimer.2
-contains a value outside the range 0 to 999999.
+contains a value outside the range 0 to 999\(aq999.
-value is specified that is outside of the range 0 to 999999.
+value is specified that is outside of the range 0 to 999\(aq999.
diff --git a/man2/getrandom.2 b/man2/getrandom.2
-source, a maximum of 33554431 bytes is returned by a single call to
+source, a maximum of 32Mi-1 bytes is returned by a single call to
diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2
-is outside the range [0..999,999].
+is outside the range [0..999\(aq999].
diff --git a/man2/ioctl.2 b/man2/ioctl.2
-0x00005401, with 0x54 = \(aqT\(aq indicating the terminal driver, and
+0x00\(aq00\(aq54\(aq01, with 0x54 = \(aqT\(aq indicating the terminal driver, and
-has value 0x00435906, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq
+has value 0x00\(aq43\(aq59\(aq06, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq
diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2
-= 1193180/frequency).
+= 1\(aq193\(aq180/frequency).
diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2
-For example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem will
+For example, if the low key is set to (8:0, 36\(aq864, 0, 0, 0), the filesystem will
-If the high key is set to (8:0, 1048576, 0, 0, 0),
+If the high key is set to (8:0, 1\(aq048\(aq576, 0, 0, 0),
diff --git a/man2/ioperm.2 b/man2/ioperm.2
-Since Linux 2.6.8, 65,536 I/O ports can be specified.
+Since Linux 2.6.8, 65\(aq536 I/O ports can be specified.
diff --git a/man2/kexec_load.2 b/man2/kexec_load.2
-The high-order bits (corresponding to the mask 0xffff0000) of
+The high-order bits (corresponding to the mask 0xffff\(aq0000) of
diff --git a/man2/link.2 b/man2/link.2
-feature, the limit on the number of hard links to a file is 65,000; on
+feature, the limit on the number of hard links to a file is 65\(aq000; on
-the limit is 65,535 links.
+the limit is 65\(aq535 links.
diff --git a/man2/msgget.2 b/man2/msgget.2
-Since Linux 3.19, the default value is 32,000.
+Since Linux 3.19, the default value is 32\(aq000.
diff --git a/man2/nanosleep.2 b/man2/nanosleep.2
-The value of the nanoseconds field must be in the range 0 to 999999999.
+The value of the nanoseconds field must be in the range 0 to 999\(aq999\(aq999.
-field was not in the range 0 to 999999999 or
+field was not in the range 0 to 999\(aq999\(aq999 or
diff --git a/man2/open.2 b/man2/open.2
-00700 user (file owner) has read, write, and execute permission
+00\(aq700 user (file owner) has read, write, and execute permission
-00400 user has read permission
+00\(aq400 user has read permission
-00200 user has write permission
+00\(aq200 user has write permission
-00100 user has execute permission
+00\(aq100 user has execute permission
-00070 group has read, write, and execute permission
+00\(aq070 group has read, write, and execute permission
-00040 group has read permission
+00\(aq040 group has read permission
-00020 group has write permission
+00\(aq020 group has write permission
-00010 group has execute permission
+00\(aq010 group has execute permission
-00007 others have read, write, and execute permission
+00\(aq007 others have read, write, and execute permission
-00004 others have read permission
+00\(aq004 others have read permission
-00002 others have write permission
+00\(aq002 others have write permission
-00001 others have execute permission
+00\(aq001 others have execute permission
-0004000 set-user-ID bit
+0\(aq004\(aq000 set-user-ID bit
-0002000 set-group-ID bit (see
+0\(aq002\(aq000 set-group-ID bit (see
-0001000 sticky bit (see
+0\(aq001\(aq000 sticky bit (see
-with a value greater than or equal to 200809L or
+with a value greater than or equal to 2008\(aq09L or
diff --git a/man2/pciconfig_read.2 b/man2/pciconfig_read.2
-memory offset (for things like prep, this is 0xc0000000),
+memory offset (for things like prep, this is 0xc000\(aq0000),
diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
-100000 (samples per second).
+100\(aq000 (samples per second).
diff --git a/man2/personality.2 b/man2/personality.2
-0xffffffff, then
+0xffff\(aqffff, then
-as 0xffffffff provides a way of retrieving
+as 0xffff\(aqffff provides a way of retrieving
-With this flag set, use 0xc0000000 as the offset at which to search
+With this flag set, use 0xc000\(aq0000 as the offset at which to search
-otherwise use 0xffffe000.
+otherwise use 0xffff\(aqe000.
diff --git a/man2/prctl.2 b/man2/prctl.2
-are 50,000 nanoseconds (50 microseconds).
+are 50\(aq000 nanoseconds (50 microseconds).
diff --git a/man2/read.2 b/man2/read.2
-0x7ffff000 (2,147,479,552) bytes,
+0x7fff\(aqf000 (2\(aq147\(aq479\(aq552) bytes,
diff --git a/man2/reboot.2 b/man2/reboot.2
-(that is, 0xfee1dead) and
+(that is, 0xfee1\(aqdead) and
-(that is, 672274793).
+(that is, 672\(aq274\(aq793 0x2812\(aq1969).
-(that is, 85072278)
+(that is, 85\(aq072\(aq278 0x0512\(aq1996)
-(that is, 369367448)
+(that is, 369\(aq367\(aq448 0x1604\(aq1998)
-(that is, 537993216)
+(that is, 537\(aq993\(aq216 0x2011\(aq2000)
-0x89abcdef).
+0x89ab\(aqcdef).
-0xcdef0123; since Linux 1.1.76).
+0xcdef\(aq0123; since Linux 1.1.76).
-0x45584543, since Linux 2.6.13).
+0x4558\(aq4543, since Linux 2.6.13).
-0x4321fedc; since Linux 2.1.30).
+0x4321\(aqfedc; since Linux 2.1.30).
-0x1234567).
+0x0123\(aq4567).
-(0xa1b2c3d4; since Linux 2.1.30).
+(0xa1b2\(aqc3d4; since Linux 2.1.30).
-0xd000fce1; since Linux 2.5.18).
+0xd000\(aqfce1; since Linux 2.5.18).
diff --git a/man2/semget.2 b/man2/semget.2
-the default value is 32,000.
+the default value is 32\(aq000.
-the default value is 32,000.
+the default value is 32\(aq000.
diff --git a/man2/sendfile.2 b/man2/sendfile.2
-will transfer at most 0x7ffff000 (2,147,479,552) bytes,
+will transfer at most 0x7fff\(aqf000 (2\(aq147\(aq479\(aq552) bytes,
diff --git a/man2/shmget.2 b/man2/shmget.2
-this limit was 0x2000000 (32\ MB).
+this limit was 0x200\(aq0000 (32\ MiB).
diff --git a/man2/sigaction.2 b/man2/sigaction.2
-    _POSIX_C_SOURCE >= 199309L
+    _POSIX_C_SOURCE >= 1993\(aq09L
-with the value 200809L or greater.
+with the value 2008\(aq09L or greater.
diff --git a/man2/spu_run.2 b/man2/spu_run.2
-.B 0x3fff0000
+.B 0x3fff\(aq0000
-     * We should see a status code of 0x1234002:
-     *   0x00000002 (spu was stopped due to stop\-and\-signal)
-     * | 0x12340000 (the stop\-and\-signal code)
+     * We should see a status code of 0x1234\(aq0002:
+     *   0x0000\(aq0002 (spu was stopped due to stop\-and\-signal)
+     * | 0x1234\(aq0000 (the stop\-and\-signal code)
diff --git a/man2/statfs.2 b/man2/statfs.2
-AFS_SUPER_MAGIC       0x5346414f
-ANON_INODE_FS_MAGIC   0x09041934 /* Anonymous inode FS (for
+AFS_SUPER_MAGIC       0x5346\(aq414f
+ANON_INODE_FS_MAGIC   0x0904\(aq1934 /* Anonymous inode FS (for
-BDEVFS_MAGIC          0x62646576
-BEFS_SUPER_MAGIC      0x42465331
-BFS_MAGIC             0x1badface
-BINFMTFS_MAGIC        0x42494e4d
-BPF_FS_MAGIC          0xcafe4a11
-BTRFS_SUPER_MAGIC     0x9123683e
-BTRFS_TEST_MAGIC      0x73727279
-CGROUP_SUPER_MAGIC    0x27e0eb   /* Cgroup pseudo FS */
-CGROUP2_SUPER_MAGIC   0x63677270 /* Cgroup v2 pseudo FS */
-CIFS_MAGIC_NUMBER     0xff534d42
-CODA_SUPER_MAGIC      0x73757245
-COH_SUPER_MAGIC       0x012ff7b7
-CRAMFS_MAGIC          0x28cd3d45
-DEBUGFS_MAGIC         0x64626720
+BDEVFS_MAGIC          0x6264\(aq6576
+BEFS_SUPER_MAGIC      0x4246\(aq5331
+BFS_MAGIC             0x1bad\(aqface
+BINFMTFS_MAGIC        0x4249\(aq4e4d
+BPF_FS_MAGIC          0xcafe\(aq4a11
+BTRFS_SUPER_MAGIC     0x9123\(aq683e
+BTRFS_TEST_MAGIC      0x7372\(aq7279
+CGROUP_SUPER_MAGIC    0x27\(aqe0eb   /* Cgroup pseudo FS */
+CGROUP2_SUPER_MAGIC   0x6367\(aq7270 /* Cgroup v2 pseudo FS */
+CIFS_MAGIC_NUMBER     0xff53\(aq4d42
+CODA_SUPER_MAGIC      0x7375\(aq7245
+COH_SUPER_MAGIC       0x012f\(aqf7b7
+CRAMFS_MAGIC          0x28cd\(aq3d45
+DEBUGFS_MAGIC         0x6462\(aq6720
-EFIVARFS_MAGIC        0xde5e81e4
-EFS_SUPER_MAGIC       0x00414a53
+EFIVARFS_MAGIC        0xde5e\(aq81e4
+EFS_SUPER_MAGIC       0x0041\(aq4a53
-F2FS_SUPER_MAGIC      0xf2f52010
-FUSE_SUPER_MAGIC      0x65735546
-FUTEXFS_SUPER_MAGIC   0xbad1dea  /* Unused */
+F2FS_SUPER_MAGIC      0xf2f5\(aq2010
+FUSE_SUPER_MAGIC      0x6573\(aq5546
+FUTEXFS_SUPER_MAGIC   0xbad\(aq1dea  /* Unused */
-HOSTFS_SUPER_MAGIC    0x00c0ffee
-HPFS_SUPER_MAGIC      0xf995e849
-HUGETLBFS_MAGIC       0x958458f6
+HOSTFS_SUPER_MAGIC    0x00c0\(aqffee
+HPFS_SUPER_MAGIC      0xf995\(aqe849
+HUGETLBFS_MAGIC       0x9584\(aq58f6
-JFS_SUPER_MAGIC       0x3153464a
+JFS_SUPER_MAGIC       0x3153\(aq464a
-MQUEUE_MAGIC          0x19800202 /* POSIX message queue FS */
+MQUEUE_MAGIC          0x1980\(aq0202 /* POSIX message queue FS */
-MTD_INODE_FS_MAGIC    0x11307854
+MTD_INODE_FS_MAGIC    0x1130\(aq7854
-NSFS_MAGIC            0x6e736673
-NTFS_SB_MAGIC         0x5346544e
-OCFS2_SUPER_MAGIC     0x7461636f
+NSFS_MAGIC            0x6e73\(aq6673
+NTFS_SB_MAGIC         0x5346\(aq544e
+OCFS2_SUPER_MAGIC     0x7461\(aq636f
-OVERLAYFS_SUPER_MAGIC 0x794c7630
-PIPEFS_MAGIC          0x50495045
+OVERLAYFS_SUPER_MAGIC 0x794c\(aq7630
+PIPEFS_MAGIC          0x5049\(aq5045
-PSTOREFS_MAGIC        0x6165676c
+PSTOREFS_MAGIC        0x6165\(aq676c
-QNX6_SUPER_MAGIC      0x68191122
-RAMFS_MAGIC           0x858458f6
-REISERFS_SUPER_MAGIC  0x52654973
+QNX6_SUPER_MAGIC      0x6819\(aq1122
+RAMFS_MAGIC           0x8584\(aq58f6
+REISERFS_SUPER_MAGIC  0x5265\(aq4973
-SECURITYFS_MAGIC      0x73636673
-SELINUX_MAGIC         0xf97cff8c
-SMACK_MAGIC           0x43415d53
+SECURITYFS_MAGIC      0x7363\(aq6673
+SELINUX_MAGIC         0xf97c\(aqff8c
+SMACK_MAGIC           0x4341\(aq5d53
-SMB2_MAGIC_NUMBER     0xfe534d42
-SOCKFS_MAGIC          0x534f434b
-SQUASHFS_MAGIC        0x73717368
-SYSFS_MAGIC           0x62656572
-SYSV2_SUPER_MAGIC     0x012ff7b6
-SYSV4_SUPER_MAGIC     0x012ff7b5
-TMPFS_MAGIC           0x01021994
-TRACEFS_MAGIC         0x74726163
-UDF_SUPER_MAGIC       0x15013346
-UFS_MAGIC             0x00011954
+SMB2_MAGIC_NUMBER     0xfe53\(aq4d42
+SOCKFS_MAGIC          0x534f\(aq434b
+SQUASHFS_MAGIC        0x7371\(aq7368
+SYSFS_MAGIC           0x6265\(aq6572
+SYSV2_SUPER_MAGIC     0x012f\(aqf7b6
+SYSV4_SUPER_MAGIC     0x012f\(aqf7b5
+TMPFS_MAGIC           0x0102\(aq1994
+TRACEFS_MAGIC         0x7472\(aq6163
+UDF_SUPER_MAGIC       0x1501\(aq3346
+UFS_MAGIC             0x0001\(aq1954
-V9FS_MAGIC            0x01021997
-VXFS_SUPER_MAGIC      0xa501fcf5
-XENFS_SUPER_MAGIC     0xabba1974
-XENIX_SUPER_MAGIC     0x012ff7b4
-XFS_SUPER_MAGIC       0x58465342
-_XIAFS_SUPER_MAGIC    0x012fd16d /* Linux 2.0 and earlier */
+V9FS_MAGIC            0x0102\(aq1997
+VXFS_SUPER_MAGIC      0xa501\(aqfcf5
+XENFS_SUPER_MAGIC     0xabba\(aq1974
+XENIX_SUPER_MAGIC     0x012f\(aqf7b4
+XFS_SUPER_MAGIC       0x5846\(aq5342
+_XIAFS_SUPER_MAGIC    0x012f\(aqd16d /* Linux 2.0 and earlier */
diff --git a/man2/statx.2 b/man2/statx.2
-with the value 0x80000000U.)
+with the value 0x8000\(aq0000U.)
diff --git a/man2/syscall.2 b/man2/syscall.2
-ia64	break 0x100000	r15	r8	r9	r10	1, 6
+ia64	break 0x10\(aq0000	r15	r8	r9	r10	1, 6
diff --git a/man2/timer_settime.2 b/man2/timer_settime.2
-    _POSIX_C_SOURCE >= 199309L
+    _POSIX_C_SOURCE >= 1993\(aq09L
-is negative or greater than 999,999,999.
+is negative or greater than 999\(aq999\(aq999.
diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
-falls outside the range zero to 999,999,999).
+falls outside the range zero to 999\(aq999\(aq999).
diff --git a/man2/truncate.2 b/man2/truncate.2
-or an entire pathname exceeded 1023 characters.
+or an entire pathname exceeded 1\(aq023 characters.
-was 200809L instead of 200112L.
+was 2008\(aq09L instead of 2001\(aq12L.
diff --git a/man2/utimensat.2 b/man2/utimensat.2
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\(aq09L
-        _POSIX_C_SOURCE >= 200809L
+        _POSIX_C_SOURCE >= 2008\(aq09L
-fields (value outside range 0 to 999,999,999, and not
+fields (value outside range 0 to 999\(aq999\(aq999, and not
diff --git a/man2/write.2 b/man2/write.2
-0x7ffff000 (2,147,479,552) bytes,
+0x7fff\(aqf000 (2\(aq147\(aq479\(aq552) bytes,

Re: Using C23 digit separators not locale digit grouping characters

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3647 bytes --]

On 2/2/23 23:29, Brian Inglis wrote:> Hi Alex,

Hi Brian,

> 
> Took your views on board and changed man2 pages.
> Attached summary only has file names and changed lines.

I prefer inline in the email :)

> Would like feedback on what to continue doing and what to forget doing before 
> starting man3?

See below.

> Of note for review are open.2 octal perms,

The octals read a bit weirder than the others.  Please keep them in a separate 
patch, so we can decide on it later.  But I wouldn't discard it for now.

> reboot.2 LINUX_REBOOT_MAGIC* adding 
> hex birth dates

LGTM

> (arguably should remove the decimals, or all values, and cryptic 
> comment from doc?),

Not sure what you mean.

> statsf.2 hex *_MAGIC,

LGTM

> changing large arbitrary values to 
> SI/IEC suffix forms (as the exact decimal values are not as informative or 
> useful),

But I'd use multipliers that result in exact values.  See below.

> and feature docs using yyyy\(aqmmL (no example *code* was changed, 
> although comments were).

LGTM.


---


-the supplied value is clamped to the range (\-32768000, +32768000).
+the supplied value is clamped to the range (\-31.25Mi, +31.25Mi).

I'd prefer here (\-32000Ki, +32000Ki).  Decimals on multipliers induce doubts on 
how much precision you kept; round numbers make it clear.


-is outside the range [0..999,999,999].
+is outside the range [0..999\(aq999\(aq999].

Please fix also the format of the range, now that you're at it (in a separate 
commit, if you don't mind).  I prefer mathematical notation, where possible: [0, 
999'999'999].


-field was not in the range 0 to 999999999 or
+field was not in the range 0 to 999\(aq999\(aq999 or

Same here: [0, 999'999'999]


-source, a maximum of 33554431 bytes is returned by a single call to
+source, a maximum of 32Mi-1 bytes is returned by a single call to

When the value is not an exact one, as here where it's the multiplier minus one, 
I prefer a more correct mathematical notation: 2^25-1


-(that is, 0xfee1dead) and
+(that is, 0xfee1\(aqdead) and
-(that is, 672274793).
+(that is, 672\(aq274\(aq793 0x2812\(aq1969).
-(that is, 85072278)
+(that is, 85\(aq072\(aq278 0x0512\(aq1996)
-(that is, 369367448)
+(that is, 369\(aq367\(aq448 0x1604\(aq1998)
-(that is, 537993216)
+(that is, 537\(aq993\(aq216 0x2011\(aq2000)

In these cases, where you added the hex equivalent, I think it would need a 
comma as a separator, and maybe some connector?


-this limit was 0x2000000 (32\ MB).
+this limit was 0x200\(aq0000 (32\ MiB).

Could you please separate the bugfixes such as this one in a different patch, if 
you don't mind?  I don't care about the order of them, though.


-AFS_SUPER_MAGIC       0x5346414f
-ANON_INODE_FS_MAGIC   0x09041934 /* Anonymous inode FS (for
+AFS_SUPER_MAGIC       0x5346\(aq414f
+ANON_INODE_FS_MAGIC   0x0904\(aq1934 /* Anonymous inode FS (

I'm getting a bit confusing while reading the diff.  The \(aq syntax is 
definitely a bit confusing when mixed with other random characters that the 
brain doesn't recognize as words.  We can solve this by using \[aq] notation, 
which I like more personally.  Please use this syntax.  We'll also need some 
global fixes to change the notation all across the pages.  I'm not asking you to 
do this though.  It's probably a lot of work.  I can do that after your patches.


Other than those minor comments, I like the diff very much.  Please continue :)

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Using C23 digit separators not locale digit grouping characters

[Tom Schwindl]

Hi Alex,

On Fri Feb 3, 2023 at 12:59 AM CET, Alejandro Colomar wrote:
> On 2/2/23 23:29, Brian Inglis wrote:> Hi Alex,
>
> Hi Brian,
>
> > 
> > Took your views on board and changed man2 pages.
> > Attached summary only has file names and changed lines.
>
> I prefer inline in the email :)
>
> > Would like feedback on what to continue doing and what to forget doing before 
> > starting man3?
>
> See below.
>
> > Of note for review are open.2 octal perms,
>
> The octals read a bit weirder than the others.  Please keep them in a separate 
> patch, so we can decide on it later.  But I wouldn't discard it for now.
>

I wonder if I'm the only one who thinks that the digit separators look
irritating for both, hex and octal. The reason for using them in the first place
is to make numbers more readable and thus get them "out of the way".
As of my experience, it's not common to use separators for neither hex or octal.
I think we're going against what people are used to and more importantly, what
is generally found in code and documentation. We might archive the opposite of
what we try to do.

Just my 2 cents.

--
Best Regards,
Tom Schwindl

Re: Using C23 digit separators not locale digit grouping characters

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2422 bytes --]

Hi Tom

On 2/3/23 14:27, Tom Schwindl wrote:
> Hi Alex,
> 
> On Fri Feb 3, 2023 at 12:59 AM CET, Alejandro Colomar wrote:
>> On 2/2/23 23:29, Brian Inglis wrote:> Hi Alex,
>>
>> Hi Brian,
>>
>>>
>>> Took your views on board and changed man2 pages.
>>> Attached summary only has file names and changed lines.
>>
>> I prefer inline in the email :)
>>
>>> Would like feedback on what to continue doing and what to forget doing before
>>> starting man3?
>>
>> See below.
>>
>>> Of note for review are open.2 octal perms,
>>
>> The octals read a bit weirder than the others.  Please keep them in a separate
>> patch, so we can decide on it later.  But I wouldn't discard it for now.
>>
> 
> I wonder if I'm the only one who thinks that the digit separators look
> irritating for both, hex and octal.

Hex ones don't seem weird to to me.
Octal does.  However, I've always been irritated by octals, due to the prefix 
being confused with part of the value.  I'd prefer C introducing Python's 0o prefix.

> The reason for using them in the first place
> is to make numbers more readable and thus get them "out of the way".
> As of my experience, it's not common to use separators for neither hex or octal.

Of course it's not common.  They didn't exist before :)
In decimals we use them because non-programming contexts always had them.  Since 
hexs are almost exclusive of programming, it's normal that tradition doesn't 
have them.  However, we use spaces often for hexs and binaries, especially in 
classes, to help distinguish the magnitude of the number, and improve 
readability in general.  I think using a standard separator is the best thing we 
can use (spaces in the man pages would be mnisleading).

> I think we're going against what people are used to and more importantly, what
> is generally found in code and documentation. We might archive the opposite of
> what we try to do.

That's true.  We're doing some important changes, which is why I want to be 
careful.  IMO, I think the patches improve the documentation, but if there's 
general consensus that it will be worse, we can revert them any time, so let's 
see how this develops.

> 
> Just my 2 cents.
> 
> --
> Best Regards,
> Tom Schwindl

Thanks for the comments!

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Using C23 digit separators not locale digit grouping characters

[Jakub Wilk]

* Tom Schwindl <schwindl@posteo.de>, 2023-02-03 13:27:
>I wonder if I'm the only one who thinks that the digit separators look 
>irritating for both, hex and octal.

Not only you.

I think C23's choice of separator is particularly bad. I found underscores 
(used in Perl, Ruby, Python 3, Java, Rust, and likely many others) more 
palatable.

-- 
Jakub Wilk

Re: Using C23 digit separators not locale digit grouping characters

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1085 bytes --]

Hi Jakub!

On 2/8/23 22:00, Jakub Wilk wrote:
> * Tom Schwindl <schwindl@posteo.de>, 2023-02-03 13:27:
>> I wonder if I'm the only one who thinks that the digit separators look 
>> irritating for both, hex and octal.
> 
> Not only you.
> 
> I think C23's choice of separator is particularly bad. I found underscores 
> (used in Perl, Ruby, Python 3, Java, Rust, and likely many others) more 
> palatable.

IIRC, that was suggested at some point for C23, but don't remember; maybe it's a glitch in my memory (I think it was suggested for separating binary (0b) input).  I can't understand how they chose ', especially when in some countries it's used as the decimal point  (I don't know if that's official, but I've seen it in hand-written text quite often here in Spain).  I agree that it's probably one of the worst separators they could have chosen.

Do you think we should use an underscore in the manual pages?  Or what would you do?

Thanks,

Alex

> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Using C23 digit separators not locale digit grouping characters

[Brian Inglis]

On 2023-02-08 14:06, Alejandro Colomar wrote:
> Hi Jakub!
> 
> On 2/8/23 22:00, Jakub Wilk wrote:
>> * Tom Schwindl <schwindl@posteo.de>, 2023-02-03 13:27:
>>> I wonder if I'm the only one who thinks that the digit separators look
>>> irritating for both, hex and octal.
>>
>> Not only you.
>>
>> I think C23's choice of separator is particularly bad. I found underscores
>> (used in Perl, Ruby, Python 3, Java, Rust, and likely many others) more
>> palatable.
> 
> IIRC, that was suggested at some point for C23, but don't remember; maybe it's a glitch in my memory (I think it was suggested for separating binary (0b) input).  I can't understand how they chose ', especially when in some countries it's used as the decimal point  (I don't know if that's official, but I've seen it in hand-written text quite often here in Spain).  I agree that it's probably one of the worst separators they could have chosen.
> 
> Do you think we should use an underscore in the manual pages?  Or what would you do?

See discussion 10 years ago in WG21 C++:

	https://open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3499.html

where ambiguity with C++ user-defined literal unit operators and "_" was an 
issue, and Objective C/C++ parsing problems with using whitespace.

So in 2020 WG14 C, opting for compatibility with WG21 C++; quoting:

	Prior Art: C++, Intel ICC, EDG, Microsoft Visual Studio
in
	https://www.open-std.org/JTC1/SC22/WG14/www/docs/n2606.pdf
	https://www.open-std.org/JTC1/sc22/wg14/www/docs/n2626.pdf

FYI see comment in:

	https://thephd.dev/c-the-improvements-june-september-virtual-c-meeting

"Guess who uses apostrophes for digit separators! The SWISS! And who is in 
Switzerland? ISO! I see WG14 is no less corrupt than WG21.
	— Miro Knejp"	;^>

We are going to be seeing these used a lot in future from GCC , and as man-pages 
are immersed in a sea of C, we might as well start getting used to it, which is 
why I made that suggestion.

-- 
Take care. Thanks, Brian Inglis			Calgary, Alberta, Canada

La perfection est atteinte			Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter	not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer	but when there is no more to cut
			-- Antoine de Saint-Exupéry

Re: Using C23 digit separators not locale digit grouping characters

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1262 bytes --]

Hi Brian,

On 2/8/23 23:10, Brian Inglis wrote:
> See discussion 10 years ago in WG21 C++:
> 
> 	https://open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3499.html
> 
> where ambiguity with C++ user-defined literal unit operators and "_" was an 
> issue, and Objective C/C++ parsing problems with using whitespace.

Interesting.  Let it be a ' then.

> 
> So in 2020 WG14 C, opting for compatibility with WG21 C++; quoting:
> 
> 	Prior Art: C++, Intel ICC, EDG, Microsoft Visual Studio
> in
> 	https://www.open-std.org/JTC1/SC22/WG14/www/docs/n2606.pdf
> 	https://www.open-std.org/JTC1/sc22/wg14/www/docs/n2626.pdf
> 
> FYI see comment in:
> 
> 	https://thephd.dev/c-the-improvements-june-september-virtual-c-meeting
> 
> "Guess who uses apostrophes for digit separators! The SWISS! And who is in 
> Switzerland? ISO! I see WG14 is no less corrupt than WG21.
> 	— Miro Knejp"	;^>

I remember having read that :D

> 
> We are going to be seeing these used a lot in future from GCC , and as man-pages 
> are immersed in a sea of C, we might as well start getting used to it, which is 
> why I made that suggestion.

Agree.

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Using C23 digit separators not locale digit grouping characters

[Brian Inglis]

On 2023-02-02 16:59, Alejandro Colomar wrote:
> On 2/2/23 23:29, Brian Inglis wrote:> Hi Alex,
>> Took your views on board and changed man2 pages.
>> Attached summary only has file names and changed lines.
> I prefer inline in the email :)
>> Would like feedback on what to continue doing and what to forget doing before 
>> starting man3?
> See below.
>> Of note for review are open.2 octal perms,
> The octals read a bit weirder than the others.  Please keep them in a separate 
> patch, so we can decide on it later.  But I wouldn't discard it for now.

Intend to keep these noted large changes in separate commits, in case of such 
issues.

>> reboot.2 LINUX_REBOOT_MAGIC* adding hex birth dates
> LGTM
>> (arguably should remove the decimals, or all values, and cryptic comment from 
>> doc?),
> Not sure what you mean.

See below - decimal (and added hex) "BCD" values of Linus and kid's birthdates!

>> statsf.2 hex *_MAGIC,
> LGTM
>> changing large arbitrary values to SI/IEC suffix forms (as the exact decimal 
>> values are not as informative or useful),
> But I'd use multipliers that result in exact values.  See below.
>> and feature docs using yyyy\(aqmmL (no example *code* was changed, although 
>> comments were).
> LGTM.
>> -the supplied value is clamped to the range (\-32768000, +32768000).
>> +the supplied value is clamped to the range (\-31.25Mi, +31.25Mi).
> I'd prefer here (\-32000Ki, +32000Ki).  Decimals on multipliers induce doubts on 
> how much precision you kept; round numbers make it clear.

Dithered about representing 32kKi - again magnitude seemed more important to 
document, but did not consider using decimals might introduce uncertainty about 
precision!

>> -is outside the range [0..999,999,999].
>> +is outside the range [0..999\(aq999\(aq999].
> Please fix also the format of the range, now that you're at it (in a separate 
> commit, if you don't mind).  I prefer mathematical notation, where possible: [0, 
> 999'999'999].
>> -field was not in the range 0 to 999999999 or
>> +field was not in the range 0 to 999\(aq999\(aq999 or
> Same here: [0, 999'999'999]

If we are changing to consistent interval notation in a separate patch, should 
we replace the closed inclusive limit strings of "[0, ...999]" by open exclusive 
limits e.g. "[0, 1G)" etc. or would semi-open be too ambiguous, as intervals 
seen in the sample so far are either open (...) or closed [...]?
I presume doc readers have less familiarity with maths and computer arithmetic 
than engineers or technical devs may require.

>> -source, a maximum of 33554431 bytes is returned by a single call to
>> +source, a maximum of 32Mi-1 bytes is returned by a single call to
> When the value is not an exact one, as here where it's the multiplier minus one, 
> I prefer a more correct mathematical notation: 2^25-1

I don't think that notation is meaningful documentation to most readers.
The original decimal value is easier to comprehend.
Even the hex 0x2000000-1 would be a bit more informative (0x20Mi-1).
An odd binary power does not bring a value quickly to mind, and has to be 
decoded to 2^5*2^20-1 to make any sense: I had to evaluate it to be sure!
With large values, the magnitude is more important to get across clearly with 
binary or decimal suffixes, although the value must be exact.

>> -(that is, 0xfee1dead) and
>> +(that is, 0xfee1\(aqdead) and
>> -(that is, 672274793).
>> +(that is, 672\(aq274\(aq793 0x2812\(aq1969).
>> -(that is, 85072278)
>> +(that is, 85\(aq072\(aq278 0x0512\(aq1996)
>> -(that is, 369367448)
>> +(that is, 369\(aq367\(aq448 0x1604\(aq1998)
>> -(that is, 537993216)
>> +(that is, 537\(aq993\(aq216 0x2011\(aq2000)
> In these cases, where you added the hex equivalent, I think it would need a 
> comma as a separator, and maybe some connector?

That's the decimal and "BCD" values of Linus and kid's birthdates if you look at 
the hex, to which the following "...meaningful" comment refers.
Suggest we separate with a dash, or I wondered if we should just drop the "cute" 
values and comments?
They are in the header if anyone other than Linus cares.

>> -this limit was 0x2000000 (32\ MB).
>> +this limit was 0x200\(aq0000 (32\ MiB).
> Could you please separate the bugfixes such as this one in a different patch, if 
> you don't mind?  I don't care about the order of them, though.
>> -AFS_SUPER_MAGIC       0x5346414f
>> -ANON_INODE_FS_MAGIC   0x09041934 /* Anonymous inode FS (for
>> +AFS_SUPER_MAGIC       0x5346\(aq414f
>> +ANON_INODE_FS_MAGIC   0x0904\(aq1934 /* Anonymous inode FS (
> I'm getting a bit confusing while reading the diff. The \(aq syntax is 
> definitely a bit confusing when mixed with other random characters that the 
> brain doesn't recognize as words. We can solve this by using \[aq] notation, 
> which I like more personally. Please use this syntax. We'll also need some 
> global fixes to change the notation all across the pages. I'm not asking you
> to do this though. It's probably a lot of work. I can do that after your
> patches.

Agree here, that's why I wanted you to have a look at the changes first.

> Other than those minor comments, I like the diff very much.  Please continue :)

-- 
Take care. Thanks, Brian Inglis			Calgary, Alberta, Canada

La perfection est atteinte			Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter	not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer	but when there is no more to cut
			-- Antoine de Saint-Exupéry

Re: Using C23 digit separators not locale digit grouping characters

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 5462 bytes --]

Hi Brian,

On 2/4/23 08:19, Brian Inglis wrote:
[...]


>>> reboot.2 LINUX_REBOOT_MAGIC* adding hex birth dates
>> LGTM
>>> (arguably should remove the decimals, or all values, and cryptic comment from 
>>> doc?),
>> Not sure what you mean.
> 
> See below - decimal (and added hex) "BCD" values of Linus and kid's birthdates!
> 

[...]

>>> -the supplied value is clamped to the range (\-32768000, +32768000).
>>> +the supplied value is clamped to the range (\-31.25Mi, +31.25Mi).
>> I'd prefer here (\-32000Ki, +32000Ki).  Decimals on multipliers induce doubts 
>> on how much precision you kept; round numbers make it clear.
> 
> Dithered about representing 32kKi - again magnitude seemed more important to 
> document, but did not consider using decimals might introduce uncertainty about 
> precision!

Actually, I should have suggested 32'000Ki :p
> 
>>> -is outside the range [0..999,999,999].
>>> +is outside the range [0..999\(aq999\(aq999].
>> Please fix also the format of the range, now that you're at it (in a separate 
>> commit, if you don't mind).  I prefer mathematical notation, where possible: 
>> [0, 999'999'999].
>>> -field was not in the range 0 to 999999999 or
>>> +field was not in the range 0 to 999\(aq999\(aq999 or
>> Same here: [0, 999'999'999]
> 
> If we are changing to consistent interval notation in a separate patch, should 
> we replace the closed inclusive limit strings of "[0, ...999]" by open exclusive 
> limits e.g. "[0, 1G)" etc. or would semi-open be too ambiguous, as intervals 
> seen in the sample so far are either open (...) or closed [...]?
> I presume doc readers have less familiarity with maths and computer arithmetic 
> than engineers or technical devs may require.

For the general case, I think it's more readable to use closed intervals; they 
are more commonly used in the man-pages so far, so I guess people are more used 
to reading them.  However, we might consider exceptions if they are reasonable 
for some cases.  Regarding familiarity to programmers, I expect most of them 
would be familiar with semi-open intervals, and as Ingo reminded me recently, we 
use them everyday in C in the form of `for (int i = 0; i < n; i++)`, so I'm not 
averse to it just by that.  But we see closed intervals more often, probably 
because it removes one subtraction in your head and so it's simpler to read.

> 
>>> -source, a maximum of 33554431 bytes is returned by a single call to
>>> +source, a maximum of 32Mi-1 bytes is returned by a single call to
>> When the value is not an exact one, as here where it's the multiplier minus 
>> one, I prefer a more correct mathematical notation: 2^25-1
> 
> I don't think that notation is meaningful documentation to most readers.
> The original decimal value is easier to comprehend.

Agree, I just brainfarted.

> Even the hex 0x2000000-1 would be a bit more informative (0x20Mi-1).
> An odd binary power does not bring a value quickly to mind, and has to be 
> decoded to 2^5*2^20-1 to make any sense: I had to evaluate it to be sure!
> With large values, the magnitude is more important to get across clearly with 
> binary or decimal suffixes, although the value must be exact.

Agreed.  Let's try with 32Mi-1.

> 
>>> -(that is, 0xfee1dead) and
>>> +(that is, 0xfee1\(aqdead) and
>>> -(that is, 672274793).
>>> +(that is, 672\(aq274\(aq793 0x2812\(aq1969).
>>> -(that is, 85072278)
>>> +(that is, 85\(aq072\(aq278 0x0512\(aq1996)
>>> -(that is, 369367448)
>>> +(that is, 369\(aq367\(aq448 0x1604\(aq1998)
>>> -(that is, 537993216)
>>> +(that is, 537\(aq993\(aq216 0x2011\(aq2000)
>> In these cases, where you added the hex equivalent, I think it would need a 
>> comma as a separator, and maybe some connector?
> 
> That's the decimal and "BCD" values of Linus and kid's birthdates if you look at 
> the hex, to which the following "...meaningful" comment refers.
> Suggest we separate with a dash, or I wondered if we should just drop the "cute" 
> values and comments?

I'd rather drop the decimal values.  They are more meaningful as hex.

> They are in the header if anyone other than Linus cares.
> 
>>> -this limit was 0x2000000 (32\ MB).
>>> +this limit was 0x200\(aq0000 (32\ MiB).
>> Could you please separate the bugfixes such as this one in a different patch, 
>> if you don't mind?  I don't care about the order of them, though.
>>> -AFS_SUPER_MAGIC       0x5346414f
>>> -ANON_INODE_FS_MAGIC   0x09041934 /* Anonymous inode FS (for
>>> +AFS_SUPER_MAGIC       0x5346\(aq414f
>>> +ANON_INODE_FS_MAGIC   0x0904\(aq1934 /* Anonymous inode FS (
>> I'm getting a bit confusing while reading the diff. The \(aq syntax is 
>> definitely a bit confusing when mixed with other random characters that the 
>> brain doesn't recognize as words. We can solve this by using \[aq] notation, 
>> which I like more personally. Please use this syntax. We'll also need some 
>> global fixes to change the notation all across the pages. I'm not asking you
>> to do this though. It's probably a lot of work. I can do that after your
>> patches.
> 
> Agree here, that's why I wanted you to have a look at the changes first.
> 
>> Other than those minor comments, I like the diff very much.  Please continue :)
> 

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]