Re: [PATCH v8 3/5] regex.3: Finalise move of reg*.3type

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

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



On 4/21/23 12:33, Alejandro Colomar wrote:
> Hi!
> 
> On 4/21/23 04:48, наб wrote:
>> They're inextricably linked, not cross-referenced at all,
>> and not used anywhere else.
>>
>> Now that they (realistically) exist to the reader, add a note
>> on how big nmatch can be; POSIX even says "The application developer
>> should note that there is probably no reason for using a value of
>> nmatch that is larger than preg−>re_nsub+1.".
>>
>> Also remove the now-duplicate regmatch_t declaration.
>>
>> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> 
> Patch applied, with minor tweaks; see below (I guess you approve them).
> 
> Cheers,
> Alex
> 
>> ---
>>  man3/regex.3 | 54 +++++++++++++++++++++++++++++++++-------------------
>>  1 file changed, 34 insertions(+), 20 deletions(-)
>>
>> diff --git a/man3/regex.3 b/man3/regex.3
>> index f6465d484..46fd3adef 100644
>> --- a/man3/regex.3
>> +++ b/man3/regex.3
>> @@ -15,7 +15,7 @@ .SH LIBRARY
>>  Standard C library
>>  .RI ( libc ", " \-lc )
>>  .SH SYNOPSIS
>> -.nf
>> +.EX
> 
> I've been thinking about this, but am not yet fully convinced.  I'll
> propose you the two alternatives, and let you decide what looks best.
> 
> (a)  Use .nf/.fi for the function prototypes, and .EX/.EE for the
>      types.
> 
> (b)  .EX/.EE for everything, as you did.
> 
> Please have a look at the PDF versions (you can run
> `pdfman ./man3/regex.3` after you `source ./scripts/bash_aliases`).
> 
> If you're going to use it often, I suggest the following in
> ~/.bash_aliases:
> 
> if [ -f ~/src/linux/man-pages/man-pages/main/scripts/bash_aliases ]; then
> 	. ~/src/linux/man-pages/man-pages/main/scripts/bash_aliases;
> fi;
> 
> 
> I've remove these bits from this patch, since the rest seems
> uncontroversial to me.

But I haven't pushed, so that we can still have it in the same
patch if you confirm.

> 
> 
>>  .B #include <regex.h>
>>  .PP
>>  .BI "int regcomp(regex_t *restrict " preg ", const char *restrict " regex ,
>> @@ -43,7 +43,7 @@ .SH SYNOPSIS
>>  .B } regmatch_t;
>>  .PP
>>  .BR typedef " /* ... */  " regoff_t;
>> -.fi
>> +.EE
>>  .SH DESCRIPTION
>>  .SS Compilation
>>  .BR regcomp ()
>> @@ -60,6 +60,21 @@ .SS Compilation
>>  The locale must be the same when running
>>  .BR regexec ().
>>  .PP
>> +After
>> +.BR regcomp ()
>> +succeeds,
>> +.I preg->re_nsub
>> +holds the number of subexpressions in
>> +.IR regex .
>> +Thus, a value of
>> +.I preg->re_nsub
>> ++ 1
>> +passed as
>> +.I nmatch
>> +to
>> +.BR regexec ()
>> +is sufficient to capture all matches.
>> +.PP
>>  .I cflags
>>  is the
>>  bitwise OR
>> @@ -192,22 +207,6 @@ .SS Match offsets
>>  .IR N+1 .)
>>  Any unused structure elements will contain the value \-1.
>>  .PP
>> -The
>> -.I regmatch_t
>> -structure which is the type of
>> -.I pmatch
>> -is defined in
>> -.IR <regex.h> .
>> -.PP
>> -.in +4n
>> -.EX
>> -typedef struct {
>> -    regoff_t rm_so;
>> -    regoff_t rm_eo;
>> -} regmatch_t;
>> -.EE
>> -.in
>> -.PP
>>  Each
>>  .I rm_so
>>  element that is not \-1 indicates the start offset of the next largest
>> @@ -218,7 +217,7 @@ .SS Match offsets
>>  which is the offset of the first character after the matching text.
>>  .PP
>>  .I regoff_t
>> -It is a signed integer type
>> +is a signed integer type
>>  capable of storing the largest value that can be stored in either an
>>  .I ptrdiff_t
>>  type or a
>> @@ -344,12 +343,27 @@ .SH HISTORY
>>  POSIX.1-2001.
>>  .PP
>>  Prior to POSIX.1-2008,
>> -the type was
>> +.I regoff_t
>> +was required to be
>>  capable of storing the largest value that can be stored in either an
>>  .I off_t
>>  type or a
>>  .I ssize_t
>>  type.
>> +.SH NOTES
> 
> NOTES is dreaded, and only used when no other section would work.
> CAVEATS (recently added to the Linux man-pages) is more suitable;
> I've edited your patch to use it.
> 
>> +.I re_nsub
>> +is only required to be initialized if
>> +.B REG_NOSUB
>> +wasn't specified, but all known implementations initialize it regardless.
>> +.\" glibc, musl, 4.4BSD, illumos
>> +.PP
>> +Both
>> +.I regex_t
>> +and
>> +.I regmatch_t
>> +may (and do) have more members, in any order.
>> +Always reference them by name.
>> +.\" illumos has two more start/end pairs and the first one is of pointers
>>  .SH EXAMPLES
>>  .EX
>>  #include <stdint.h>
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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