Re: [PATCH] string_copying.7: tfix

[Alejandro Colomar <alx@kernel.org>]

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

Hi Lennart,

(CC += Branden)

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

In this case, man-pages(7) advises to not hyphenate:

   Hyphenation with multi, non, pre, re, sub, and so on
       The general tendency in modern English is not to hyphenate  af‐
       ter prefixes such as "multi", "non", "pre", "re", "sub", and so
       on.   Manual pages should generally follow this rule when these
       prefixes are used in natural English constructions with  simple
       suffixes.   The  following list gives some examples of the pre‐
       ferred forms:

              [...]
              subcomponent
              subdirectory
              subsystem

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

Is nor incorrect here?  I'm not a native English speaker and would like
to understand why it is incorrect.

>  .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
>  from a character sequence that just fits the destination buffer;

I guess it's ok (to me they both sound good)

>  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,

I believe the below is like a parenthetical, which is why I put it
between commas; isn't it?  Although your version also looks good.

> +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,

Same.

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

Heh, my text is wixed!

>  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,
> +contained in a null-padded fixed-width buffer,

And same.

Thanks,
Alex

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

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


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