Re: [PATCH] string_copying.7: tfix

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

Hi Alex,

At 2023-07-28T23:31:10+0200, Alejandro Colomar wrote:
> (CC += Branden)

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

> On 2023-07-28 20:41, Lennart Jablonka wrote:
> >  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.

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.

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

> >  .\" ----- 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)

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.

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

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

[duplicates of the foregoing cases snipped]

Regards,
Branden

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