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

[Rafal Luzynski <digitalfreak at lingonborough dot com>]

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