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

[Rafal Luzynski]

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 <zackw@panix.com> 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-Corrections-for-the-documentation-from-Zack.patch
Type: text/x-patch
Size: 9871 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/libc-alpha/attachments/20171109/82f189ee/attachment.bin>