From: Rafal Luzynski Date: Mon, 18 Sep 2017 22:00:22 +0000 (+0200) Subject: Documentation to the above changes (bug 10871). X-Git-Tag: upstream/2.30~1795 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=22390764f9ef3b04ae71ad100af6282f677315c2;p=platform%2Fupstream%2Fglibc.git Documentation to the above changes (bug 10871). [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. Reviewed-by: Carlos O'Donell --- diff --git a/ChangeLog b/ChangeLog index ab15b59..7b518b2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,15 @@ 2018-01-22 Rafal Luzynski [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. + +2018-01-22 Rafal Luzynski + + [BZ #10871] * locale/C-time.c (_nl_C_LC_TIME): Add abbreviated alternative month names, define them as the same as abbreviated month names explicitly. * locale/categories.def (LC_TIME): Add ab_alt_mon and wide-ab_alt_mon. diff --git a/NEWS b/NEWS index 79736db..dd8b795 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 names 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 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.