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: 4242 bytes --]

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.


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