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

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

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

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