From patchwork Thu Nov 9 11:32:27 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rafal Luzynski X-Patchwork-Id: 24181 Received: (qmail 7635 invoked by alias); 9 Nov 2017 11:32:36 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 7623 invoked by uid 89); 9 Nov 2017 11:32:35 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-23.9 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KAM_LAZY_DOMAIN_SECURITY autolearn=ham version=3.3.2 spammy=dash, that!, H*c:PHrt, occurrence X-HELO: aev204.rev.netart.pl X-Spam-Score: 3.8 Date: Thu, 9 Nov 2017 12:32:27 +0100 (CET) From: Rafal Luzynski Reply-To: Rafal Luzynski To: Zack Weinberg Cc: GNU C Library Message-ID: <1758455610.176980.1510227147755@poczta.nazwa.pl> In-Reply-To: References: <1489658352.1095088.1505817931266@poczta.nazwa.pl> Subject: Re: [RFC][PATCH v9 6/6] Documentation to the above changes (bug 10871). MIME-Version: 1.0 X-Originating-Client: com.openexchange.ox.gui.dhtml Hi Zack, Thank you for your review. Actually it seems to me that you have replaced almost whole my documentation. I am really OK with that! Wouldn't you like to give a tag for example "Signed-off-by" eventually? I have applied all your fixes locally with some minor updates even if I have some doubts which I express here. At the end of this message please find an attachment which shows not whole documentation but just your changes. I thought it would be easier for you to review only your changes rather than whole documentation. 27.10.2017 19:47 Zack Weinberg wrote: > [...] > However, you are using "precise" as a verb here, which doesn't make > sense; "precise" is not used as a verb in any variety of English that > I know. I only understood what you meant after reading the entire > patch. What you want to say is > > [BZ#10871] > * 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.. That's one of the reasons why I need a review or even another person writing the documentation. :-( I have checked the dictionaries and the correct verb (or a term) which I meant was "clarify", "qualify", "pinpoint", "specify", "state precisely". Please suggest which term to use or please tell that your version does not need any further changes. > [...] > I need to revise this entire paragraph, because, again, "precise" > doesn't make sense as a verb. It would also make more sense to > explain things in a different order. New suggested text: > > + * 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. You have removed "Greek". Are you sure you want to remove this? Of course it does not make sense to mention all languages here but on the other hand I'd like to avoid the suggestion that this is only for Slavic (or Balto-Slavic) languages. In fact, these are the original (ancient) features of whole Indo-European family. > + 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 A triple dash, is this what you want? > [...] > > @itemx ABMON_12 > > -The return value is abbreviated name of the month. @code{ABMON_1} > > +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} > > corresponds to January. > > There is an error in the part of this sentence you didn't change. > Please correct it while we're in here anyway: > > + The return value is the abbreviated name of the month, ... > ^^^^ Thank you, fixed locally. > > +Similar to @code{MON_1} etc., but here the month names are in the > > grammatical > > Texinfo quirk: write "etc.,@:" instead of "etc.," to make sure the > space after the comma is not too wide in the PDF version of the > manual. I've found one more occurrence of "etc." in the same document and corrected it as well. Please see the attachment. > > +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}. > > Change "this information" to "these month names". > > Change "the modifier @code{O} is used in a format specifier @code{B}" to > "for the format specifier @code{%OB}." > > > + Here the first value @code{ALTMON_1} also corresponds to January. > > I don't think this sentence is necessary. (I see that it appears > under the specification of MON_* but it's clunky there too. Possibly > I will revise this entire section myself later.) > [...] OK, applied locally, too. > [...] > > diff --git a/manual/time.texi b/manual/time.texi > > index 33aa221..396934e 100644 > > --- a/manual/time.texi > > +++ b/manual/time.texi > > [...] > > @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 O modifier is unambiguously a GNU extension, but the grammatical > form is just what the locale does. I would say instead > > @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. > > > @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. > > Similarly; also, you have a copy-and-paste error, it says "abbreviated > month name" here too. Good point, thank you. Fixed locally. > @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}) This should be %OB. :-) ---------------------------------------^^^ I have fixed locally. I don't quote your complete review because I have no other questions. Again, please see the attachment where I apply your fixes to my local repository. Regards, Rafal Reviewed-by: Zack Weinberg From dd6227e98b0bebb263b69783ac4c2738fa383ea1 Mon Sep 17 00:00:00 2001 From: Rafal Luzynski 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 [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 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