[v10,5/5] Documentation to the above changes (bug 10871).
Commit Message
[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.
---
NEWS | 24 ++++++++++++++++++++++++
manual/locale.texi | 26 +++++++++++++++++++++++---
manual/time.texi | 35 +++++++++++++++++++++++++++--------
3 files changed, 74 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.
@@ -35,6 +35,30 @@ Major new features:
are the same interfaces added in version 2.26 for some platforms where
this format is supported but is not the format of long double.
+* 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:
* On GNU/Linux, the obsolete Linux constant PTRACE_SEIZE_DEVEL is no longer
@@ -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
@@ -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