[v12,5/6] Documentation to the above changes (bug 10871).

  On 01/15/2018 03:46 AM, Rafal Luzynski wrote:
> Can I suggest that if there are no issues beyond the documentation
> (yes, I know that whether we add _NL_ABALTMON_* or __ABALTMON_* and
> ABALTMON_* is a serious API issue) then please let's commit this ASAP
> to make sure we have those remaining 2 weeks to announce the change
> to the outer world and let's polish the documentation within this
> period?

Here's a patch with my suggestions for the documentation; it should
apply on top of yours if you'd like to merge it in (or I can push it
later; I don't have a strong opinion).

I mention that an ABALTMON equivalent for %Ob isn't provided, but is
expected, and that _NL_ABALTMON may be used in the meantime.  I'm not
sure if we want to say it quite that way, but it's a start.

That was my mistake about "@:" being a colon.  That's what I get for
reviewing with the Texinfo manual out of hand.  :)  I think Texinfo
handles the comma after the period properly, as I couldn't tell a
difference in the rendered output either way, but it doesn't hurt to
give it hints, so I left it in.  I did add commas before "etc." though.

I agree that if it's documentation minutiae holding this up, the patches
should go in.

Rical
  

On 01/20/2018 12:36 AM, Rical Jasan wrote:
> On 01/15/2018 03:46 AM, Rafal Luzynski wrote:
>> Can I suggest that if there are no issues beyond the documentation
>> (yes, I know that whether we add _NL_ABALTMON_* or __ABALTMON_* and
>> ABALTMON_* is a serious API issue) then please let's commit this ASAP
>> to make sure we have those remaining 2 weeks to announce the change
>> to the outer world and let's polish the documentation within this
>> period?
> Here's a patch with my suggestions for the documentation; it should
> apply on top of yours if you'd like to merge it in (or I can push it
> later; I don't have a strong opinion).
> 
> I mention that an ABALTMON equivalent for %Ob isn't provided, but is
> expected, and that _NL_ABALTMON may be used in the meantime.  I'm not
> sure if we want to say it quite that way, but it's a start.
> 
> That was my mistake about "@:" being a colon.  That's what I get for
> reviewing with the Texinfo manual out of hand.  :)  I think Texinfo
> handles the comma after the period properly, as I couldn't tell a
> difference in the rendered output either way, but it doesn't hurt to
> give it hints, so I left it in.  I did add commas before "etc." though.
> 
> I agree that if it's documentation minutiae holding this up, the patches
> should go in.

This looks good to me.

Reviewed-by: Carlos O'Donell <carlos@redhat.com>

> diff --git a/manual/locale.texi b/manual/locale.texi
> index 059db75c1c..19b1cfc421 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
> @@ -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,13 +966,19 @@ 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 these month names for the format specifier @code{OB}.
> +use these month names for the conversion specifier @code{%OB}
> +(@pxref{Formatting Calendar Time}).
>  
>  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.
> +
> +@strong{NB:} @code{ABALTMON_@dots{}} constants corresponding to the @code{%Ob}
> +conversion specifier are not currently provided, but are expected to be in a
> +future release.  In the meantime, it is possible to use
> +@code{_NL_ABALTMON_@dots{}}.
>  @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 2a5afd9e56..6c3d5e9ab2 100644
> --- a/manual/time.texi
> +++ b/manual/time.texi
> @@ -1349,7 +1349,7 @@ Emperors' reigns.
>  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
> +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.
  

20.01.2018 09:36 Rical Jasan <ricaljasan@pacific.net> wrote:
> [...]
> Here's a patch with my suggestions for the documentation; it should
> apply on top of yours if you'd like to merge it in (or I can push it
> later; I don't have a strong opinion).

Thank you, Rical.  I will apply your patch locally on top of my
patches and then push everything together to ensure that you get
the full credit for your work.

Regards,

Rafal
  

20.01.2018 11:50 Rafal Luzynski <digitalfreak@lingonborough.com> wrote:
>
> 20.01.2018 09:36 Rical Jasan <ricaljasan@pacific.net> wrote:
> > [...]
> > Here's a patch with my suggestions for the documentation; it should
> > apply on top of yours if you'd like to merge it in (or I can push it
> > later; I don't have a strong opinion).
>
> Thank you, Rical. I will apply your patch locally on top of my
> patches and then push everything together to ensure that you get
> the full credit for your work.

Rical, I'm sorry, I have to change my mind. Your patch is of course
correct but lacks the changelog entry, the commit title and comment.
Please, let's go to the second option: please push it later on your
own, after I push my changes which I'm going to do now.

Regards,

Rafal
  

On 01/22/2018 12:43 AM, Rafal Luzynski wrote:
> 20.01.2018 11:50 Rafal Luzynski <digitalfreak@lingonborough.com> wrote:
>>
>> 20.01.2018 09:36 Rical Jasan <ricaljasan@pacific.net> wrote:
>>> [...]
>>> Here's a patch with my suggestions for the documentation; it should
>>> apply on top of yours if you'd like to merge it in (or I can push it
>>> later; I don't have a strong opinion).
>>
>> Thank you, Rical. I will apply your patch locally on top of my
>> patches and then push everything together to ensure that you get
>> the full credit for your work.
> 
> Rical, I'm sorry, I have to change my mind. Your patch is of course
> correct but lacks the changelog entry, the commit title and comment.
> Please, let's go to the second option: please push it later on your
> own, after I push my changes which I'm going to do now.

No worries; pushed as 0f5e2da1608f.  (I did some rewrapping on the long
lines, so the diff looks different, but I didn't change any of the
content of the edits.)

Rical
  

23.01.2018 04:41 Rical Jasan <ricaljasan@pacific.net> wrote:
> [...]
> No worries; pushed as 0f5e2da1608f. (I did some rewrapping on the long
> lines, so the diff looks different, but I didn't change any of the
> content of the edits.)

Thank you for your fixes, Rical.

Regards,

Rafal
  

I have received a comment from Gnulib maintainers that this
documentation is too ambiguous because does not define which
date format should be considered "full" and which should be
considered "month standalone".  I have explained that the date
is "full" if there is a day number and a month name (the week
day and the year number are optional) and the month name is
"standalone" when there is no day number (it may be just the
month name alone, or if a year number is added this still counts
as standalone).  It has been requested to add this definition
to the glibc documentation.

But, OTOH, I can't guarantee this works the same in all languages
which have this issue.  Maybe we should add a phrase "in many
languages" or "in most of the languages which need this feature"?

Any suggestions how to fix the documentation?  Does anybody want
to commit immediately?

Regards,

Rafal
  

On 01/24/2018 04:45 PM, Rafal Luzynski wrote:
> I have received a comment from Gnulib maintainers that this
> documentation is too ambiguous because does not define which
> date format should be considered "full" and which should be
> considered "month standalone".  I have explained that the date
> is "full" if there is a day number and a month name (the week
> day and the year number are optional) and the month name is
> "standalone" when there is no day number (it may be just the
> month name alone, or if a year number is added this still counts
> as standalone).  It has been requested to add this definition
> to the glibc documentation.
> 
> But, OTOH, I can't guarantee this works the same in all languages
> which have this issue.  Maybe we should add a phrase "in many
> languages" or "in most of the languages which need this feature"?
> 
> Any suggestions how to fix the documentation?  Does anybody want
> to commit immediately?

I see no immediate need to rush into documenting this any more than
is currently documented. Please reflect on the comments provided
by the gnulib maintainers and see if any ideas come to mind.

In my experience it is sometimes best to use examples here to define
what you mean. So instead of writing completely generic text, we
use Polish as an example and describe which is full and standalone
using the example.
  

25.01.2018 02:47 Carlos O'Donell <carlos@redhat.com> wrote:
>
>
> On 01/24/2018 04:45 PM, Rafal Luzynski wrote:
> > I have received a comment from Gnulib maintainers that this
> > documentation is too ambiguous because does not define which
> > date format should be considered "full" and which should be
> > considered "month standalone". I have explained that the date
> > is "full" if there is a day number and a month name (the week
> > day and the year number are optional) and the month name is
> > "standalone" when there is no day number (it may be just the
> > month name alone, or if a year number is added this still counts
> > as standalone). It has been requested to add this definition
> > to the glibc documentation.
> >
> > But, OTOH, I can't guarantee this works the same in all languages
> > which have this issue. Maybe we should add a phrase "in many
> > languages" or "in most of the languages which need this feature"?
> >
> > Any suggestions how to fix the documentation? Does anybody want
> > to commit immediately?
>
> I see no immediate need to rush into documenting this any more than
> is currently documented. Please reflect on the comments provided
> by the gnulib maintainers and see if any ideas come to mind.

I still remember it needs to be fixed.  While the manual and even
the comments may be updated later NEWS file probably will not.

I had an opportunity to discuss this with Dmitry and we have agreed
that we should reword "when the month is used as part of a complete date"
into "when the month appears together with a day of the month" and
"when the month is named by itself" with "when the month appears without
a day of the month" in order to make sure the readers understand the
rules correctly.  But I'm still thinking whether this is really the
good direction.  The old statements were ambiguous but easy to understand.
The new ones may be not so easy.  What about using both of them, like
"when the month appears together with a day of the month (e.g., when
it is used as part of a complete date)" and "when the month appears
without a day of the month (e.g., when it is named by itself)" or
even "(e.g., when it appears standalone)"?  Also I think we need
to mention at least once in the manual that some languages may have
different rules.  For example, Dmitry's comment [1] is a valid use
of the nominative case despite appearing together with a day number
(this corner case should be handled by translators and they should
use the format "%OB, %-d-е").

> In my experience it is sometimes best to use examples here to define
> what you mean. So instead of writing completely generic text, we
> use Polish as an example and describe which is full and standalone
> using the example.

I think we can use more languages to emphasize that the feature
is not Polish-specific and to increase a chance that an example
will be more familiar to the readers.  What about Catalan, Upper
Sorbian, Latin?  (Note: Latin is not supported in glibc).

Regards,

Rafal


[1] https://sourceware.org/bugzilla/show_bug.cgi?id=10871#c5