Patchwork Document strftime %Ob and %OB as C2X features

login
register
mail settings
Submitter Joseph Myers
Date Aug. 21, 2019, 7:39 p.m.
Message ID <alpine.DEB.2.21.1908211938300.25161@digraph.polyomino.org.uk>
Download mbox | patch
Permalink /patch/34234/
State New
Headers show

Comments

Joseph Myers - Aug. 21, 2019, 7:39 p.m.
On Thu, 15 Aug 2019, Florian Weimer wrote:

> C2X (in the form of N2385) is ambiguous on the relative meaning of %B
> and %OB, so the precise meaning defined in the manual is still a GNU
> extension.  Not sure if that matters.  I do not have objection to this
> patch.

Here is a version of the patch that tries to clarify that issue.


Document strftime %Ob and %OB as C2X features.

C2X standardizes strftime %Ob and %OB support.  This patch updates the
glibc manual to say these are C2X features, while noting that the
details of what is the alternative form of a month name are not
specified in C2X.

Note: C2X seems unclear to me about whether %h being equivalent to %b
means %Oh is thereby allowed and equivalent to %Ob; I've asked WG14.

Tested with "make info" and "make pdf".

2019-08-21  Joseph Myers  <joseph@codesourcery.com>

	* manual/time.texi (strftime): Document %Ob and %OB as C2X
	features.
Rafal Luzynski - Aug. 22, 2019, 9:55 a.m.
21.08.2019 21:39 Joseph Myers <joseph@codesourcery.com> wrote:
> 
> On Thu, 15 Aug 2019, Florian Weimer wrote:
> 
> > C2X (in the form of N2385) is ambiguous on the relative meaning of %B
> > and %OB, so the precise meaning defined in the manual is still a GNU
> > extension.  Not sure if that matters.  I do not have objection to this
> > patch.
> 
> Here is a version of the patch that tries to clarify that issue.
> [...]

Thank you, Joseph.  This looks good.  While talking about this, I received
few complains that this piece of documentation which I wrote 1.5 years
ago is sometimes ambiguous.  It is clear that "%B" is for a full date
and "%OB" is for a standalone name of a month.  People had questions:

* what if there is only a day and a month name (not a complete date so
  people thought it should be "%OB" but the answer is "%B" because there is
  a day and a month);
* what if there is only a month name and a year (it's not just a month
  standalone so people thought it should be "%B" but the answer is "%OB"
  because there is no day);
* what if some languages (which I'm not aware of) have different rules?

Is this the right moment to improve the documentation about this?

Regards,

Rafal
Joseph Myers - Aug. 22, 2019, 3:11 p.m.
On Thu, 22 Aug 2019, Rafal Luzynski wrote:

> Thank you, Joseph.  This looks good.  While talking about this, I received
> few complains that this piece of documentation which I wrote 1.5 years
> ago is sometimes ambiguous.  It is clear that "%B" is for a full date
> and "%OB" is for a standalone name of a month.  People had questions:
> 
> * what if there is only a day and a month name (not a complete date so
>   people thought it should be "%OB" but the answer is "%B" because there is
>   a day and a month);
> * what if there is only a month name and a year (it's not just a month
>   standalone so people thought it should be "%B" but the answer is "%OB"
>   because there is no day);
> * what if some languages (which I'm not aware of) have different rules?
> 
> Is this the right moment to improve the documentation about this?

I think improvements to this documentation are welcome at any time.

Patch

diff --git a/manual/time.texi b/manual/time.texi
index bfa46dd45b..c5f5b94b67 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -1352,7 +1352,11 @@  alternative numeric symbols.
 With @code{%B}, @code{%b}, and @code{%h}: 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.
+part of a complete date.  The @code{%OB} and @code{%Ob} formats are a
+C2X feature, specified in C2X to use the locale's `alternative' month
+name; @theglibc{} extends this specification to say that the form used
+in a complete date is the default and the form naming the month by
+itself is the alternative.
 @end table
 
 If the format supports the modifier but no alternative representation
@@ -1372,14 +1376,16 @@  The full weekday name according to the current locale.
 @item %b
 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.
+As a C2X feature (with a more detailed specification in @theglibc{}),
+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, 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.
+As a C2X feature (with a more detailed specification in @theglibc{}),
+the @code{O} modifier can be used (@code{%OB}) to get the grammatical
+form used when the month is named by itself.
 
 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