string_copying.7: tfix

Signed-off-by Lennart Jablonka <[email protected]>

---
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(-)

man7/string_copying.7 +0 -0

index da1fc6752..04426ef77 100644

man7/string_copying.7 +0 -0

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

Quoted 4 lines

man7/string_copying.7 +0 -0

index da1fc6752..04426ef77 100644

man7/string_copying.7 instead of · line 283

Quoted 6 lines

man7/string_copying.7 +1 -1

@@ -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:

man7/string_copying.7 instead of · line 285

Quoted 3 lines

man7/string_copying.7 +1 -1

 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.

man7/string_copying.7 is a more useful alternative to this function. · line 447

Quoted 7 lines

man7/string_copying.7 +1 -2

@@ -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.

man7/string_copying.7 is a more useful alternative to this function. · line 448

Quoted 1 line

man7/string_copying.7 +1 -0

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

Ok

Quoted 1 line

man7/string_copying.7 +0 -0

 into a destination character sequence.

(CC += Branden)

man7/string_copying.7 instead of · line 285

Quoted 3 lines

while not duplicating memory

man7/string_copying.7 +1 -1

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

Review

Quoted 2 lines

(quoted diff) +1 -1

-See EXAMPLES for a reference implementation.
+see EXAMPLES for a reference implementation.

Ok

Quoted 4 lines

.\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ .TP
.BR strlcpy (3bsd)

(quoted diff) +0 -0

@@ -427,7 +427,7 @@ isn't large enough to hold the copy,

man7/string_copying.7 isn't large enough to hold the copy, · line 431

Quoted 6 lines

man7/string_copying.7 +1 -1

 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)

man7/string_copying.7 is a more useful alternative to this function. · line 447

Quoted 3 lines

man7/string_copying.7 +1 -2

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

Review isn't large enough to hold the copy, · line 433

Quoted 1 line

(quoted diff) +1 -0

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

Ok

Quoted 1 line

into a destination character sequence.

Quoted 11 lines

man7/string_copying.7 is a more useful alternative to this function. · line 447

Quoted 7 lines

man7/string_copying.7 +1 -2

@@ -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.

Quoted 5 lines

Review is a more useful alternative to this function. · line 448

Quoted 1 line

(quoted diff) +1 -0

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

Ok

Quoted 1 line

man7/string_copying.7 +0 -0

 into a destination character sequence.

The “contained in a null-padded fixed-width buffer” indeed looks like a parenthetical (or rather, a non-restrictive participial clause—the “contained” is the participle), which is why it should be between commas. You didn’t do quite that: You put a comma after it, but not before.

This case is what I tried to explain: You set off the “into a destination character sequence” prepositional phrase (the “into” being the preposition) by a comma. You did not surround the participial clause by commas. That’s what I did.

Hi Alex,

Quoted 1 line · Alejandro Colomar

(CC += Branden)

I think I just received my grammar prescriptivist's draft notice... ;-)

Quoted 7 lines · Lennart Jablonka

man7/string_copying.7 instead of · line 285

Quoted 3 lines

while not duplicating memory

man7/string_copying.7 +1 -1

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

With the humbling caveat that you find me more persuasive than some online grammar authorities,

the foregoing suggestion is in my view a
hypercorrection. The (coordinating) conjunction "nor" is not restricted to sentences using "neither".

https://newsroom.unl.edu/announce/snr/3511/19686
https://study.com/learn/lesson/neither-nor-usage-examples-sentences.html
https://www.grammarbook.com/blog/effective-writing/using-nor-properly/

In the last, attend particularly to section "Using Nor Properly:
Interchanging with Or".

I'm a +0 on this hunk of the patch. It's correct either way.

Quoted 5 lines

Review

Quoted 3 lines

(quoted diff) +1 -1

-See EXAMPLES for a reference implementation.
+see EXAMPLES for a reference implementation.

Ok

Strong +1 here. It is volcanically nonstandard to apply sentence capitalization to an independent clause after a semicolon.

Quoted 13 lines

man7/string_copying.7 isn't large enough to hold the copy, · line 431

Quoted 11 lines

.\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ .TP
.BR strlcpy (3bsd)

man7/string_copying.7 +1 -1

@@ -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)

I think the comma arose there due to good instincts: you have a long chain of prepositional (and participial) phrases that do _not_ grow strictly narrower in scope as they proceed.

Consider:

"Due to the dense foliage, it's impossible to distinguish the man in the tree growing from the loamy soil laid down in the Cenozoic Era that I remember learning about in geology class."

This (admittedly goofy) sentence is not difficult to interpret: each phrase (after the first, "Due to", which serves as a topicalizer) modifies only the preceding one.

By contrast, the sentence in this man page is structurally complex and therefore challenging to parse.

"It's impossible to distinguish
(truncation (by the result (of the call))
from (a character sequence (that just fits
([inside] the destination
buffer))).

That's pretty tough sledding. Only semantic knowledge permits the experienced programmer to make sense of it.

The use of the comma prompts the reader that an ambiguous parse is possible, and that they should pause, as they would in speaking, to permit the modifying phrases just uttered to bind to the preceding language. Or, alternatively, the comma (or pause) is a warning that the phrase stack is being popped, cueing the reader or listener to attempt multiple parses in search of one that seems suitable.

That this exhibit took so much meta-analysis to explain is what motivates my advice: it would be better to recast the sentence until clarity is achieved.

Quoted 8 lines

man7/string_copying.7 is a more useful alternative to this function. · line 447

Quoted 4 lines

man7/string_copying.7 +1 -2

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

Quoted 5 lines

Review isn't large enough to hold the copy, · line 433

Quoted 1 line

(quoted diff) +1 -0

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

Ok

Quoted 1 line

into a destination character sequence.

I'm a +0 on this one, too. To me, it reads equivalently either way.

[duplicates of the foregoing cases snipped]

Regards,
Branden

Signed-off-by Lennart Jablonka <[email protected]>

---
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(-)

man7/string_copying.7 +0 -0

index da1fc6752..04426ef77 100644