Re: [PATCH v5 3/8] regex.3: Desoupify regerror() description

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

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

On 4/20/23 17:35, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>  man3/regex.3 | 46 ++++++++++++++++++++--------------------------
>  1 file changed, 20 insertions(+), 26 deletions(-)
> 
> diff --git a/man3/regex.3 b/man3/regex.3
> index ae160c9b3..c5185549b 100644
> --- a/man3/regex.3
> +++ b/man3/regex.3
> @@ -26,7 +26,7 @@ .SH SYNOPSIS
>  .BI "            int " eflags );
>  .PP
>  .BI "size_t regerror(int " errcode ", const regex_t *_Nullable restrict " preg ,
> -.BI "            char " errbuf "[restrict ." errbuf_size "], \
> +.BI "                char " errbuf "[restrict ." errbuf_size "], \

See man-pages(7):

FORMATTING AND WORDING CONVENTIONS
       The  following  subsections  note some details for preferred formatting
       and wording conventions in various sections of the pages  in  the  man‐
       pages project.

   SYNOPSIS
       [...]

       In the SYNOPSIS, a long function prototype may  need  to  be  continued
       over  to the next line.  The continuation line is indented according to
       the following rules:

       (1)  If there is a single such prototype that needs  to  be  continued,
            then align the continuation line so that when the page is rendered
            on  a fixed‐width font device (e.g., on an xterm) the continuation
            line starts just below the start of the argument list in the  line
            above.   (Exception:  the indentation may be adjusted if necessary
            to prevent a very long continuation line or a further continuation
            line where the function prototype is very long.)  As an example:

                int tcsetattr(int fd, int optional_actions,
                              const struct termios *termios_p);

       (2)  But, where multiple functions in the SYNOPSIS require continuation
            lines, and the function names have different lengths,  then  align
            all continuation lines to start in the same column.  This provides
            a nicer rendering in PDF output (because the SYNOPSIS uses a vari‐
            able  width  font  where  spaces render narrower than most charac‐
            ters).  As an example:

                int getopt(int argc, char * const argv[],
                           const char *optstring);
                int getopt_long(int argc, char * const argv[],
                           const char *optstring,
                           const struct option *longopts, int *longindex);


>  size_t " errbuf_size );
>  .BI "void regfree(regex_t *" preg );
>  .fi
> @@ -207,34 +207,28 @@ .SS Error reporting
>  .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
> -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]).
> +is
> +.BR 0 ,
> +the size of the required buffer is returned.
> +Otherwise, up to
> +.I errbuf_size
> +bytes are copied to
> +.IR errbuf ;
> +the error string is always null-terminated, and truncated to fit.
>  .SS 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 --]