setlocale.3: Wording issues

setlocale.3: Wording issues

[Alejandro Colomar (man-pages)]

Hi Michael,

I don't understand what this paragraph means, I think it needs some wfix.

Around setlocale.3:179:
[
       On  startup  of  the main program, the portable "C" locale is
       selected as default.  A program may be made portable  to  all
       locales by calling:

           setlocale(LC_ALL, "");

       after  program  initialization,  by using the values returned
       from a localeconv(3) call for  locale-dependent  information,
       by  using the multibyte and wide character functions for text
       processing if MB_CUR_MAX > 1, and by  using  strcoll(3),  wc‐
       scoll(3) or strxfrm(3), wcsxfrm(3) to compare strings.

<<<Especially these last 2 lines

]

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: setlocale.3: Wording issues

[Michael Kerrisk (man-pages)]

Hi Alex,

On 1/7/21 7:32 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> I don't understand what this paragraph means, I think it needs some wfix.
> 
> Around setlocale.3:179:
> [
>        On  startup  of  the main program, the portable "C" locale is
>        selected as default.  A program may be made portable  to  all
>        locales by calling:
> 
>            setlocale(LC_ALL, "");
> 
>        after  program  initialization,  by using the values returned
>        from a localeconv(3) call for  locale-dependent  information,
>        by  using the multibyte and wide character functions for text
>        processing if MB_CUR_MAX > 1, and by  using  strcoll(3),  wc‐
>        scoll(3) or strxfrm(3), wcsxfrm(3) to compare strings.
> 
> <<<Especially these last 2 lines
> 
> ]

I see what you mean. I had to read that a few times to parse it.
It looks like the text was added in 1999. I think the following
clarifies and preserves the meaning:

[[
       On startup of the main program, the portable "C" locale is select‐
       ed  as  default.  A program may be made portable to all locales by
       calling:

           setlocale(LC_ALL, "");

       after program initialization, and then:

       (a) using the values returned from a localeconv(3)  call  for  lo‐
           cale-dependent information;

       (c) using the multibyte and wide character functions for text pro‐
           cessing if MB_CUR_MAX > 1; and

       (c) using strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3) to com‐
           pare strings.
]]

What do you think?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: setlocale.3: Wording issues

[Alejandro Colomar (man-pages)]

Hi Michael,

On 1/8/21 10:26 AM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 1/7/21 7:32 PM, Alejandro Colomar (man-pages) wrote:
>> Hi Michael,
>>
>> I don't understand what this paragraph means, I think it needs some wfix.
>>
>> Around setlocale.3:179:
>> [
>>        On  startup  of  the main program, the portable "C" locale is
>>        selected as default.  A program may be made portable  to  all
>>        locales by calling:
>>
>>            setlocale(LC_ALL, "");
>>
>>        after  program  initialization,  by using the values returned
>>        from a localeconv(3) call for  locale-dependent  information,
>>        by  using the multibyte and wide character functions for text
>>        processing if MB_CUR_MAX > 1, and by  using  strcoll(3),  wc‐
>>        scoll(3) or strxfrm(3), wcsxfrm(3) to compare strings.
>>
>> <<<Especially these last 2 lines
>>
>> ]
> 
> I see what you mean. I had to read that a few times to parse it.
> It looks like the text was added in 1999. I think the following
> clarifies and preserves the meaning:
> 
> [[
>        On startup of the main program, the portable "C" locale is select‐
>        ed  as  default.  A program may be made portable to all locales by
>        calling:
> 
>            setlocale(LC_ALL, "");
> 
>        after program initialization, and then:
> 
>        (a) using the values returned from a localeconv(3)  call  for  lo‐
>            cale-dependent information;
> 
>        (c) using the multibyte and wide character functions for text pro‐
>            cessing if MB_CUR_MAX > 1; and
> 
>        (c) using strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3) to com‐
>            pare strings.
> ]]
> 
> What do you think?

Much better.

But I still don't get why [A, B or  C, D].  What does it mean?

Thanks,

Alex


> 
> Thanks,
> 
> Michael
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: setlocale.3: Wording issues

[Michael Kerrisk (man-pages)]

On 1/8/21 12:41 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> On 1/8/21 10:26 AM, Michael Kerrisk (man-pages) wrote:
>> Hi Alex,
>>
>> On 1/7/21 7:32 PM, Alejandro Colomar (man-pages) wrote:
>>> Hi Michael,
>>>
>>> I don't understand what this paragraph means, I think it needs some wfix.
>>>
>>> Around setlocale.3:179:
>>> [
>>>        On  startup  of  the main program, the portable "C" locale is
>>>        selected as default.  A program may be made portable  to  all
>>>        locales by calling:
>>>
>>>            setlocale(LC_ALL, "");
>>>
>>>        after  program  initialization,  by using the values returned
>>>        from a localeconv(3) call for  locale-dependent  information,
>>>        by  using the multibyte and wide character functions for text
>>>        processing if MB_CUR_MAX > 1, and by  using  strcoll(3),  wc‐
>>>        scoll(3) or strxfrm(3), wcsxfrm(3) to compare strings.
>>>
>>> <<<Especially these last 2 lines
>>>
>>> ]
>>
>> I see what you mean. I had to read that a few times to parse it.
>> It looks like the text was added in 1999. I think the following
>> clarifies and preserves the meaning:
>>
>> [[
>>        On startup of the main program, the portable "C" locale is select‐
>>        ed  as  default.  A program may be made portable to all locales by
>>        calling:
>>
>>            setlocale(LC_ALL, "");
>>
>>        after program initialization, and then:
>>
>>        (a) using the values returned from a localeconv(3)  call  for  lo‐
>>            cale-dependent information;
>>
>>        (c) using the multibyte and wide character functions for text pro‐
>>            cessing if MB_CUR_MAX > 1; and
>>
>>        (c) using strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3) to com‐
>>            pare strings.
>> ]]
>>
>> What do you think?
> 
> Much better.
> 
> But I still don't get why [A, B or  C, D].  What does it mean?

I don't read it that way. I see it as: [A and (B and/or C and/or D].
Do you see what I mean?

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: setlocale.3: Wording issues

[Alejandro Colomar (man-pages)]

Hi Michael,

On 1/8/21 1:45 PM, Michael Kerrisk (man-pages) wrote:
> On 1/8/21 12:41 PM, Alejandro Colomar (man-pages) wrote:
>> Hi Michael,
>>
>> On 1/8/21 10:26 AM, Michael Kerrisk (man-pages) wrote:
>>> Hi Alex,
>>>
>>> On 1/7/21 7:32 PM, Alejandro Colomar (man-pages) wrote:
>>>> Hi Michael,
>>>>
>>>> I don't understand what this paragraph means, I think it needs some wfix.
>>>>
>>>> Around setlocale.3:179:
>>>> [
>>>>        On  startup  of  the main program, the portable "C" locale is
>>>>        selected as default.  A program may be made portable  to  all
>>>>        locales by calling:
>>>>
>>>>            setlocale(LC_ALL, "");
>>>>
>>>>        after  program  initialization,  by using the values returned
>>>>        from a localeconv(3) call for  locale-dependent  information,
>>>>        by  using the multibyte and wide character functions for text
>>>>        processing if MB_CUR_MAX > 1, and by  using  strcoll(3),  wc‐
>>>>        scoll(3) or strxfrm(3), wcsxfrm(3) to compare strings.
>>>>
>>>> <<<Especially these last 2 lines
>>>>
>>>> ]
>>>
>>> I see what you mean. I had to read that a few times to parse it.
>>> It looks like the text was added in 1999. I think the following
>>> clarifies and preserves the meaning:
>>>
>>> [[
>>>        On startup of the main program, the portable "C" locale is select‐
>>>        ed  as  default.  A program may be made portable to all locales by
>>>        calling:
>>>
>>>            setlocale(LC_ALL, "");
>>>
>>>        after program initialization, and then:
>>>
>>>        (a) using the values returned from a localeconv(3)  call  for  lo‐
>>>            cale-dependent information;
>>>
>>>        (c) using the multibyte and wide character functions for text pro‐
>>>            cessing if MB_CUR_MAX > 1; and
>>>
>>>        (c) using strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3) to com‐
>>>            pare strings.
>>> ]]
>>>
>>> What do you think?
>>
>> Much better.
>>
>> But I still don't get why [A, B or  C, D].  What does it mean?
> 
> I don't read it that way. I see it as: [A and (B and/or C and/or D].
> Do you see what I mean?

About the three lines (a) (b) (c) as a whole, yes, I understand that part.
About [strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3)], nope, I still
can't understand the punctuation there.
So I can't parse the inner contents of (c).

Thanks,

Alex

> 
> Thanks,
> 
> Michael
> 
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: setlocale.3: Wording issues

[Michael Kerrisk (man-pages)]

[CC += Bruno]

Hi Alex,

On 1/8/21 2:05 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> On 1/8/21 1:45 PM, Michael Kerrisk (man-pages) wrote:
>> On 1/8/21 12:41 PM, Alejandro Colomar (man-pages) wrote:
>>> Hi Michael,
>>>
>>> On 1/8/21 10:26 AM, Michael Kerrisk (man-pages) wrote:
>>>> Hi Alex,
>>>>
>>>> On 1/7/21 7:32 PM, Alejandro Colomar (man-pages) wrote:
>>>>> Hi Michael,
>>>>>
>>>>> I don't understand what this paragraph means, I think it needs some wfix.
>>>>>
>>>>> Around setlocale.3:179:
>>>>> [
>>>>>        On  startup  of  the main program, the portable "C" locale is
>>>>>        selected as default.  A program may be made portable  to  all
>>>>>        locales by calling:
>>>>>
>>>>>            setlocale(LC_ALL, "");
>>>>>
>>>>>        after  program  initialization,  by using the values returned
>>>>>        from a localeconv(3) call for  locale-dependent  information,
>>>>>        by  using the multibyte and wide character functions for text
>>>>>        processing if MB_CUR_MAX > 1, and by  using  strcoll(3),  wc‐
>>>>>        scoll(3) or strxfrm(3), wcsxfrm(3) to compare strings.
>>>>>
>>>>> <<<Especially these last 2 lines
>>>>>
>>>>> ]
>>>>
>>>> I see what you mean. I had to read that a few times to parse it.
>>>> It looks like the text was added in 1999. I think the following
>>>> clarifies and preserves the meaning:
>>>>
>>>> [[
>>>>        On startup of the main program, the portable "C" locale is select‐
>>>>        ed  as  default.  A program may be made portable to all locales by
>>>>        calling:
>>>>
>>>>            setlocale(LC_ALL, "");
>>>>
>>>>        after program initialization, and then:
>>>>
>>>>        (a) using the values returned from a localeconv(3)  call  for  lo‐
>>>>            cale-dependent information;
>>>>
>>>>        (c) using the multibyte and wide character functions for text pro‐
>>>>            cessing if MB_CUR_MAX > 1; and
>>>>
>>>>        (c) using strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3) to com‐
>>>>            pare strings.
>>>> ]]
>>>>
>>>> What do you think?
>>>
>>> Much better.
>>>
>>> But I still don't get why [A, B or  C, D].  What does it mean?
>>
>> I don't read it that way. I see it as: [A and (B and/or C and/or D].
>> Do you see what I mean?
> 
> About the three lines (a) (b) (c) as a whole, yes, I understand that part.
> About [strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3)], nope, I still
> can't understand the punctuation there.
> So I can't parse the inner contents of (c).

Ah sorry. Now I see what you mean. I'm not sure of this, but I suspect
that it's supposed to mean:

    Use [strcoll(3)+strxfrm(3)] for non-wide-char strings and 
    [wcscoll(3)+wcsxfrm(3)] for wide char strings.

Maybe Bruno can help.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: setlocale.3: Wording issues

[Alejandro Colomar (man-pages)]

Hi Michael,

On 1/8/21 2:17 PM, Michael Kerrisk (man-pages) wrote:
> [CC += Bruno]
> 
> Hi Alex,
> 
> On 1/8/21 2:05 PM, Alejandro Colomar (man-pages) wrote:
>> Hi Michael,
>>
>> On 1/8/21 1:45 PM, Michael Kerrisk (man-pages) wrote:
>>> On 1/8/21 12:41 PM, Alejandro Colomar (man-pages) wrote:
>>>> Hi Michael,
>>>>
>>>> On 1/8/21 10:26 AM, Michael Kerrisk (man-pages) wrote:
>>>>> Hi Alex,
>>>>>
>>>>> On 1/7/21 7:32 PM, Alejandro Colomar (man-pages) wrote:
>>>>>> Hi Michael,
>>>>>>
>>>>>> I don't understand what this paragraph means, I think it needs some wfix.
>>>>>>
>>>>>> Around setlocale.3:179:
>>>>>> [
>>>>>>        On  startup  of  the main program, the portable "C" locale is
>>>>>>        selected as default.  A program may be made portable  to  all
>>>>>>        locales by calling:
>>>>>>
>>>>>>            setlocale(LC_ALL, "");
>>>>>>
>>>>>>        after  program  initialization,  by using the values returned
>>>>>>        from a localeconv(3) call for  locale-dependent  information,
>>>>>>        by  using the multibyte and wide character functions for text
>>>>>>        processing if MB_CUR_MAX > 1, and by  using  strcoll(3),  wc‐
>>>>>>        scoll(3) or strxfrm(3), wcsxfrm(3) to compare strings.
>>>>>>
>>>>>> <<<Especially these last 2 lines
>>>>>>
>>>>>> ]
>>>>>
>>>>> I see what you mean. I had to read that a few times to parse it.
>>>>> It looks like the text was added in 1999. I think the following
>>>>> clarifies and preserves the meaning:
>>>>>
>>>>> [[
>>>>>        On startup of the main program, the portable "C" locale is select‐
>>>>>        ed  as  default.  A program may be made portable to all locales by
>>>>>        calling:
>>>>>
>>>>>            setlocale(LC_ALL, "");
>>>>>
>>>>>        after program initialization, and then:
>>>>>
>>>>>        (a) using the values returned from a localeconv(3)  call  for  lo‐
>>>>>            cale-dependent information;
>>>>>
>>>>>        (c) using the multibyte and wide character functions for text pro‐
>>>>>            cessing if MB_CUR_MAX > 1; and
>>>>>
>>>>>        (c) using strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3) to com‐
>>>>>            pare strings.
>>>>> ]]
>>>>>
>>>>> What do you think?
>>>>
>>>> Much better.
>>>>
>>>> But I still don't get why [A, B or  C, D].  What does it mean?
>>>
>>> I don't read it that way. I see it as: [A and (B and/or C and/or D].
>>> Do you see what I mean?
>>
>> About the three lines (a) (b) (c) as a whole, yes, I understand that part.
>> About [strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3)], nope, I still
>> can't understand the punctuation there.
>> So I can't parse the inner contents of (c).
> 
> Ah sorry. Now I see what you mean. I'm not sure of this, but I suspect
> that it's supposed to mean:
> 
>     Use [strcoll(3)+strxfrm(3)] for non-wide-char strings and 
>     [wcscoll(3)+wcsxfrm(3)] for wide char strings.
> 
> Maybe Bruno can help.

Yes, that was my first thought (after a few trials), but I preferred to
check with you :)

I don't know how to express it.
Maybe [A and B, or C and D]?

Thanks,

Alex

> 
> Thanks,
> 
> Michael
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: setlocale.3: Wording issues

[Bruno Haible]

Alejandro Colomar (man-pages) wrote:
> >>>>>        (a) using the values returned from a localeconv(3)  call  for  lo‐
> >>>>>            cale-dependent information;
> >>>>>
> >>>>>        (c) using the multibyte and wide character functions for text pro‐
> >>>>>            cessing if MB_CUR_MAX > 1; and
> >>>>>
> >>>>>        (c) using strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3) to com‐
> >>>>>            pare strings.

If you feel it's better to separate the functions for strings from the functions
for wide strings, I would write it like this:

        * using the values returned from a localeconv(3)  call  for  lo‐
          cale-dependent information;

        * using the multibyte and wide character functions for text pro‐
          cessing if MB_CUR_MAX > 1;

        * using strcoll(3) or strxfrm(3) to compare strings; and

        * using wcscoll(3) or wcsxfrm(3) to compare wide-character strings.

Regarding the type of enumeration, I generally use
  - (1), (2), (3), ... when the order matters, e.g. to describe steps that
    need to be done one after the other,
  - (a), (b), (c), ... for alternatives ("or"),
  - simple *, *, *, ... for other enumerations.

Bruno

Re: setlocale.3: Wording issues

[Michael Kerrisk (man-pages)]

On 1/8/21 5:10 PM, Bruno Haible wrote:
> Alejandro Colomar (man-pages) wrote:
>>>>>>>        (a) using the values returned from a localeconv(3)  call  for  lo‐
>>>>>>>            cale-dependent information;
>>>>>>>
>>>>>>>        (c) using the multibyte and wide character functions for text pro‐
>>>>>>>            cessing if MB_CUR_MAX > 1; and
>>>>>>>
>>>>>>>        (c) using strcoll(3), wcscoll(3) or strxfrm(3), wcsxfrm(3) to com‐
>>>>>>>            pare strings.
> 
> If you feel it's better to separate the functions for strings from the functions
> for wide strings, I would write it like this:
> 
>         * using the values returned from a localeconv(3)  call  for  lo‐
>           cale-dependent information;
> 
>         * using the multibyte and wide character functions for text pro‐
>           cessing if MB_CUR_MAX > 1;
> 
>         * using strcoll(3) or strxfrm(3) to compare strings; and
> 
>         * using wcscoll(3) or wcsxfrm(3) to compare wide-character strings.

Thanks, Bruno!

> Regarding the type of enumeration, I generally use
>   - (1), (2), (3), ... when the order matters, e.g. to describe steps that
>     need to be done one after the other,
>   - (a), (b), (c), ... for alternatives ("or"),
>   - simple *, *, *, ... for other enumerations.

Agreed. I changed it.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/