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

[Zack Weinberg <zackw at panix dot com>]

On Thu, Nov 9, 2017 at 6:32 AM, Rafal Luzynski
<digitalfreak@lingonborough.com> wrote:
>
> 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?

Are we officially doing that now?  I have to admit I don't really get
the point of it, but yes, you can go ahead and put

Reviewed-by: Zack Weinberg <zackw@panix.com>

on all of these patches if we are officially requiring it.

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

Yes, this makes sense in this case.

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

Thanks for explaining.  Because this is formal documentation of a new
feature, I think the best word to use would be "specify".

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

I removed "Greek" because I didn't know if it was correct to say that
%B will use genitive case and %OB will use nominative case _for Greek_.
If it is, we could say

+ For instance, in Greek and in many Slavic and Baltic languages, ...

(English prefers to order lists like this from most to least specific.)

On the other hand, if Greek wants some other case for %B (accusative,
perhaps, because it was dative in Ancient Greek?) then we could say
instead

+ For instance, in Greek and in many Baltic and Slavic languages, %B and
+ %OB produce the month in different noun cases

and avoid saying which cases they are.

I wish I knew a non-Indo-European example to throw in.

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

Yes, this is how you write an em-dash in Texinfo source.  (I can't
find this in the Texinfo manual, but it is a convention inherited from
TeX, and I just verified that `makeinfo --html` understands it.)

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

Thanks.

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

Doh! Thanks for catching.

zw