Re: [PATCH v4 5/6] regex.3, regex_t.3type, regmatch_t.3type, regoff_t.3type: Move in with regex.3

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

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

On 4/20/23 15:02, наб 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>
> ---
>  man3/regex.3              | 40 +++++++++++++++++++--------------------
>  man3type/regex_t.3type    |  1 +
>  man3type/regmatch_t.3type |  2 +-
>  man3type/regoff_t.3type   |  2 +-
>  4 files changed, 23 insertions(+), 22 deletions(-)
>  create mode 100644 man3type/regex_t.3type
> 
> diff --git a/man3/regex.3 b/man3/regex.3
> index 615e065de..6d203fa22 100644
> --- a/man3/regex.3
> +++ b/man3/regex.3
> @@ -15,7 +15,7 @@ regcomp, regexec, regerror, regfree \- POSIX regex functions
>  Standard C library
>  .RI ( libc ", " \-lc )
>  .SH SYNOPSIS
> -.nf
> +.EX
>  .B #include <regex.h>
>  .PP
>  .BI "int regcomp(regex_t *restrict " preg ", const char *restrict " regex ,
> @@ -43,7 +43,7 @@ size_t " errbuf_size );
>  .B } regmatch_t;
>  .PP
>  .BR typedef " /* ... */  " regoff_t;
> -.fi
> +.EE
>  .SH DESCRIPTION
>  .SS Compilation
>  .BR regcomp ()
> @@ -60,6 +60,21 @@ is a null-terminated string.
>  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
> @@ -196,22 +211,6 @@ must be at least
>  .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
> @@ -222,7 +221,7 @@ element indicates the end offset of the match,
>  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
> @@ -346,7 +345,8 @@ POSIX.1-2008.
>  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
> diff --git a/man3type/regex_t.3type b/man3type/regex_t.3type
> new file mode 100644
> index 000000000..c0daaf0ff
> --- /dev/null
> +++ b/man3type/regex_t.3type

The link changes in the same patch that does the move are fine.
git should be smart enough to follow that, and it will help
humans too.  This short removal of the file might be worse than
than the previous approach, I fear.

> @@ -0,0 +1 @@
> +.so man3/regex.3
> diff --git a/man3type/regmatch_t.3type b/man3type/regmatch_t.3type
> index dc78f2cf2..c0daaf0ff 100644
> --- a/man3type/regmatch_t.3type
> +++ b/man3type/regmatch_t.3type
> @@ -1 +1 @@
> -.so man3type/regex_t.3type
> +.so man3/regex.3
> diff --git a/man3type/regoff_t.3type b/man3type/regoff_t.3type
> index dc78f2cf2..c0daaf0ff 100644
> --- a/man3type/regoff_t.3type
> +++ b/man3type/regoff_t.3type
> @@ -1 +1 @@
> -.so man3type/regex_t.3type
> +.so man3/regex.3


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

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