locale.5: document glibc conventions regarding days and week

From fc28ef135148e0b6c6546666422cc9999e64bfc3 Mon Sep 17 00:00:00 2001

Hi,

let's document glibc de facto current interpretation of handling weekdays also on the locale(5) man page, based on Petr's research in the past, currently documented in the glibc Locales wiki page.

Quoted 2 lines

From fc28ef135148e0b6c6546666422cc9999e64bfc3 Mon Sep 17 00:00:00 2001

From: Marko Myllynen <[email protected]>
Date: Mon, 26 May 2014 08:42:23 +0300
Subject: [PATCH] locale.5: document glibc conventions regarding days and week

Based on existing practice and glibc community wiki page at

https://sourceware.org/glibc/wiki/Locales

---
 man5/locale.5 |   69 +++++++++++++++++++++++++++++++++++++++++++-------------
 1 files changed, 53 insertions(+), 16 deletions(-)

man5/locale.5 +53 -17

index 2ad8e59..1b0f57d 100644
@@ -966,14 +966,14 @@ followed by a list of abbreviated names of the days of the week.
 The list starts with the first day of the week
 as specified by
 .I week
-(Sunday by default).
+(Sunday by default). See NOTES.
 .TP
 .I day
 followed by a list of names of the days of the week.
 The list starts with the first day of the week
 as specified by
 .I week
-(Sunday by default).
+(Sunday by default). See NOTES.
 .TP
 .I abmon
 followed by a list of abbreviated month names.

@@ -1011,16 +1011,7 @@ Regarding the start of the week,
 shall be used for Sunday and
 .B 19971201
 shall be used for Monday.
-Thus, countries using
-.B 19971130
-should have local Sunday name as the first day in the
-.I day
-list,
-while countries using
-.B 19971201
-should have Monday translation as the first item in the
-.I day
-list.
+See NOTES.
 .TP
 .IR first_weekday " (since glibc 2.2)"
 followed by the number of the first day from the

@@ -1031,12 +1022,12 @@ The default value of
 corresponds to either Sunday or Monday depending
 on the value of the second
 .I week
-list item.
+list item. See NOTES.
 .TP
 .IR first_workday " (since glibc 2.2)"
 followed by the number of the first working day from the
 .I day
-list.
+list. See NOTES.
 .TP
 .I cal_direction
 .\" from localedata/locales/uk_UA

@@ -1067,10 +1058,56 @@ definition ends with the string
 \(em database for the current locale setting of that category
 .br
 /usr/lib/nls/charmap/* \(em charmap-files
+.SH NOTES
+The collective GNU C library community wisdom regarding
+.IR day ,
+.IR week ,
+and
+.I first_weekday
+states at
+https://sourceware.org/glibc/wiki/Locales
+the following:
+.PP
+The value of the second
+.I week
+list item specifies the base of the
+.I day
+list.
+.PP
+.I first_weekday
+specifies the offset of the first day-of-week in the
+.I day
+list.
+.PP
+For compatibility reasons, all glibc locales should set the value of the
+second
+.I week
+list item to
+.B 19971130
+(Sunday) and base the
+.I day
+list appropriately, and set
+.I first_weekday
+to
+.B 1
+or
+.BR 2 ,
+depending on whether the week actually starts on Sunday or Monday
+for the locale.
+.PP
+Thus, a locale which week starts on Monday
+.I first_weekday
+and
+.I first_workday
+should be set to
+.B 2
+and
+.I abday
+and
+.I day
+should have the locale representation of Sunday as the first list item.
 .SH CONFORMING TO
 POSIX.2, ISO/IEC 14652.
-.SH BUGS
-This manual page isn't complete.
 .\" .SH AUTHOR
 .\" Jochen Hein ([email protected])
 .SH SEE ALSO
--

1.7.1

Thanks,

Looking at this patch more closely, there's a piece that seems to be broken.

That sentence is garbled. Some words are missing, I think. Can you clarify?

From 19a2e938158ffb94b0265968c6213a16b5179985 Mon Sep 17 00:00:00 2001

Hi,

Quoted 1 line · Michael Kerrisk (man-pages)

Quoted 3 lines

Looking at this patch more closely, there's a piece that seems to be broken.

That sentence is garbled. Some words are missing, I think. Can you clarify?

it was clumsy indeed, and also repetitive, I don't think it's needed at all as the previous paragraph already explains the same thing.

Please see an updated and rebased patch below.

From 19a2e938158ffb94b0265968c6213a16b5179985 Mon Sep 17 00:00:00 2001
From: Marko Myllynen <[email protected]>
Date: Wed, 28 May 2014 17:18:15 +0300
Subject: [PATCH] locale.5: document glibc conventions regarding days and week

Based on existing practice and glibc community wiki page at

https://sourceware.org/glibc/wiki/Locales

---
 man5/locale.5 |   59 +++++++++++++++++++++++++++++++++++++++++++++++---------
 1 files changed, 49 insertions(+), 10 deletions(-)

man5/locale.5 +49 -11

index 6f0538a..754a4e0 100644
@@ -975,6 +975,7 @@ The list starts with the first day of the week
 as specified by
 .I week
 (Sunday by default).
+See NOTES.
 .TP
 .I day
 followed by a list of names of the days of the week.

@@ -982,6 +983,7 @@ The list starts with the first day of the week
 as specified by
 .I week
 (Sunday by default).
+See NOTES.
 .TP
 .I abmon
 followed by a list of abbreviated month names.

@@ -1020,16 +1022,7 @@ Regarding the start of the week,
 shall be used for Sunday and
 .B 19971201
 shall be used for Monday.
-Thus, countries using
-.B 19971130
-should have local Sunday name as the first day in the
-.I day
-list,
-while countries using
-.B 19971201
-should have Monday translation as the first item in the
-.I day
-list.
+See NOTES.
 .TP
 .IR first_weekday " (since glibc 2.2)"
 followed by the number of the first day from the

@@ -1041,6 +1034,7 @@ corresponds to either Sunday or Monday depending
 on the value of the second
 .I week
 list item.
+See NOTES.
 .TP
 .IR first_workday " (since glibc 2.2)"
 followed by the number of the first working day from the

@@ -1048,6 +1042,7 @@ followed by the number of the first working day from the
 list.
 The default value is
 .BR 2 .
+See NOTES.
 .TP
 .I cal_direction
 .\" from localedata/locales/uk_UA

@@ -1080,6 +1075,50 @@ Usual default locale archive location.
 .TP
 .I /usr/share/i18n/locales
 Usual default path for locale definition files.
+.SH NOTES
+The collective GNU C library community wisdom regarding
+.IR abday ,
+.IR day ,
+.IR week ,
+.IR first_weekday ,
+and
+.I first_workday
+states at
+https://sourceware.org/glibc/wiki/Locales
+the following:
+.PP
+The value of the second
+.I week
+list item specifies the base of the
+.I abday
+and
+.I day
+lists.
+.PP
+.I first_weekday
+specifies the offset of the first day-of-week in the
+.I abday
+and
+.I day
+lists.
+.PP
+For compatibility reasons, all glibc locales should set the value of the
+second
+.I week
+list item to
+.B 19971130
+(Sunday) and base the
+.I abday
+and
+.I day
+lists appropriately, and set
+.I first_weekday
+to
+.B 1
+or
+.BR 2 ,
+depending on whether the week actually starts on Sunday or Monday
+for the locale.
 .SH CONFORMING TO
 POSIX.2, ISO/IEC TR 14652.
 .SH BUGS
--

1.7.1

Thanks,

--
Marko Myllynen

Quoted 6 lines · Marko Myllynen

Quoted 4 lines · Michael Kerrisk (man-pages)

Looking at this patch more closely, there's a piece that seems to be broken.

That sentence is garbled. Some words are missing, I think. Can you clarify?

Quoted 4 lines

it was clumsy indeed, and also repetitive, I don't think it's needed at all as the previous paragraph already explains the same thing.

Please see an updated and rebased patch below.

Best just to tell me what needs to be dropped from the preceding patch, since I've already merged and edited in a private branch.

Hi,

Quoted 10 lines · Michael Kerrisk (man-pages)

Quoted 9 lines · Marko Myllynen

Quoted 4 lines · Michael Kerrisk (man-pages)

Looking at this patch more closely, there's a piece that seems to be broken.

That sentence is garbled. Some words are missing, I think. Can you clarify?

it was clumsy indeed, and also repetitive, I don't think it's needed at all as the previous paragraph already explains the same thing.

Quoted 4 lines

Quoted 1 line

Please see an updated and rebased patch below.

Best just to tell me what needs to be dropped from the preceding patch, since I've already merged and edited in a private branch.

best to drop the sentence that was garbled. I'll double check it once it appears in a public branch.

Quoted 13 lines · Marko Myllynen

Quoted 12 lines · Michael Kerrisk (man-pages)

Quoted 10 lines · Marko Myllynen

Quoted 4 lines · Michael Kerrisk (man-pages)

Looking at this patch more closely, there's a piece that seems to be broken.

That sentence is garbled. Some words are missing, I think. Can you clarify?

it was clumsy indeed, and also repetitive, I don't think it's needed at all as the previous paragraph already explains the same thing.

Please see an updated and rebased patch below.

Quoted 5 lines

Quoted 2 lines

Best just to tell me what needs to be dropped from the preceding patch, since I've already merged and edited in a private branch.

best to drop the sentence that was garbled. I'll double check it once it appears in a public branch.

Done. And now the changes are published in Git.

From 4d8d8552aaf67f56278d1d8b90c88e531bfd111e Mon Sep 17 00:00:00 2001

Hi,

Quoted 17 lines · Michael Kerrisk (man-pages)

Quoted 16 lines · Marko Myllynen

Quoted 14 lines · Michael Kerrisk (man-pages)

Quoted 10 lines · Marko Myllynen

Quoted 4 lines · Michael Kerrisk (man-pages)

Looking at this patch more closely, there's a piece that seems to be broken.

That sentence is garbled. Some words are missing, I think. Can you clarify?

it was clumsy indeed, and also repetitive, I don't think it's needed at all as the previous paragraph already explains the same thing.

Please see an updated and rebased patch below.

Best just to tell me what needs to be dropped from the preceding patch, since I've already merged and edited in a private branch.

Quoted 4 lines

Quoted 2 lines

best to drop the sentence that was garbled. I'll double check it once it appears in a public branch.

Done. And now the changes are published in Git.

thanks, looks good, I'd add this tiny change to be explicit rather than implicit.

Quoted 1 line

From 4d8d8552aaf67f56278d1d8b90c88e531bfd111e Mon Sep 17 00:00:00 2001

From: Marko Myllynen <[email protected]>
Date: Wed, 28 May 2014 18:11:55 +0300
Subject: [PATCH] locale.5: minor NOTES clarification

---
 man5/locale.5 |   16 ++++++++++++----
 1 files changed, 12 insertions(+), 4 deletions(-)

man5/locale.5 +12 -4

index d762858..572833d 100644
@@ -1079,10 +1079,12 @@ Usual default path for locale definition files.
 POSIX.2, ISO/IEC TR 14652.
 .SH NOTES
 The collective GNU C library community wisdom regarding
+.IR abday ,
 .IR day ,
 .IR week ,
+.IR first_weekday ,
 and
-.I first_weekday
+.I first_workday
 states at
 https://sourceware.org/glibc/wiki/Locales
 the following:

@@ -1090,13 +1092,17 @@ the following:
 The value of the second
 .I week
 list item specifies the base of the
+.I abday
+and
 .I day
-list.
+lists.
 .IP *
 .I first_weekday
 specifies the offset of the first day-of-week in the
+.I abday
+and
 .I day
-list.
+lists.
 .IP *
 For compatibility reasons, all glibc locales should set the value of the
 second

@@ -1104,8 +1110,10 @@ second
 list item to
 .B 19971130
 (Sunday) and base the
+.I abday
+and
 .I day
-list appropriately, and set
+lists appropriately, and set
 .I first_weekday
 to
 .B 1