Re: [PATCH v6 1/2] strftime: Set the default width of "%Ey" to 2 [BZ #23758]

[Zack Weinberg <zackw at panix dot com>]

This review covers only the documentation and commit message.

> The Japanese era name is scheduled to be changed on May 1, 2019.
> Prior to this, change the alternative representation for year in
> strftime to pad the number with zero to keep it constant width, so
> that prevent the trouble we saw in the past from becoming obvious
> again from the year after the era name changes onward.
>
> Since only one Japanese era name is used by each emperor's reign as
> lately, it is rare that the year ends in one digit or lasts more than
> three digits.  In addition, the default width of month, day, hour,
> minute, and second is 2, so adjust the default width of year the same
> as them, and then the whole display balance is improved.  Therefore,
> it would be reasonable to set the default width padding with zero of
> "%Ey" to 2.

This commit message will not be clear to readers who are not familiar
with Japanese era dating.  I had to look it up myself.  It also needs
to make clear that %Ey is changed for all locales, not just Japanese
locales, and this is expected to be harmless for locales that use %Ey
for something else.  (I see you mentioned this in the commit message
for the %EY change, but it belongs here.)

Based on what I learned, I suggest this instead:

| In Japanese locales, strftime's alternative year format (%Ey)
| produces the year of the current era (nengō).  A new era typically
| begins when a new emperor is enthroned.  The year of the current
| era is therefore usually a one- or two-digit number.
|
| Many programs that display Japanese era dates assume that the era
| year is two digits wide.  To improve how these programs display
| dates during the first nine years of a new era, change %Ey to pad
| one-digit numbers on the left with a zero.  This change applies to
| all locales.  It is expected to be harmless for other locales that
| use the alternative year format (e.g. lo_LA and th_TH, in which %Ey
| produces the year of the Buddhist calendar) as those calendars'
| year numbers are already more than two digits wide, and this is
| not expected to change.
|
| This change needs to be in place before 2019-05-01 CE, as a new
| era is scheduled to begin on that date.

>       [BZ #23758]
>       * NEWS: Mention the change.

Changes to NEWS are not mentioned in the ChangeLog.

>       * manual/time.texi (strftime): Document the desctiption for "%Ey".
>       Also, fix the wording to "alternative" rather than "alternate".
>       * time/strftime_l.c (__strftime_internal): Set the default width
>       padding with zero of "%Ey" to 2.

The rest of the ChangeLog entry is fine.  However ...

>       Also, fix the wording to "alternative" rather than "alternate".

... this wording change is *correct*, because "alternative" is the
term used by the POSIX specification for strftime, but it should be
committed as a separate patch.

Please remove all of the alternate -> alternative changes in this
patch series.  Please then prepare a separate patch that changes all
uses of "alternate" to "alternative" in the manual's description of
time formatting and makes no other changes.  That patch is
pre-approved: you may post it to the mailing list and immediately push
it to git, without waiting for someone to look at it.  It should be
applied before this patch series.

However, take care not to change uses of "alternate" that refer to
things other than alternative time formats.  For instance, "alternate"
is the correct word to use in the discussion of signal stacks.

(When used as modifiers, "alternate" and "alternative" mean almost
exactly the same thing.  Which one is used in any given context is a
matter of convention.  The manual tries to be consistent with the
POSIX specification, which uses one word for some things and the other
for others.  I regret the confusion this must cause.)

> +* Improve the width of alternative representation for year in
> +  strftime.  For %Ey conversion specifier, the default action is now
> +  to pad the number with zero to keep minimum 2 digits, similar to %y.

It is appropriate to repeat here that this change applies to all
locales, but is for the sake of Japanese era years, and is expected to
be harmless for all other locales.  Taking Paul's comments into
account as well, here is a suggested revision:

| * strftime's default formatting of a locale's alternative year (%Ey)
|   has been changed to zero-pad the year to a minimum of two digits,
|   like %y.  This improves the display of Japanese era years during
|   the first nine years of a new era, and is expected to be harmless
|   for all other locales (only Japanese locales regularly have
|   alternative year numbers less than 10).  Zero-padding can be
|   overridden with the '-' or '_' flags (which are GNU extensions).

> +If the @code{E} modifier is specified (@code{%Ey}), the locale's
> +alternative representation for year (the era year) is used instead.
> +The default action is to pad the number with zero to keep minimum 2
> +digits, similar to @code{%y}.

In addition to Paul's suggestion, this needs to be reworded for
clarity and to avoid using the term "the era year", which is not an
appropriate description of the alternative calendar for all locales.
Also, it should be clarified that %Ey does *not* reduce the result
modulo 100 as %y does.  I suggest

| If the @code{E} modifier is specified (@code{%Ey}), instead produces
| the year number according to a locale-specific alternative calendar.
| Unlike @code{%y}, the number is @emph{not} reduced modulo 100.
| However, by default it is zero-padded to a minimum of two digits
| (this can be overridden by an explicit field width or by the @code{_}
| and @code{-} flags).

zw