Re: Further inconsistencies in FTM

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi ALex,

On 1/8/21 12:14 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> On 1/8/21 11:50 AM, Michael Kerrisk (man-pages) wrote:
>> Hi Alex,
>>
>> On 1/7/21 6:04 PM, Alejandro Colomar (man-pages) wrote:
>>> Hi Michael,
>>>
>>> [[
>>> SYNOPSIS
>>>        #include <stdlib.h>
>>>
>>>        int clearenv(void);
>>>
>>>    Feature   Test   Macro   Requirements  for  glibc  (see  fea‐
>>>    ture_test_macros(7)):
>>>
>>>        clearenv():
>>>            /* Glibc since 2.19: */ _DEFAULT_SOURCE
>>>                || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
>>>
>>> ]]
>>>
>>> [[
>>> SYNOPSIS
>>>        #include <time.h>
>>>
>>>        int dysize(int year);
>>>
>>>    Feature   Test   Macro   Requirements  for  glibc  (see  fea‐
>>>    ture_test_macros(7)):
>>>
>>>        dysize():
>>>            Since glibc 2.19:
>>>                _DEFAULT_SOURCE
>>>            Glibc 2.19 and earlier:
>>>                _BSD_SOURCE || _SVID_SOURCE
>>>
>>> ]]
>>>
>>> Which one do you prefer?
>>
>> Probably the latter, since it is a little easier to read.
>>
>> The former form has crept in as a result of my attempts
>> to keep the FTM info somewhat compact. See, for example:
>>
>>        chroot():
>>            Since glibc 2.2.2:
>>                _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
>>                    || /* Since glibc 2.20: */ _DEFAULT_SOURCE
>>                    || /* Glibc <= 2.19: */ _BSD_SOURCE
>>            Before glibc 2.2.2:
>>                none
>>
>>
>>        waitid():
>>            Since glibc 2.26:
>>                _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
>>            Glibc 2.25 and earlier:
>>                _XOPEN_SOURCE
>>                    || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
>>                    || /* Glibc <= 2.19: */ _BSD_SOURCE
>>
>> The latter could be rewritten (I hope I got the expansion right) 
>> as:
>>        waitid():
>>            Since glibc 2.26:
>>                _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L
>>            Glibc 2.20 to 2.25
>>                _XOPEN_SOURCE ||  _POSIX_C_SOURCE >= 200809L
>>            Glibc 2.12 to 2.19
>>                _XOPEN_SOURCE ||  _POSIX_C_SOURCE >= 200809L
>>                    || _BSD_SOURCE
>>            Glibc 2.11 and earlier:
>>                _XOPEN_SOURCE || _BSD_SOURCE
>>
>>  
>> That's more verbose, but perhaps also easier to read, now that
>> I look at it.
>>
>> I'm not sure whether you are thinking of doing some global edit,
>> but if you are, perhaps we need to discuss this more.
> 
> Well, I'm not thinking of a global edit right now (we've had enough of
> those for now I think :), but more as something to think for the future.
> So yes, a discussion about if we prefer to have a single way of
> expressing FTM or if there are times when the other way is better would
> be good.
> Your thoughts?

On reflection, I think the final form that I have shown may be
preferable.

Thanks,

Michael


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