Re: [RFC][PATCH v9 6/6] Documentation to the above changes (bug 10871).

[Zack Weinberg <zackw at panix dot com>]

On Tue, Sep 19, 2017 at 6:45 AM, Rafal Luzynski
<digitalfreak@lingonborough.com> wrote:
> [documentation]

Thank you for writing documentation.

In another message, you asked where it was appropriate to document
changes to the format of the locale data file.  I also checked and I
could not find any existing documentation of the locale data file
format or semantics.  Therefore, you do not have to update it. :-)
(Of course, if you want to write a whole new chapter for the manual,
documenting the locale data file, we would be grateful -- but please
send that as a separate patch.)

In that message you were also worried about making non-native speaker
errors, so let me tell you that your English is very good in general;
I only found a few places where you said something in a way that a
native speaker wouldn't.  I do have a lot of corrections below, but
mostly they are about clarity, not grammar.

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

Because these are changes to the manual, rather than the code, it is
not important to give the complete list of symbols in this changelog
entry.

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

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

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

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

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

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

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

> diff --git a/manual/time.texi b/manual/time.texi
> index 33aa221..396934e 100644
> --- a/manual/time.texi
> +++ b/manual/time.texi
> @@ -1347,7 +1347,10 @@ Emperors' reigns.
>
>  @item O
>  Use the locale's alternate numeric symbols for numbers.  This modifier
> -applies only to numeric format specifiers.
> +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.
>  @end table

We need to change the older text to make this clearer:

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

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

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

> -Using @code{%B} together with @code{%d} produces grammatically
> -incorrect results for some locales.
> +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.

Paralleling what we said earlier about MON_... and ALTMON_..., make this

   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.

>  @itemx %B
>  @itemx %h
>  The month name according to the current locale, in abbreviated form or
> -the full name.
> +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.

Here again it would be better to change the older text a bit as well:

   @itemx %h
   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.

zw