Re: [PATCH v3 1/1] strcpy.3: Rewrite page to document all string-copying functions

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

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

Hi Doug,

On 12/14/22 17:36, Alejandro Colomar wrote:
> On 12/14/22 17:22, Douglas McIlroy wrote:
>>> chain copy
>>
>> This term is never overtly defined. The definition might be inferred
>> from, "To chain copy
>> functions, they need to return a pointer to the end", but the
>> problematic grammar of the
>> sentence diverts attention from its content.
> 
> Okay, I'll try to improve the wording in that paragraph; indeed that subsection 
> intended to define the "chain copy" term.
> 
>>

I'll hold on sending v5 to see if there is more feedback from others, but here's 
what I have for documenting the chain term:


@@ -202,15 +192,36 @@ .SS Terms (and abbreviations)
  It is used as a sentinel value,
  to be able to truncate strings or character sequences
  instead of overrunning the containing buffer.
-.\" ----- DESCRIPTION :: Copy, concatenate, and chain-copy ------------/
-.SS Copy, concatenate, and chain-copy
+.\" ----- DESCRIPTION :: Terms (and abbreviations) :: copy ------------/
+.TP
+.I copy
+This term is used when
+the writing starts at the first element pointed to by
+.IR dst .
+.\" ----- DESCRIPTION :: Terms (and abbreviations) :: catenate --------/
+.TP
+.I catenate
+This term is used when
+a function first finds the terminating null byte in
+.IR dst ,
+and then starts writing at that position.
+.\" ----- DESCRIPTION :: Terms (and abbreviations) :: chain -----------/
+.TP
+.I chain
+This term is used when
+it's the programmer who provides a pointer to the
+.IR end ,
+and the function starts writing at that location.
+.IR dst .
+.\" ----- DESCRIPTION :: Copy, catenate, and chain-copy ---------------/
+.SS Copy, catenate, and chain-copy
  Originally,
-there was a distinction between functions that copy and those that concatenate.
+there was a distinction between functions that copy and those that catenate.
  However, newer functions that copy while allowing chaining
  cover both use cases with a single API.
  They are also algorithmically faster,
  since they don't need to search for the end of the existing string.
-However, functions that concatenate have a much simpler use,
+However, functions that catenate have a much simpler use,
  so if performance is not important,
  it can make sense to use them for improving readability.
  .PP



Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

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