Re: [PATCH] string_copying.7: tfix

[Alejandro Colomar <alx@kernel.org>]

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

Hi Lennart,

On 2023-07-28 20:41, Lennart Jablonka wrote:
> Signed-off-by: Lennart Jablonka <humm@ljabl.com>

Please send v2 with

Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>

I'll comment below on what should be removed from the patch in v2.
Reword the commit message as you find appropriate for the revision.

> ---
> On some of the commas:  There are a few of instances of
> 
> 	Subject verb object partclause, advphrase.
> 
> For example:
> 
> 	This function catenates the input character sequence contained in a null-padded wixed-width buffer, into a destination string.
> 	| subject     | verb    | object                     | participial clause                           | adverbial phrase       |
> 
> Dropping the relative clause, there shouldn't be a comma preceding the
> restrictive adverbial phrase: The input character sequence is really,
> always catenated into a destination string; that is essential.
> 
> The participial clause, being non-restrictive---there is but one input
> character sequence that could be meant---, should be enclosed by commas.
> That is the existing comma's purpose and doesn't work without the added,
> first comma.


Please include these things in the commit message.  The same it can
be useful for me to review now, it can be useful for anyone
revisiting the patch in the future.

> 
>  man7/string_copying.7 | 26 +++++++++++++-------------
>  1 file changed, 13 insertions(+), 13 deletions(-)
> 
> diff --git a/man7/string_copying.7 b/man7/string_copying.7
> index da1fc6752..04426ef77 100644
> --- a/man7/string_copying.7
> +++ b/man7/string_copying.7
> @@ -49,7 +49,7 @@ const char *restrict " src ,
>  .PP
>  // Zero a fixed-width buffer, and
>  // copy a string into a character sequence with truncation.
> -.BI "char *strncpy(char " dest "[restrict ." sz "], \
> +.BI "char *strncpy(char " dst "[restrict ." sz "], \

ok

>  const char *restrict " src ,
>  .BI "               size_t " sz );
>  .PP
> @@ -280,9 +280,9 @@ instead of
>  In programs that make considerable use of strings or character sequences,
>  and need the best performance,
>  using overlapping character sequences can make a big difference.
> -It allows holding subsequences of a larger character sequence.
> +It allows holding sub-sequences of a larger character sequence,

Use subsequences (but the s/./,/ is good).

>  while not duplicating memory
> -nor using time to do a copy.
> +or using time to do a copy.

revert

>  .PP
>  However, this is delicate,
>  since it requires using character sequences.
> @@ -397,7 +397,7 @@ It returns a pointer suitable for chaining.
>  Truncation needs to be detected only once after the last chained call.
>  .IP
>  This function is not provided by any library;
> -See EXAMPLES for a reference implementation.
> +see EXAMPLES for a reference implementation.

ok

>  .\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/
>  .TP
>  .BR strlcpy (3bsd)
> @@ -427,7 +427,7 @@ isn't large enough to hold the copy,
>  the resulting character sequence is truncated.
>  Since it creates a character sequence,
>  it doesn't need to write a terminating null byte.
> -It's impossible to distinguish truncation by the result of the call,
> +It's impossible to distinguish truncation by the result of the call

revert

>  from a character sequence that just fits the destination buffer;
>  truncation should be detected by
>  comparing the length of the input string
> @@ -444,8 +444,8 @@ is a more useful alternative to this function.
>  .\" ----- DESCRIPTION :: Functions :: zustr2ustp(3) --------------------/
>  .TP
>  .BR zustr2ustp (3)
> -This function copies the input character sequence
> -contained in a null-padded wixed-width buffer,
> +This function copies the input character sequence,

ok

> +contained in a null-padded fixed-width buffer,

ok

>  into a destination character sequence.
>  The programmer is responsible for allocating a buffer large enough.
>  It returns a pointer suitable for chaining.
> @@ -455,12 +455,12 @@ since the size of the original character sequence is always known,
>  so it wouldn't be very useful.
>  .IP
>  This function is not provided by any library;
> -See EXAMPLES for a reference implementation.
> +see EXAMPLES for a reference implementation.

ok

>  .\" ----- DESCRIPTION :: Functions :: zustr2stp(3) --------------------/
>  .TP
>  .BR zustr2stp (3)
> -This function copies the input character sequence
> -contained in a null-padded wixed-width buffer,
> +This function copies the input character sequence,

ok

> +contained in a null-padded fixed-width buffer,

ok

>  into a destination string.
>  The programmer is responsible for allocating a buffer large enough.
>  It returns a pointer suitable for chaining.
> @@ -470,7 +470,7 @@ since the size of the original character sequence is always known,
>  so it wouldn't be very useful.
>  .IP
>  This function is not provided by any library;
> -See EXAMPLES for a reference implementation.
> +see EXAMPLES for a reference implementation.

ok

>  .\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/
>  .TP
>  .BR strncat (3)
> @@ -478,8 +478,8 @@ Do not confuse this function with
>  .BR strncpy (3);
>  they are not related at all.
>  .IP
> -This function catenates the input character sequence
> -contained in a null-padded wixed-width buffer,
> +This function catenates the input character sequence,

ok

> +contained in a null-padded fixed-width buffer,

ok

>  into a destination string.
>  The programmer is responsible for allocating a buffer large enough.
>  The return value is useless.

Cheers,
Alex

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


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