From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 66500 invoked by alias); 15 Jan 2018 03:42:57 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Received: (qmail 66426 invoked by uid 89); 15 Jan 2018 03:42:56 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-25.2 required=5.0 tests=AWL,BAYES_00,GIT_PATCH_0,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,SPF_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=cents, Calendar, gained, congratulations X-HELO: smtp.pacific.net Subject: Re: [PATCH v12 5/6] Documentation to the above changes (bug 10871). To: Rafal Luzynski , libc-alpha@sourceware.org References: <1802414843.37687.1515744747279@poczta.nazwa.pl> <1927758682.38060.1515745107778@poczta.nazwa.pl> From: Rical Jasan Message-ID: <49ea50a9-3cca-bbfe-8c75-41ea603d1a58@pacific.net> Date: Mon, 15 Jan 2018 03:42:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.2.1 MIME-Version: 1.0 In-Reply-To: <1927758682.38060.1515745107778@poczta.nazwa.pl> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-SW-Source: 2018-01/txt/msg00497.txt.bz2 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