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

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

[-- Attachment #1.1: Type: text/plain, Size: 5012 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 );

Sorry, I just realized now.  Alignment of continuation lines should be 
the same for both functions.

See man-pages(7):
    SYNOPSIS
        Wrap  the  function  prototype(s)  in a .nf/.fi pair to prevent
        filling.

        In general, where more than one function prototype is shown  in
        the  SYNOPSIS,  the prototypes should not be separated by blank
        lines.  However, blank lines (achieved using .PP) may be  added
        in the following cases:

        *  to  separate  long lists of function prototypes into related
           groups (see for example list(3));

        *  in other cases that may improve readability.

        In the SYNOPSIS, a long function prototype may need to be  con‐
        tinued  over  to  the  next line.  The continuation line is in‐
        dented according to the following rules:

        1. If there is a single such prototype that needs to be contin‐
           ued, then align the continuation line so that when the  page
           is rendered on a fixed‐width font device (e.g., on an xterm)
           the continuation line starts just below the start of the ar‐
           gument  list in the line above.  (Exception: the indentation
           may be adjusted if necessary to prevent a very long continu‐
           ation line or a further continuation line where the function
           prototype is very long.)  As an example:

               int tcsetattr(int fd, int optional_actions,
                             const struct termios *termios_p);

        2. But, where multiple functions in the SYNOPSIS  require  con‐
           tinuation  lines,  and  the  function  names  have different
           lengths, then align all continuation lines to start  in  the
           same  column.  This provides a nicer rendering in PDF output
           (because the SYNOPSIS  uses  a  variable  width  font  where
           spaces  render  narrower than most characters).  As an exam‐
           ple:

               int getopt(int argc, char * const argv[],
                          const char *optstring);
               int getopt_long(int argc, char * const argv[],
                          const char *optstring,
                          const struct option *longopts, int *longindex);

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

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