From dd6227e98b0bebb263b69783ac4c2738fa383ea1 Mon Sep 17 00:00:00 2001
From: Rafal Luzynski <digitalfreak@lingonborough.com>
Date: Thu, 9 Nov 2017 12:05:33 +0100
Subject: [PATCH] Corrections for the documentation from Zack

This commit is not meant to be pushed to the repository.
It's to simplify the review only.
---
 ChangeLog          |  9 +++++----
 NEWS               | 35 +++++++++++++++++++++++------------
 manual/locale.texi | 19 +++++++++----------
 manual/time.texi   | 49 +++++++++++++++++++++++++++----------------------
 4 files changed, 64 insertions(+), 48 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8020990..5cc06fd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,10 +1,11 @@
 2017-11-06  Rafal Luzynski  <digitalfreak@lingonborough.com>
 
 	[BZ #10871]
-	* manual/locale.texi (nl_langinfo): Document ALTMON_1..12,
-	precise details about ABMON_1..12 and MON_1..12.
-	* manual/time.texi (strftime): Document "%OB" and "%Ob" format
-	specifiers, precise details about "%B" and "%b".
+	* manual/locale.texi: Document ALTMON_1..12 constants for
+	nl_langinfo.  Explain when to use ALTMON instead of MON.
+	* manual/time.texi (strftime, strptime): Document GNU extension
+	permitting O modifier with %B and %b.  Explain when to use
+	%OB instead of %B.
 
 2017-11-06  Rafal Luzynski  <digitalfreak@lingonborough.com>
 
diff --git a/NEWS b/NEWS
index 5daf650..9afe47b 100644
--- a/NEWS
+++ b/NEWS
@@ -35,18 +35,29 @@ 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 of two grammatical forms of month names has been added.
-  It has been precised that the month names returned by nl_langinfo with
-  MON_1..12 and ABMON_1..12, and formatted by strftime with "%B" and "%b"
-  format specifiers are in the grammatical form used when the month forms
-  part of a complete date.  New series of valid arguments have been added
-  to nl_langinfo: ALTMON_1..12 and _NL_ABALTMON_1..12 and the "O" modifier
-  is supported with "%B" and "%b" format specifiers by strftime, they
-  generate the month names in the grammatical form used when the month is
-  named by itself.  This feature is required by several languages, mostly
-  Slavic and Baltic but also Greek and probably more.  In other languages
-  which do not need this feature the output month names will be the same
-  for both old and new arguments of nl_langinfo and strftime.
+* 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 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:
 
diff --git a/manual/locale.texi b/manual/locale.texi
index b61c709..e5cd9d7 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,8 +937,8 @@ unabbreviated weekday name.
 @itemx ABMON_10
 @itemx ABMON_11
 @itemx ABMON_12
-The return value is abbreviated name of the month, in the grammatical form
-used when the month forms part of a complete date.  @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
@@ -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,14 +966,13 @@ 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 this information when the modifier @code{O} is used in a format specifier
-@code{B}.  Here the first value @code{ALTMON_1} also corresponds to January.
+use these month names for the format specifier @code{OB}.
 
-Note that in locales which do not need different grammatical forms of the
-month names (including English) the return values are identical to those
-returned by the corresponding @code{MON_@dots{}} values.
+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 396934e..81c7674 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -1346,11 +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.  Additionally, as a GNU extension,
-this modifier also applies to the @code{%b} and @code{%B} format specifiers
-and forces the use of month names in the grammatical form used when the month
-is named by itself.
+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
@@ -1368,22 +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.
-As a GNU extension, it is specified that the abbreviated month name is
-produced in the grammatical form used when the month forms part of a complete
-date; applying the @code{O} modifier produces the abbreviated month name in
-the grammatical form used when the month is named by itself.
+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.
-As a GNU extension, it is specified that the full month name is produced in
-the grammatical form used when the month forms part of a complete date;
-applying the @code{O} modifier produces the abbreviated month name in the
-grammatical form used when the month is named by itself.
+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.
 
-Note that most of the locales do not need different grammatical forms of the
-month names.  In these locales the @code{O} modifier does not change the
-results of the @code{%b} and @code{%B} specifiers.
+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.
@@ -1790,10 +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.  If the current locale requires different grammatical forms of
-the month names then both forms are accepted, does not matter if the @code{O}
-modifier is present or not.
+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.
-- 
2.7.5
