Issue in man page regex.3

Issue in man page regex.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    null-terminated → NUL-terminated

"B<regexec>()  is used to match a null-terminated string against the "
"precompiled pattern buffer, I<preg>.  I<nmatch> and I<pmatch> are used to "
"provide information regarding the location of any matches.  I<eflags> is the "
"bitwise-B<or> of zero or more of the following flags:"

Issue in man page regex.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    null byte → NUL byte

"B<regerror>()  is passed the error code, I<errcode>, the pattern buffer, "
"I<preg>, a pointer to a character string buffer, I<errbuf>, and the size of "
"the string buffer, I<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<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)."

Issue in man page regex.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    How can a variable (I<preg>) free memory? Isn't it B<regfree>() which frees the memory?

"Supplying B<regfree>()  with a precompiled pattern buffer, I<preg> will free "
"the memory allocated to the pattern buffer by the compiling process, "
"B<regcomp>()."

Re: Issue in man page regex.3

[Alejandro Colomar]

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

Hi Helge,

On 1/22/23 20:31, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    null-terminated → NUL-terminated

I prefer NUL-terminated too, but there's a historic tradition of using 
null-terminated and similar syntax in the manual pages.  The intent is to reduce 
confusion between NUL and NULL.  See man-pages(7).

I believe that doesn't make any sense, since there's at least some visual 
difference between NUL and NULL, but the isn't any difference between null and 
null (apart from the context).

Sooo, I may apply policy change to stop using English syntax for these terms, 
and start using NUL and NULL consistently.

Cheers,

Alex


> 
> "B<regexec>()  is used to match a null-terminated string against the"
> "precompiled pattern buffer, I<preg>.  I<nmatch> and I<pmatch> are used to"
> "provide information regarding the location of any matches.  I<eflags> is the"
> "bitwise-B<or> of zero or more of the following flags:"

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

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

Re: Issue in man page regex.3

[Alejandro Colomar]

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

Hi Helge,

On 1/22/23 20:31, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    How can a variable (I<preg>) free memory? Isn't it B<regfree>() which frees the memory?

How about the patch below?

Cheers,

Alex

> 
> "Supplying B<regfree>()  with a precompiled pattern buffer, I<preg> will free"
> "the memory allocated to the pattern buffer by the compiling process,"
> "B<regcomp>()."


diff --git a/man3/regex.3 b/man3/regex.3
index 6f5831f24..f6faf6240 100644
--- a/man3/regex.3
+++ b/man3/regex.3
@@ -240,7 +240,7 @@ .SS POSIX pattern buffer freeing
  Supplying
  .BR regfree ()
  with a precompiled pattern buffer,
-.I preg
+.IR preg ,
  will free the memory allocated to the pattern buffer by the compiling
  process,
  .BR regcomp ().


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

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

Re: Issue in man page regex.3

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 1331 bytes --]

Hello Alex,
On Sun, Jan 22, 2023 at 10:03:46PM +0100, Alejandro Colomar wrote:
> On 1/22/23 20:31, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue:    How can a variable (I<preg>) free memory? Isn't it B<regfree>() which frees the memory?
> 
> How about the patch below?
> 
> Cheers,
> 
> Alex
> 
> > 
> > "Supplying B<regfree>()  with a precompiled pattern buffer, I<preg> will free"
> > "the memory allocated to the pattern buffer by the compiling process,"
> > "B<regcomp>()."
> 
> 
> diff --git a/man3/regex.3 b/man3/regex.3
> index 6f5831f24..f6faf6240 100644
> --- a/man3/regex.3
> +++ b/man3/regex.3
> @@ -240,7 +240,7 @@ .SS POSIX pattern buffer freeing
>  Supplying
>  .BR regfree ()
>  with a precompiled pattern buffer,
> -.I preg
> +.IR preg ,
>  will free the memory allocated to the pattern buffer by the compiling
>  process,
>  .BR regcomp ().

I don't really see a change here? It's only the markup, that changed?

Greetings

         Helge


-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

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

Re: Issue in man page regex.3

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1089 bytes --]

Hi Helge,

At 2023-01-23T18:47:06+0100, Helge Kreutzmann wrote:
> On Sun, Jan 22, 2023 at 10:03:46PM +0100, Alejandro Colomar wrote:
> > On 1/22/23 20:31, Helge Kreutzmann wrote:
> > > Without further ado, the following was found:
> > > 
> > > Issue:    How can a variable (I<preg>) free memory?

It doesn't, but no claim is made that (by itself) it does.

> > > Isn't it B<regfree>() which frees the memory?

Yes.

> >  Supplying
> >  .BR regfree ()
> >  with a precompiled pattern buffer,
> > -.I preg
> > +.IR preg ,
> >  will free the memory allocated to the pattern buffer by the compiling
> >  process,
> >  .BR regcomp ().
> 
> I don't really see a change here? It's only the markup, that changed?

The addition of a comma makes clear that the subject corresponding to
the verb "will free" is "regfree", not "preg".

https://thecriticalreader.com/commas-names-titles/

Without the added comma, the sentence reads as if it has a comma splice,
and would thus be (strictly) invalid.

https://www.grammarly.com/blog/comma-splice/

Regards,
Branden

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

Re: Issue in man page regex.3

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 1590 bytes --]

Hello Branden,
On Mon, Jan 23, 2023 at 01:03:26PM -0600, G. Branden Robinson wrote:
> At 2023-01-23T18:47:06+0100, Helge Kreutzmann wrote:
> > On Sun, Jan 22, 2023 at 10:03:46PM +0100, Alejandro Colomar wrote:
> > > On 1/22/23 20:31, Helge Kreutzmann wrote:
> > > > Without further ado, the following was found:
> > > > 
> > > > Issue:    How can a variable (I<preg>) free memory?
> 
> It doesn't, but no claim is made that (by itself) it does.
> 
> > > > Isn't it B<regfree>() which frees the memory?
> 
> Yes.
> 
> > >  Supplying
> > >  .BR regfree ()
> > >  with a precompiled pattern buffer,
> > > -.I preg
> > > +.IR preg ,
> > >  will free the memory allocated to the pattern buffer by the compiling
> > >  process,
> > >  .BR regcomp ().
> > 
> > I don't really see a change here? It's only the markup, that changed?
> 
> The addition of a comma makes clear that the subject corresponding to
> the verb "will free" is "regfree", not "preg".
> 
> https://thecriticalreader.com/commas-names-titles/
> 
> Without the added comma, the sentence reads as if it has a comma splice,
> and would thus be (strictly) invalid.
> 
> https://www.grammarly.com/blog/comma-splice/


Thanks, I missed the comma. Yes, this makes it clear.

Greetings

        Helge


-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

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

Issue in man page regex.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    null byte → NUL byte

"B<regerror>()  is passed the error code, I<errcode>, the pattern buffer, "
"I<preg>, a pointer to a character string buffer, I<errbuf>, and the size of "
"the string buffer, I<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<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])."

Issue in man page regex.3

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    B<…>size_t errbuf_size → B<…size_t> I<errbuf_size>

"B<size_t regerror(>size_t errbuf_size;\n"
"B<            int >I<errcode>B<, const regex_t *_Nullable restrict >I<preg>B<,>\n"
"B<            char >I<errbuf>B<[_Nullable restrict >I<errbuf_size>B<],>\n"
"B<            size_t >I<errbuf_size>B<);>\n"
"B<void regfree(regex_t *>I<preg>B<);>\n"