Message ID | 1927758682.38060.1515745107778@poczta.nazwa.pl |
---|---|
State | New |
Headers | show |
Series | Month names in alternative grammatical case | expand |
Sorry I haven't had time to review sooner, but I was able to make some time today. On 01/12/2018 12:18 AM, Rafal Luzynski wrote: > [BZ #10871] > * manual/locale.texi: Document ALTMON_1..12 constants for > nl_langinfo. Specify when to use ALTMON instead of MON. > * manual/time.texi (strftime, strptime): Document GNU extension > permitting O modifier with %B and %b. Specify when to use > %OB instead of %B. > --- > ChangeLog | 9 +++++++++ > NEWS | 24 ++++++++++++++++++++++++ > manual/locale.texi | 26 +++++++++++++++++++++++--- > manual/time.texi | 35 +++++++++++++++++++++++++++-------- > 4 files changed, 83 insertions(+), 11 deletions(-) > > diff --git a/NEWS b/NEWS > index 75bf467..c70d8a9 100644 > --- a/NEWS > +++ b/NEWS > @@ -69,6 +69,30 @@ Major new features: > collation ordering. Previous glibc versions used locale-specific > ordering, the change might break systems that relied on that. > > +* Support for two grammatical forms of month name has been added. "month names" > + In a call to strftime, the "%B" and "%b" format specifiers will now > + produce the grammatical form required when the month is used as part > + of a complete date. New "%OB" and "%Ob" specifiers produce the form > + required when the month is named by itself. For instance, in Greek > + and in many Slavic and Baltic languages, "%B" will produce the month > + in genitive case, and "%OB" will produce the month in nominative case. > + > + In a call to strptime, "%B", "%b", "%h", "%OB", "%Ob", and "%Oh" > + are all valid and will all accept any known form of month > + name---standalone or complete, abbreviated or full. In a call to > + nl_langinfo, the query constants MON_1..12 and ABMON_1..12 return > + the strings used by "%B" and "%b", respectively. New query > + constants ALTMON_1..12 and _NL_ABALTMON_1..12 return the strings It seems odd not to have ABALTMON_*. Unfortunately I didn't get to reviewing this sooner, and I don't want to block this, and another developer has OK'd it [1], but I wanted to throw in my 2 cents. ABALTMON_* is both intuitive and consistent, and I wonder how many people are going to try using it, only to have to go look up instructions on the _NL_* variant, which isn't documented at all... ...which brings up another question: why are we announcing a reserved name (i.e., "_*") as available for general use (and not documenting it)? > + used by "%OB" and "%Ob", respectively. > + > + In a locale definition file, use "alt_mon" and "ab_alt_mon" to > + define the strings for %OB and %Ob, respectively; these have the > + same syntax as "mon" and "ab_mon". > + > + This feature is currently a GNU extension, but it is expected to > + be added to the next revision of POSIX, and it is also already > + available on some BSD-derived operating systems. > + > Deprecated and removed features, and other changes affecting compatibility: > > * Support for statically linked applications which call dlopen is deprecated > diff --git a/manual/locale.texi b/manual/locale.texi > index 60ad2a1..059db75 100644 > --- a/manual/locale.texi > +++ b/manual/locale.texi > @@ -923,7 +923,7 @@ corresponds to Sunday. > @itemx DAY_5 > @itemx DAY_6 > @itemx DAY_7 > -Similar to @code{ABDAY_1} etc., but here the return value is the > +Similar to @code{ABDAY_1} etc.,@: but here the return value is the There shouldn't be a colon immediately following the comma, but there should be a comma between ABDAY_1 and etc.: "Similar to @code{ABDAY_1}, etc., but..." (Note the colon can follow the period because the period is a part of the abbreviation.) The comma and colon essentially serve the same purpose, so it's somewhat redundant to use the two punctuation marks together like that, and I don't think "but" will generally ever follow a colon, so the comma is probably more appropriate. I could see an em-dash being used, though. There are several occurrences of this. > unabbreviated weekday name. > @item ABMON_1 > @itemx ABMON_2 > @@ -937,7 +937,8 @@ unabbreviated weekday name. > @itemx ABMON_10 > @itemx ABMON_11 > @itemx ABMON_12 > -The return value is abbreviated name of the month. @code{ABMON_1} > +The return value is the abbreviated name of the month, in the grammatical Good catch. > +form used when the month forms part of a complete date. @code{ABMON_1} > corresponds to January. > @item MON_1 > @itemx MON_2 > @@ -951,8 +952,27 @@ corresponds to January. > @itemx MON_10 > @itemx MON_11 > @itemx MON_12 > -Similar to @code{ABMON_1} etc., but here the month names are not abbreviated. > +Similar to @code{ABMON_1} etc.,@: but here the month names are not abbreviated.> Here the first value @code{MON_1} also corresponds to January. > +@item ALTMON_1 > +@itemx ALTMON_2 > +@itemx ALTMON_3 > +@itemx ALTMON_4 > +@itemx ALTMON_5 > +@itemx ALTMON_6 > +@itemx ALTMON_7 > +@itemx ALTMON_8 > +@itemx ALTMON_9 > +@itemx ALTMON_10 > +@itemx ALTMON_11 > +@itemx ALTMON_12 > +Similar to @code{MON_1} etc.,@: but here the month names are in the grammatical > +form used when the month is named by itself. The @code{strftime} functions > +use these month names for the format specifier @code{OB}. An "(@pxref{Formatting Calendar Time})" would be good at the end there. Also, I think it should read "conversion specifier @code{%OB}." In the strftime description, "B" is called the "format specifier", "O" is an "optional modifier", and "%OB" would be an example of a conversion specifier. > + > +Note that not all languages need two different forms of the month names, > +so the strings returned for @code{MON_@dots{}} and @code{ALTMON_@dots{}} > +may or may not be the same, depending on the locale. > @item AM_STR > @itemx PM_STR > The return values are strings which can be used in the representation of time > diff --git a/manual/time.texi b/manual/time.texi > index 33aa221..2a5afd9 100644 > --- a/manual/time.texi > +++ b/manual/time.texi > @@ -1346,8 +1346,13 @@ example, @code{%Ex} might yield a date format based on > the Japanese > Emperors' reigns. > > @item O > -Use the locale's alternate numeric symbols for numbers. This modifier > -applies only to numeric format specifiers. > +With all format specifiers that produce numbers: use the locale's > +alternate numeric symbols. > + > +With @code{%B} and @code{%b}: use the grammatical form for month names And "h"? What about: "With the format specifiers that produce month names:"? > +that is appropriate when the month is named by itself, rather than > +the form that is appropriate when the month is used as part of a > +complete date. This is a GNU extension. > @end table > > If the format supports the modifier but no alternate representation > @@ -1365,13 +1370,21 @@ The abbreviated weekday name according to the current > locale. > The full weekday name according to the current locale. > > @item %b > -The abbreviated month name according to the current locale. > +The abbreviated month name according to the current locale, in the > +grammatical form used when the month is part of a complete date. > +As a GNU extension, the @code{O} modifier can be used (@code{%Ob}) > +to get the grammatical form used when the month is named by itself. > > @item %B > -The full month name according to the current locale. > +The full month name according to the current locale, in the > +grammatical form used when the month is part of a complete date. > +As a GNU extension, the @code{O} modifier can be used (@code{%OB}) > +to get the grammatical form used when the month is named by itself. > > -Using @code{%B} together with @code{%d} produces grammatically > -incorrect results for some locales. > +Note that not all languages need two different forms of the month > +names, so the text produced by @code{%B} and @code{%OB}, and by > +@code{%b} and @code{%Ob}, may or may not be the same, depending on > +the locale. > > @item %c > The preferred calendar time representation for the current locale. > @@ -1778,8 +1791,14 @@ the full name. > @item %b > @itemx %B > @itemx %h > -The month name according to the current locale, in abbreviated form or > -the full name. > +A month name according to the current locale. All three specifiers > +will recognize both abbreviated and full month names. If the > +locale provides two different grammatical forms of month names, > +all three specifiers will recognize both forms. > + > +As a GNU extension, the @code{O} modifier can be used with these > +specifiers; it has no effect, as both grammatical forms of month > +names are recognized. > > @item %c > The date and time representation for the current locale. The rest sounds good. The ABALTMON issue aside, I'm glad to see this patch/bugfix finally have gained enough consensus to be going in. Congratulations. :) Rical [1] https://sourceware.org/ml/libc-alpha/2018-01/msg00409.html
On 01/14/2018 07:42 PM, Rical Jasan wrote: > It seems odd not to have ABALTMON_*. Unfortunately I didn't get to > reviewing this sooner, and I don't want to block this, and another > developer has OK'd it [1], but I wanted to throw in my 2 cents. I asked the same thing during the review, see: https://www.sourceware.org/ml/libc-alpha/2018-01/msg00408.html There is no reason we can't add it in the future. Perhaps a note about this in the documentation might explain why the expected define is not present?
On 01/14/2018 10:28 PM, Carlos O'Donell wrote: > On 01/14/2018 07:42 PM, Rical Jasan wrote: >> It seems odd not to have ABALTMON_*. Unfortunately I didn't get to >> reviewing this sooner, and I don't want to block this, and another >> developer has OK'd it [1], but I wanted to throw in my 2 cents. > I asked the same thing during the review, see: > https://www.sourceware.org/ml/libc-alpha/2018-01/msg00408.html > > There is no reason we can't add it in the future. > > Perhaps a note about this in the documentation might explain > why the expected define is not present? That would be fine with me. I think it deserves a mention because the feature is implemented, and I imagine anybody taking advantage of the bugfix or using %OB, et al., will naturally be interested in, if not looking for, the abbreviated equivalent. Better to have complete documentation that gets updated later than no documentation at all. Should the full _NL_ABALTMON list be documented alongside ALTMON, or do you think another paragraph in the ALTMON description is a sufficient shim? If ABALTMON is expected to be added in 2.28 because of how close to the 2.27 release this went in, I'd prefer the latter, perhaps even with a note that ABALTMON is expected to supersede the currently-available _NL_ABALTMON, but if ABALTMON is intended to be deferred until standardization, I think the former is more appropriate, with no mention of ABALTMON. Rical
15.01.2018 04:42 Rical Jasan <ricaljasan@pacific.net> wrote: > > > Sorry I haven't had time to review sooner, but I was able to make some > time today. Thank you for your review. > On 01/12/2018 12:18 AM, Rafal Luzynski wrote: > > [BZ #10871] > > * manual/locale.texi: Document ALTMON_1..12 constants for > > nl_langinfo. Specify when to use ALTMON instead of MON. > > * manual/time.texi (strftime, strptime): Document GNU extension > > permitting O modifier with %B and %b. Specify when to use > > %OB instead of %B. > > --- > > ChangeLog | 9 +++++++++ > > NEWS | 24 ++++++++++++++++++++++++ > > manual/locale.texi | 26 +++++++++++++++++++++++--- > > manual/time.texi | 35 +++++++++++++++++++++++++++-------- > > 4 files changed, 83 insertions(+), 11 deletions(-) > > > > diff --git a/NEWS b/NEWS > > index 75bf467..c70d8a9 100644 > > --- a/NEWS > > +++ b/NEWS > > @@ -69,6 +69,30 @@ Major new features: > > collation ordering. Previous glibc versions used locale-specific > > ordering, the change might break systems that relied on that. > > > > +* Support for two grammatical forms of month name has been added. > > "month names" OK, I'm going to apply this locally. That's why I'm asking other people to review or even write the documentation from scratch because the details like "month(s) name(s)" are sometimes confusing for me as a foreigner. > > > + In a call to strftime, the "%B" and "%b" format specifiers will now > > + produce the grammatical form required when the month is used as part > > + of a complete date. New "%OB" and "%Ob" specifiers produce the form > > + required when the month is named by itself. For instance, in Greek > > + and in many Slavic and Baltic languages, "%B" will produce the month > > + in genitive case, and "%OB" will produce the month in nominative case. > > + > > + In a call to strptime, "%B", "%b", "%h", "%OB", "%Ob", and "%Oh" > > + are all valid and will all accept any known form of month > > + name---standalone or complete, abbreviated or full. In a call to > > + nl_langinfo, the query constants MON_1..12 and ABMON_1..12 return > > + the strings used by "%B" and "%b", respectively. New query > > + constants ALTMON_1..12 and _NL_ABALTMON_1..12 return the strings > > It seems odd not to have ABALTMON_*. Unfortunately I didn't get to > reviewing this sooner, and I don't want to block this, and another > developer has OK'd it [1], but I wanted to throw in my 2 cents. > > ABALTMON_* is both intuitive and consistent, and I wonder how many > people are going to try using it, only to have to go look up > instructions on the _NL_* variant, which isn't documented at all... It has been answered by Carlos already. Well, the same question could be asked about all other _NL_* constants. Especially since they cannot be changed in future due to ABI compatibility. They are not documented in the documentation but documented in the header file. As I wrote before, the idea to standardize ABALTMON_* is very new. Can we assume already that it will be eventually accepted even if it takes many years and define it as a public GNU extension already? I'm kinda tempted to say yes. With _NL_ABALTMON_* the situation is more complex because... here I need to put a longer story. First of all, we should discourage using nl_langinfo() to display month names. Programmers should use strftime("%OB") and strftime("%Ob") even if nl_langinfo() produces the same results more efficiently. nl_langinfo() should be considered a low-level API used to implement strftime(). I think I saw this recommendation somewhere so I think the idea is not new. But if they really want to use nl_langinfo() they should use ALTMON_* for full month names if it is available (MON_* if it is not) and _NL_ABALTMON_* for short month names (ABMON_* if it is not). Recommend to use an undocumented feature? But OTOH I was told not to declare even ALTMON_* series as public because it is not yet published by POSIX (even if it is accepted to be published in future). ABALTMON_* was not yet even filed to POSIX. Sorry, I'm short of time so I don't provide links here. > ...which brings up another question: why are we announcing a reserved > name (i.e., "_*") as available for general use (and not documenting it)? Actually they are public symbols even if unofficial and undocumented. Would it be better to remove them from ChangeLog? AFAIK the purpose is to help if someone investigates in future who and why introduced these symbols. > > [...] > > diff --git a/manual/locale.texi b/manual/locale.texi > > index 60ad2a1..059db75 100644 > > --- a/manual/locale.texi > > +++ b/manual/locale.texi > > @@ -923,7 +923,7 @@ corresponds to Sunday. > > @itemx DAY_5 > > @itemx DAY_6 > > @itemx DAY_7 > > -Similar to @code{ABDAY_1} etc., but here the return value is the > > +Similar to @code{ABDAY_1} etc.,@: but here the return value is the > > There shouldn't be a colon immediately following the comma, but there > should be a comma between ABDAY_1 and etc.: "Similar to @code{ABDAY_1}, > etc., but..." [...] AFAIK it's not a colon but "@:" is an operator to force a regular space. Otherwise there would be a full stop space automatically inserted due to the "dot-space" sequence. > > [...] > > +@item ALTMON_1 > > +@itemx ALTMON_2 > > +@itemx ALTMON_3 > > +@itemx ALTMON_4 > > +@itemx ALTMON_5 > > +@itemx ALTMON_6 > > +@itemx ALTMON_7 > > +@itemx ALTMON_8 > > +@itemx ALTMON_9 > > +@itemx ALTMON_10 > > +@itemx ALTMON_11 > > +@itemx ALTMON_12 > > +Similar to @code{MON_1} etc.,@: but here the month names are in the > > grammatical > > +form used when the month is named by itself. The @code{strftime} functions > > +use these month names for the format specifier @code{OB}. > > An "(@pxref{Formatting Calendar Time})" would be good at the end there. It is already in other places in this document. If you really need it here then I'll appreciate a full example which I can just copy & paste. > Also, I think it should read "conversion specifier @code{%OB}." In the > strftime description, "B" is called the "format specifier", "O" is an > "optional modifier", and "%OB" would be an example of a conversion > specifier. Again, I'm not a real expert to determine which term is correct here. I will appreciate the corrections from native English speakers but I'd like to get a consistent version. > > [...] > > diff --git a/manual/time.texi b/manual/time.texi > > index 33aa221..2a5afd9 100644 > > --- a/manual/time.texi > > +++ b/manual/time.texi > > @@ -1346,8 +1346,13 @@ example, @code{%Ex} might yield a date format based > > on > > the Japanese > > Emperors' reigns. > > > > @item O > > -Use the locale's alternate numeric symbols for numbers. This modifier > > -applies only to numeric format specifiers. > > +With all format specifiers that produce numbers: use the locale's > > +alternate numeric symbols. > > + > > +With @code{%B} and @code{%b}: use the grammatical form for month names > > And "h"? What about: "With the format specifiers that produce month > names:"? The documentation of "%h" says it works exactly the same as "%b" and I read this as a sufficient explanation. I can add "%h" here if you insist. As a reader I don't like the documents which refer to other documents (which may refer to yet other documents etc.) so I wouldn't like to see "With the format specifiers that produce month names" (and please, readers, read this document again if you have already forgotten which format specifiers produce month names) :-) So, again, at the moment I don't change anything and I'll add "%h" if you insist. > [...] > The ABALTMON issue aside, I'm glad to see this patch/bugfix finally have > gained enough consensus to be going in. Congratulations. :) > > Rical Thank you again for your review. I believe it helps me to finalize this task. Can I suggest that if there are no issues beyond the documentation (yes, I know that whether we add _NL_ABALTMON_* or __ABALTMON_* and ABALTMON_* is a serious API issue) then please let's commit this ASAP to make sure we have those remaining 2 weeks to announce the change to the outer world and let's polish the documentation within this period? Regards, Rafal
15.01.2018 09:30 Rical Jasan <ricaljasan@pacific.net> wrote: > > > On 01/14/2018 10:28 PM, Carlos O'Donell wrote: > > On 01/14/2018 07:42 PM, Rical Jasan wrote: > >> It seems odd not to have ABALTMON_*. Unfortunately I didn't get to > >> reviewing this sooner, and I don't want to block this, and another > >> developer has OK'd it [1], but I wanted to throw in my 2 cents. > > I asked the same thing during the review, see: > > https://www.sourceware.org/ml/libc-alpha/2018-01/msg00408.html > > > > There is no reason we can't add it in the future. > > > > Perhaps a note about this in the documentation might explain > > why the expected define is not present? > > That would be fine with me. I think it deserves a mention because the > feature is implemented, and I imagine anybody taking advantage of the > bugfix or using %OB, et al., will naturally be interested in, if not > looking for, the abbreviated equivalent. Better to have complete > documentation that gets updated later than no documentation at all. Again, as we are short of time I'll appreciate a complete excerpt of the documentation which I can just copy & paste. Or maybe better please polish the documentation later after I commit so you will get a full credit in the commit message and a changelog entry. :-) > Should the full _NL_ABALTMON list be documented alongside ALTMON, or do > you think another paragraph in the ALTMON description is a sufficient > shim? If ABALTMON is expected to be added in 2.28 because of how close > to the 2.27 release this went in, I'd prefer the latter, perhaps even > with a note that ABALTMON is expected to supersede the > currently-available _NL_ABALTMON, but if ABALTMON is intended to be > deferred until standardization, I think the former is more appropriate, > with no mention of ABALTMON. No, please don't defer this to 2.28. This set of patches has missed about 2 release deadlines already and I think it deserves to be included in some new releases of major Linux distros which I expect to be released this year. Regarding the POSIX standardization, since ALTMON_* has been accepted in ~2010 and is still not yet published I assume that ABALTMON_* will remain waiting another ~10 years (I'm trying not to be ironic, having worked on the issue for just glibc for about 2.5 years I really understand the hard work beyond standardization.) Regards, Rafal
15.01.2018 12:46 Rafal Luzynski <digitalfreak@lingonborough.com> wrote: > > 15.01.2018 04:42 Rical Jasan <ricaljasan@pacific.net> wrote: > > [...] > > On 01/12/2018 12:18 AM, Rafal Luzynski wrote: > > > [...] > > > diff --git a/NEWS b/NEWS > > > index 75bf467..c70d8a9 100644 > > > --- a/NEWS > > > +++ b/NEWS > > > @@ -69,6 +69,30 @@ Major new features: > > > collation ordering. Previous glibc versions used locale-specific > > > ordering, the change might break systems that relied on that. > > > > > > +* Support for two grammatical forms of month name has been added. > > > > "month names" > > OK, I'm going to apply this locally. That's why I'm asking other people > to review or even write the documentation from scratch because the details > like "month(s) name(s)" are sometimes confusing for me as a foreigner. I have applied this change locally but nothing else. Should I apply more changes? PING - I'm getting worried about my patches. Carlos, anybody? BTW, my github repo is up to date at the moment: https://github.com/rluzynski/glibc Regards, Rafal
On Thu, 18 Jan 2018, Rafal Luzynski wrote:
> PING - I'm getting worried about my patches. Carlos, anybody?
I'm concerned more generally that we still have multiple complicated
architecture-independent patches, especially this one and C11 threads,
pending review for 2.27, as the architecture validation for 2.27 can't
really start until those patches have either been accepted or postponed to
2.28. (Architecture maintainers of course can and should do preliminary
testing and fixing issues found, but we should resolve the major
architecture-independent patches before any near-final validation for the
release.)
On 01/15/2018 03:46 AM, Rafal Luzynski wrote: > Can I suggest that if there are no issues beyond the documentation > (yes, I know that whether we add _NL_ABALTMON_* or __ABALTMON_* and > ABALTMON_* is a serious API issue) then please let's commit this ASAP > to make sure we have those remaining 2 weeks to announce the change > to the outer world and let's polish the documentation within this > period? Here's a patch with my suggestions for the documentation; it should apply on top of yours if you'd like to merge it in (or I can push it later; I don't have a strong opinion). I mention that an ABALTMON equivalent for %Ob isn't provided, but is expected, and that _NL_ABALTMON may be used in the meantime. I'm not sure if we want to say it quite that way, but it's a start. That was my mistake about "@:" being a colon. That's what I get for reviewing with the Texinfo manual out of hand. :) I think Texinfo handles the comma after the period properly, as I couldn't tell a difference in the rendered output either way, but it doesn't hurt to give it hints, so I left it in. I did add commas before "etc." though. I agree that if it's documentation minutiae holding this up, the patches should go in. Rical diff --git a/manual/locale.texi b/manual/locale.texi index 059db75c1c..19b1cfc421 100644 --- a/manual/locale.texi +++ b/manual/locale.texi @@ -923,7 +923,7 @@ corresponds to Sunday. @itemx DAY_5 @itemx DAY_6 @itemx DAY_7 -Similar to @code{ABDAY_1} etc.,@: but here the return value is the +Similar to @code{ABDAY_1}, etc.,@: but here the return value is the unabbreviated weekday name. @item ABMON_1 @itemx ABMON_2 @@ -952,7 +952,7 @@ corresponds to January. @itemx MON_10 @itemx MON_11 @itemx MON_12 -Similar to @code{ABMON_1} etc.,@: but here the month names are not abbreviated. +Similar to @code{ABMON_1}, etc.,@: but here the month names are not abbreviated. Here the first value @code{MON_1} also corresponds to January. @item ALTMON_1 @itemx ALTMON_2 @@ -966,13 +966,19 @@ Here the first value @code{MON_1} also corresponds to January. @itemx ALTMON_10 @itemx ALTMON_11 @itemx ALTMON_12 -Similar to @code{MON_1} etc.,@: but here the month names are in the grammatical +Similar to @code{MON_1}, etc.,@: but here the month names are in the grammatical form used when the month is named by itself. The @code{strftime} functions -use these month names for the format specifier @code{OB}. +use these month names for the conversion specifier @code{%OB} +(@pxref{Formatting Calendar Time}). Note that not all languages need two different forms of the month names, so the strings returned for @code{MON_@dots{}} and @code{ALTMON_@dots{}} may or may not be the same, depending on the locale. + +@strong{NB:} @code{ABALTMON_@dots{}} constants corresponding to the @code{%Ob} +conversion specifier are not currently provided, but are expected to be in a +future release. In the meantime, it is possible to use +@code{_NL_ABALTMON_@dots{}}. @item AM_STR @itemx PM_STR The return values are strings which can be used in the representation of time diff --git a/manual/time.texi b/manual/time.texi index 2a5afd9e56..6c3d5e9ab2 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -1349,7 +1349,7 @@ Emperors' reigns. With all format specifiers that produce numbers: use the locale's alternate numeric symbols. -With @code{%B} and @code{%b}: use the grammatical form for month names +With @code{%B}, @code{%b}, and @code{%h}: use the grammatical form for month names that is appropriate when the month is named by itself, rather than the form that is appropriate when the month is used as part of a complete date. This is a GNU extension.
On 01/20/2018 12:36 AM, Rical Jasan wrote: > On 01/15/2018 03:46 AM, Rafal Luzynski wrote: >> Can I suggest that if there are no issues beyond the documentation >> (yes, I know that whether we add _NL_ABALTMON_* or __ABALTMON_* and >> ABALTMON_* is a serious API issue) then please let's commit this ASAP >> to make sure we have those remaining 2 weeks to announce the change >> to the outer world and let's polish the documentation within this >> period? > Here's a patch with my suggestions for the documentation; it should > apply on top of yours if you'd like to merge it in (or I can push it > later; I don't have a strong opinion). > > I mention that an ABALTMON equivalent for %Ob isn't provided, but is > expected, and that _NL_ABALTMON may be used in the meantime. I'm not > sure if we want to say it quite that way, but it's a start. > > That was my mistake about "@:" being a colon. That's what I get for > reviewing with the Texinfo manual out of hand. :) I think Texinfo > handles the comma after the period properly, as I couldn't tell a > difference in the rendered output either way, but it doesn't hurt to > give it hints, so I left it in. I did add commas before "etc." though. > > I agree that if it's documentation minutiae holding this up, the patches > should go in. This looks good to me. Reviewed-by: Carlos O'Donell <carlos@redhat.com> > diff --git a/manual/locale.texi b/manual/locale.texi > index 059db75c1c..19b1cfc421 100644 > --- a/manual/locale.texi > +++ b/manual/locale.texi > @@ -923,7 +923,7 @@ corresponds to Sunday. > @itemx DAY_5 > @itemx DAY_6 > @itemx DAY_7 > -Similar to @code{ABDAY_1} etc.,@: but here the return value is the > +Similar to @code{ABDAY_1}, etc.,@: but here the return value is the > unabbreviated weekday name. > @item ABMON_1 > @itemx ABMON_2 > @@ -952,7 +952,7 @@ corresponds to January. > @itemx MON_10 > @itemx MON_11 > @itemx MON_12 > -Similar to @code{ABMON_1} etc.,@: but here the month names are not abbreviated. > +Similar to @code{ABMON_1}, etc.,@: but here the month names are not abbreviated. > Here the first value @code{MON_1} also corresponds to January. > @item ALTMON_1 > @itemx ALTMON_2 > @@ -966,13 +966,19 @@ Here the first value @code{MON_1} also corresponds to January. > @itemx ALTMON_10 > @itemx ALTMON_11 > @itemx ALTMON_12 > -Similar to @code{MON_1} etc.,@: but here the month names are in the grammatical > +Similar to @code{MON_1}, etc.,@: but here the month names are in the grammatical > form used when the month is named by itself. The @code{strftime} functions > -use these month names for the format specifier @code{OB}. > +use these month names for the conversion specifier @code{%OB} > +(@pxref{Formatting Calendar Time}). > > Note that not all languages need two different forms of the month names, > so the strings returned for @code{MON_@dots{}} and @code{ALTMON_@dots{}} > may or may not be the same, depending on the locale. > + > +@strong{NB:} @code{ABALTMON_@dots{}} constants corresponding to the @code{%Ob} > +conversion specifier are not currently provided, but are expected to be in a > +future release. In the meantime, it is possible to use > +@code{_NL_ABALTMON_@dots{}}. > @item AM_STR > @itemx PM_STR > The return values are strings which can be used in the representation of time > diff --git a/manual/time.texi b/manual/time.texi > index 2a5afd9e56..6c3d5e9ab2 100644 > --- a/manual/time.texi > +++ b/manual/time.texi > @@ -1349,7 +1349,7 @@ Emperors' reigns. > With all format specifiers that produce numbers: use the locale's > alternate numeric symbols. > > -With @code{%B} and @code{%b}: use the grammatical form for month names > +With @code{%B}, @code{%b}, and @code{%h}: use the grammatical form for month names > that is appropriate when the month is named by itself, rather than > the form that is appropriate when the month is used as part of a > complete date. This is a GNU extension.
On 01/18/2018 05:35 AM, Joseph Myers wrote: > On Thu, 18 Jan 2018, Rafal Luzynski wrote: > >> PING - I'm getting worried about my patches. Carlos, anybody? > > I'm concerned more generally that we still have multiple complicated > architecture-independent patches, especially this one and C11 threads, > pending review for 2.27, as the architecture validation for 2.27 can't > really start until those patches have either been accepted or postponed to > 2.28. (Architecture maintainers of course can and should do preliminary > testing and fixing issues found, but we should resolve the major > architecture-independent patches before any near-final validation for the > release.) This work is now complete. Rafal should commit this ASAP. I think C11 threads should be deferred until 2.28 opens, and I will continue review. With those two out of the way all that remains is fixing the x86 bug. We should stick to discussing release blockers: https://sourceware.org/glibc/wiki/Release/2.27#Release_blockers.3F All "Desirable this release" should be deferred to 2.28.
20.01.2018 09:36 Rical Jasan <ricaljasan@pacific.net> wrote: > [...] > Here's a patch with my suggestions for the documentation; it should > apply on top of yours if you'd like to merge it in (or I can push it > later; I don't have a strong opinion). Thank you, Rical. I will apply your patch locally on top of my patches and then push everything together to ensure that you get the full credit for your work. Regards, Rafal
20.01.2018 11:50 Rafal Luzynski <digitalfreak@lingonborough.com> wrote: > > 20.01.2018 09:36 Rical Jasan <ricaljasan@pacific.net> wrote: > > [...] > > Here's a patch with my suggestions for the documentation; it should > > apply on top of yours if you'd like to merge it in (or I can push it > > later; I don't have a strong opinion). > > Thank you, Rical. I will apply your patch locally on top of my > patches and then push everything together to ensure that you get > the full credit for your work. Rical, I'm sorry, I have to change my mind. Your patch is of course correct but lacks the changelog entry, the commit title and comment. Please, let's go to the second option: please push it later on your own, after I push my changes which I'm going to do now. Regards, Rafal
12.01.2018 09:18 Rafal Luzynski <digitalfreak@lingonborough.com> wrote: > > [BZ #10871] > * manual/locale.texi: Document ALTMON_1..12 constants for > nl_langinfo. Specify when to use ALTMON instead of MON. > * manual/time.texi (strftime, strptime): Document GNU extension > permitting O modifier with %B and %b. Specify when to use > %OB instead of %B. > --- > ChangeLog | 9 +++++++++ > NEWS | 24 ++++++++++++++++++++++++ > manual/locale.texi | 26 +++++++++++++++++++++++--- > manual/time.texi | 35 +++++++++++++++++++++++++++-------- > 4 files changed, 83 insertions(+), 11 deletions(-) > [...] This patch has been pushed. Thank you Zack, Carlos, Dmitry, Rical, and everyone else for your reviews, documentation updates, assistance, etc. Rical, as I wrote before I have not merged your changes. Please add them now so you will get the full credit in the commit log. Regards, Rafal
On Sat, 20 Jan 2018, Carlos O'Donell wrote: > We should stick to discussing release blockers: > https://sourceware.org/glibc/wiki/Release/2.27#Release_blockers.3F > > All "Desirable this release" should be deferred to 2.28. Well - we may not need to decide on RISC-V yet, as it's low risk for other ports, but unless version 5 fully addresses all issues raised with version 4 without going back on fixes for issues with previous versions, it doesn't look like it would make it as version 6 wouldn't be ready until after 2.27 is out.
On 01/22/2018 12:43 AM, Rafal Luzynski wrote: > 20.01.2018 11:50 Rafal Luzynski <digitalfreak@lingonborough.com> wrote: >> >> 20.01.2018 09:36 Rical Jasan <ricaljasan@pacific.net> wrote: >>> [...] >>> Here's a patch with my suggestions for the documentation; it should >>> apply on top of yours if you'd like to merge it in (or I can push it >>> later; I don't have a strong opinion). >> >> Thank you, Rical. I will apply your patch locally on top of my >> patches and then push everything together to ensure that you get >> the full credit for your work. > > Rical, I'm sorry, I have to change my mind. Your patch is of course > correct but lacks the changelog entry, the commit title and comment. > Please, let's go to the second option: please push it later on your > own, after I push my changes which I'm going to do now. No worries; pushed as 0f5e2da1608f. (I did some rewrapping on the long lines, so the diff looks different, but I didn't change any of the content of the edits.) Rical
23.01.2018 04:41 Rical Jasan <ricaljasan@pacific.net> wrote: > [...] > No worries; pushed as 0f5e2da1608f. (I did some rewrapping on the long > lines, so the diff looks different, but I didn't change any of the > content of the edits.) Thank you for your fixes, Rical. Regards, Rafal
I have received a comment from Gnulib maintainers that this documentation is too ambiguous because does not define which date format should be considered "full" and which should be considered "month standalone". I have explained that the date is "full" if there is a day number and a month name (the week day and the year number are optional) and the month name is "standalone" when there is no day number (it may be just the month name alone, or if a year number is added this still counts as standalone). It has been requested to add this definition to the glibc documentation. But, OTOH, I can't guarantee this works the same in all languages which have this issue. Maybe we should add a phrase "in many languages" or "in most of the languages which need this feature"? Any suggestions how to fix the documentation? Does anybody want to commit immediately? Regards, Rafal
On 01/24/2018 04:45 PM, Rafal Luzynski wrote: > I have received a comment from Gnulib maintainers that this > documentation is too ambiguous because does not define which > date format should be considered "full" and which should be > considered "month standalone". I have explained that the date > is "full" if there is a day number and a month name (the week > day and the year number are optional) and the month name is > "standalone" when there is no day number (it may be just the > month name alone, or if a year number is added this still counts > as standalone). It has been requested to add this definition > to the glibc documentation. > > But, OTOH, I can't guarantee this works the same in all languages > which have this issue. Maybe we should add a phrase "in many > languages" or "in most of the languages which need this feature"? > > Any suggestions how to fix the documentation? Does anybody want > to commit immediately? I see no immediate need to rush into documenting this any more than is currently documented. Please reflect on the comments provided by the gnulib maintainers and see if any ideas come to mind. In my experience it is sometimes best to use examples here to define what you mean. So instead of writing completely generic text, we use Polish as an example and describe which is full and standalone using the example.
25.01.2018 02:47 Carlos O'Donell <carlos@redhat.com> wrote: > > > On 01/24/2018 04:45 PM, Rafal Luzynski wrote: > > I have received a comment from Gnulib maintainers that this > > documentation is too ambiguous because does not define which > > date format should be considered "full" and which should be > > considered "month standalone". I have explained that the date > > is "full" if there is a day number and a month name (the week > > day and the year number are optional) and the month name is > > "standalone" when there is no day number (it may be just the > > month name alone, or if a year number is added this still counts > > as standalone). It has been requested to add this definition > > to the glibc documentation. > > > > But, OTOH, I can't guarantee this works the same in all languages > > which have this issue. Maybe we should add a phrase "in many > > languages" or "in most of the languages which need this feature"? > > > > Any suggestions how to fix the documentation? Does anybody want > > to commit immediately? > > I see no immediate need to rush into documenting this any more than > is currently documented. Please reflect on the comments provided > by the gnulib maintainers and see if any ideas come to mind. I still remember it needs to be fixed. While the manual and even the comments may be updated later NEWS file probably will not. I had an opportunity to discuss this with Dmitry and we have agreed that we should reword "when the month is used as part of a complete date" into "when the month appears together with a day of the month" and "when the month is named by itself" with "when the month appears without a day of the month" in order to make sure the readers understand the rules correctly. But I'm still thinking whether this is really the good direction. The old statements were ambiguous but easy to understand. The new ones may be not so easy. What about using both of them, like "when the month appears together with a day of the month (e.g., when it is used as part of a complete date)" and "when the month appears without a day of the month (e.g., when it is named by itself)" or even "(e.g., when it appears standalone)"? Also I think we need to mention at least once in the manual that some languages may have different rules. For example, Dmitry's comment [1] is a valid use of the nominative case despite appearing together with a day number (this corner case should be handled by translators and they should use the format "%OB, %-d-ะต"). > In my experience it is sometimes best to use examples here to define > what you mean. So instead of writing completely generic text, we > use Polish as an example and describe which is full and standalone > using the example. I think we can use more languages to emphasize that the feature is not Polish-specific and to increase a chance that an example will be more familiar to the readers. What about Catalan, Upper Sorbian, Latin? (Note: Latin is not supported in glibc). Regards, Rafal [1] https://sourceware.org/bugzilla/show_bug.cgi?id=10871#c5
diff --git a/NEWS b/NEWS index 75bf467..c70d8a9 100644 --- a/NEWS +++ b/NEWS @@ -69,6 +69,30 @@ Major new features: collation ordering. Previous glibc versions used locale-specific ordering, the change might break systems that relied on that. +* Support for two grammatical forms of month name has been added. + In a call to strftime, the "%B" and "%b" format specifiers will now + produce the grammatical form required when the month is used as part + of a complete date. New "%OB" and "%Ob" specifiers produce the form + required when the month is named by itself. For instance, in Greek + and in many Slavic and Baltic languages, "%B" will produce the month + in genitive case, and "%OB" will produce the month in nominative case. + + In a call to strptime, "%B", "%b", "%h", "%OB", "%Ob", and "%Oh" + are all valid and will all accept any known form of month + name---standalone or complete, abbreviated or full. In a call to + nl_langinfo, the query constants MON_1..12 and ABMON_1..12 return + the strings used by "%B" and "%b", respectively. New query + constants ALTMON_1..12 and _NL_ABALTMON_1..12 return the strings + used by "%OB" and "%Ob", respectively. + + In a locale definition file, use "alt_mon" and "ab_alt_mon" to + define the strings for %OB and %Ob, respectively; these have the + same syntax as "mon" and "ab_mon". + + This feature is currently a GNU extension, but it is expected to + be added to the next revision of POSIX, and it is also already + available on some BSD-derived operating systems. + Deprecated and removed features, and other changes affecting compatibility: * Support for statically linked applications which call dlopen is deprecated diff --git a/manual/locale.texi b/manual/locale.texi index 60ad2a1..059db75 100644 --- a/manual/locale.texi +++ b/manual/locale.texi @@ -923,7 +923,7 @@ corresponds to Sunday. @itemx DAY_5 @itemx DAY_6 @itemx DAY_7 -Similar to @code{ABDAY_1} etc., but here the return value is the +Similar to @code{ABDAY_1} etc.,@: but here the return value is the unabbreviated weekday name. @item ABMON_1 @itemx ABMON_2 @@ -937,7 +937,8 @@ unabbreviated weekday name. @itemx ABMON_10 @itemx ABMON_11 @itemx ABMON_12 -The return value is abbreviated name of the month. @code{ABMON_1} +The return value is the abbreviated name of the month, in the grammatical +form used when the month forms part of a complete date. @code{ABMON_1} corresponds to January. @item MON_1 @itemx MON_2 @@ -951,8 +952,27 @@ corresponds to January. @itemx MON_10 @itemx MON_11 @itemx MON_12 -Similar to @code{ABMON_1} etc., but here the month names are not abbreviated. +Similar to @code{ABMON_1} etc.,@: but here the month names are not abbreviated. Here the first value @code{MON_1} also corresponds to January. +@item ALTMON_1 +@itemx ALTMON_2 +@itemx ALTMON_3 +@itemx ALTMON_4 +@itemx ALTMON_5 +@itemx ALTMON_6 +@itemx ALTMON_7 +@itemx ALTMON_8 +@itemx ALTMON_9 +@itemx ALTMON_10 +@itemx ALTMON_11 +@itemx ALTMON_12 +Similar to @code{MON_1} etc.,@: but here the month names are in the grammatical +form used when the month is named by itself. The @code{strftime} functions +use these month names for the format specifier @code{OB}. + +Note that not all languages need two different forms of the month names, +so the strings returned for @code{MON_@dots{}} and @code{ALTMON_@dots{}} +may or may not be the same, depending on the locale. @item AM_STR @itemx PM_STR The return values are strings which can be used in the representation of time diff --git a/manual/time.texi b/manual/time.texi index 33aa221..2a5afd9 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -1346,8 +1346,13 @@ example, @code{%Ex} might yield a date format based on the Japanese Emperors' reigns. @item O -Use the locale's alternate numeric symbols for numbers. This modifier -applies only to numeric format specifiers. +With all format specifiers that produce numbers: use the locale's +alternate numeric symbols. + +With @code{%B} and @code{%b}: use the grammatical form for month names +that is appropriate when the month is named by itself, rather than +the form that is appropriate when the month is used as part of a +complete date. This is a GNU extension. @end table