Re: [PATCH] strftime.3: mention strftime_l() with .so link

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4581 bytes --]



On 7/19/22 23:55, Alejandro Colomar wrote:
> Hi!
> 
> On 7/19/22 23:27, наб wrote:
>> On Tue, Jul 19, 2022 at 10:50:06PM +0200, Alejandro Colomar wrote:
>>> Also, please add the link page name to the list of affecteed pages:
>>> strftime.3, strftime_l.3: ...
>>
>> Fixed.
>>
>>> Prefer .PP
>>>
>>> We avoid raw roff requests in man(7) pages as much as possible.
>>> I'd tell you how to get the same behavior with rare man(7) macros, but I
>>> don't think we need to complicate it, when .PP is also nice here.
>>> But just for you to know, there's .PD 0 in man(7).
>>
>> I grepped for .br specifically and saw it's used so I used it.
>> Replaced with .PD 0, .PP, .PD to the same effect.
> 
> Yeah, mtk wasn't very happy with me fixing existing pages, under the 
> fear of churn.  I'm more concerned with the maintainability issues of 
> having existing undesirable code (even if it Just Works for now and 
> isn't really broken), since it leads to contributors like you to think 
> that we actually use it, and then we (I?) keep receiving patches with 
> undesirable code; then I need to have discussions explaining that we 
> have old code that uses it, but I'd prefer to avoid it in new code, etc.
> 
> So yes, we have old code that at some point I'd like to fix, and I will, 
> but there's too much of it. :)
> 
>>
>> See updated scissor-patch below:
>> -- >8 --
>> Date: Tue, 19 Jul 2022 20:46:49 +0200
>> Subject: [PATCH v2] strftime.3, strftime_l.3: mention strftime_l() 
>> with .so
>>   link
> 
> Okay, so you want to keep "mention".  I will keep it ;)
> 
> Cheers,
> 
> Alex
> 
>>
>> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
>> ---
>>   man3/strftime.3   | 29 ++++++++++++++++++++++++++++-
>>   man3/strftime_l.3 |  1 +
>>   2 files changed, 29 insertions(+), 1 deletion(-)
>>   create mode 100644 man3/strftime_l.3
>>
>> diff --git a/man3/strftime.3 b/man3/strftime.3
>> index dc98a5122..a93c0f4c2 100644
>> --- a/man3/strftime.3
>> +++ b/man3/strftime.3
>> @@ -27,6 +27,11 @@ Standard C library
>>   .BI "size_t strftime(char *restrict " s ", size_t " max ,
>>   .BI "                const char *restrict " format ,
>>   .BI "                const struct tm *restrict " tm );
>> +.PP
>> +.BI "size_t strftime_l(char *restrict " s ", size_t " max ,
>> +.BI "                  const char *restrict " format ,
>> +.BI "                  const struct tm *restrict " tm ,
>> +.BI "                  locale_t " locale );
>>   .fi
>>   .SH DESCRIPTION
>>   The
>> @@ -471,6 +476,20 @@ as an argument to a
>>   One example of such alternative forms is the Japanese era calendar 
>> scheme in the
>>   .B ja_JP
>>   glibc locale.
>> +.PP
>> +.\" POSIX.1-2008 TC2:
>> +.\"   [CX] The strftime_l() function shall be equivalent to the 
>> strftime() function, except that the locale data used is from the 
>> locale represented by locale.
>> +.\"   [CX] The behavior is undefined if the locale argument to 
>> strftime_l() is the special locale object LC_GLOBAL_LOCALE or is not a 
>> valid locale object handle.

Maybe these comments would be better placed in the commit message?  I 
tend to dislike code comments.

>> +.BR strftime_l ()
>> +is equivalent to
>> +.BR strftime (),
>> +except it uses the specified
>> +.I locale
>> +instead of the current locale.
>> +The behaviour is undefined if
>> +.I locale
>> +is invalid or
>> +.BR LC_GLOBAL_LOCALE .
>>   .SH RETURN VALUE
>>   Provided that the result string,
>>   including the terminating null byte, does not exceed
>> @@ -516,14 +535,22 @@ lbx lb lb
>>   l l l.
>>   Interface    Attribute    Value
>>   T{
>> -.BR strftime ()
>> +.BR strftime (),
>> +.BR strftime_l ()
>>   T}    Thread safety    MT-Safe env locale
>>   .TE
>>   .hy
>>   .ad
>>   .sp 1
>>   .SH CONFORMING TO
>> +.BR strftime ():
>>   SVr4, C89, C99.
>> +.PD 0
>> +.PP
>> +.PD
>> +.BR strftime_l ():
>> +POSIX.1-2008.
>> +.PP
>>   .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the 
>> details
>>   .\" in the standards changed across versions. Investigate and
>>   .\" write up.
>> diff --git a/man3/strftime_l.3 b/man3/strftime_l.3
>> new file mode 100644
>> index 000000000..02e797a23
>> --- /dev/null
>> +++ b/man3/strftime_l.3
>> @@ -0,0 +1 @@
>> +.so man3/strftime.3
> 

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]