Patchwork [v11,5/5] Documentation to the above changes (bug 10871).

login
register
mail settings
Submitter Rafal Luzynski
Date Jan. 9, 2018, 12:03 a.m.
Message ID <1840843125.675193.1515456193380@poczta.nazwa.pl>
Download mbox | patch
Permalink /patch/25278/
State New
Headers show

Comments

Rafal Luzynski - Jan. 9, 2018, 12:03 a.m.
[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(-)

 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 anyway.
 
 @item %c
 The date and time representation for the current locale.
Carlos O'Donell - Jan. 11, 2018, 4:46 a.m.
On 01/08/2018 04:03 PM, 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.

OK, with the one suggestion below.

Reviewed-by: Carlos O'Donell <carlos@redhat.com>

> ---
>  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.
> +  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.

OK.

> +
> +  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.

OK.

> +
> +  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".

OK.

> +
> +  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.

OK.

> +
>  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

OK.

>  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}

OK.

>  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}.

OK.

> +
> +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.

OK.

>  @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..81c7674 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.

OK.

>  @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.

OK.

>  
>  @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.

OK.

>  
> -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.

OK.

>  
>  @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 anyway.

s/anyway//g.

>  
>  @item %c
>  The date and time representation for the current locale.
>
Rafal Luzynski - Jan. 12, 2018, 4:21 a.m.
11.01.2018 05:46 Carlos O'Donell <carlos@redhat.com> wrote:
>
>
> On 01/08/2018 04:03 PM, Rafal Luzynski wrote:
> > [...]
> > +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 anyway.
>
> s/anyway//g.

OK, I trust you as an English native speaker.  Done locally.

Regards,

Rafal

Patch

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..81c7674 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