Re: [PATCH v3 8/9] regex.3: desoupify function descriptions

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

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

Hi наб!

On 4/20/23 13:15, наб wrote:
> Behold:
>   regerror() is passed the error code, errcode, the pattern buffer,
>   preg, a pointer to a character string buffer, errbuf, and the size
>   of the string buffer, errbuf_size.
> 
> Absolute soup. This reads to me like an ill-conceived copy from a very
> early standard version. It looks fine in source form but is horrific to
> read as running text.
> 
> Instead, replace all of these with just the descriptions of what they do
> with their arguments. What the arguments are is very clearly noted in
> big bold in the prototypes.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

It would be nice to see the --range-diff[1], to easily review changes to
patches.  I have a hard time running vdiff[2] on the raw patches.

[1]:  <https://git-scm.com/docs/git-format-patch#Documentation/git-format-patch.txt---range-diffltpreviousgt>
      See also: <https://git-scm.com/docs/git-range-diff>

[2]:  <http://catb.org/jargon/html/V/vdiff.html>, not
      <https://www.unix.com/man-page/linux/1/vdiff/>

Cheers,
Alex

> ---
> Left one "pre"compiled buffer.
> 
>  man3/regex.3 | 80 +++++++++++++++++++++-------------------------------
>  1 file changed, 32 insertions(+), 48 deletions(-)
> 
> diff --git a/man3/regex.3 b/man3/regex.3
> index 9f262f985..9bb4a73ff 100644
> --- a/man3/regex.3
> +++ b/man3/regex.3
> @@ -25,8 +25,8 @@ Standard C library
>  .BI "            size_t " nmatch ", regmatch_t " pmatch "[restrict ." nmatch ],
>  .BI "            int " eflags );
>  .PP
> -.BI "size_t regerror(int " errcode ", const regex_t *restrict " preg ,
> -.BI "            char " errbuf "[restrict ." errbuf_size "], \
> +.BI "size_t regerror(int " errcode ", const regex_t *_Nullable restrict " preg ,
> +.BI "                char " errbuf "[restrict ." errbuf_size "], \
>  size_t " errbuf_size );
>  .BI "void regfree(regex_t *" preg );
>  .PP
> @@ -52,21 +52,13 @@ for subsequent
>  .BR regexec ()
>  searches.
>  .PP
> -.BR regcomp ()
> -is supplied with
> -.IR preg ,
> -a pointer to a pattern buffer storage area;
> -.IR regex ,
> -a pointer to the null-terminated string and
> -.IR cflags ,
> -flags used to determine the type of compilation.
> -.PP
> -All regular expression searching must be done via a compiled pattern
> -buffer, thus
> -.BR regexec ()
> -must always be supplied with the address of a
> -.BR regcomp ()-initialized
> -pattern buffer.
> +The pattern buffer at
> +.I *preg
> +is initialized.
> +.I regex
> +is a null-terminated string.
> +The locale must be the same when running
> +.BR regexec ().
>  .PP
>  After
>  .BR regcomp ()
> @@ -142,12 +134,10 @@ contains
>  .SS POSIX regex matching
>  .BR regexec ()
>  is used to match a null-terminated string
> -against the precompiled pattern buffer,
> -.IR preg .
> -.I nmatch
> -and
> -.I pmatch
> -are used to provide information regarding the location of any matches.
> +against the compiled pattern buffer in
> +.IR *preg ,
> +which must have been initialised with
> +.BR regexec ().
>  .I eflags
>  is the
>  bitwise OR
> @@ -242,34 +232,28 @@ and
>  .BR regexec ()
>  into error message strings.
>  .PP
> -.BR regerror ()
> -is passed the error code,
> -.IR errcode ,
> -the pattern buffer,
> -.IR preg ,
> -a pointer to a character string buffer,
> -.IR errbuf ,
> -and the size of the string buffer,
> -.IR errbuf_size .
> -It returns the size of the
> -.I errbuf
> -required to contain the null-terminated error message string.
> -If both
> -.I errbuf
> -and
> +.I errcode
> +must be the latest error returned from an operation on
> +.IR preg .
> +If
> +.I preg
> +is a null pointer\(emthe latest error.
> +.PP
> +If
> +.I errbuf_size
> +is
> +.BR 0 ,
> +the size of the required buffer is returned.
> +Otherwise, up to
>  .I errbuf_size
> -are nonzero,
> -.I errbuf
> -is filled in with the first
> -.I "errbuf_size \- 1"
> -characters of the error message and a terminating null byte (\[aq]\e0\[aq]).
> +bytes are copied to
> +.IR errbuf ;
> +the error string is always null-terminated, and truncated to fit.
>  .SS POSIX pattern buffer freeing
> -Supplying
>  .BR regfree ()
> -with a precompiled pattern buffer,
> -.IR preg ,
> -will free the memory allocated to the pattern buffer by the compiling
> -process,
> +invalidates the pattern buffer at
> +.IR *preg ,
> +which must have been initialized via
>  .BR regcomp ().
>  .SH RETURN VALUE
>  .BR regcomp ()

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

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