On 12/14/22 18:11, Alejandro Colomar wrote:
> 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 .


@@ -213,6 +213,10 @@ .SS Terms (and abbreviations)
  .IR end ,
  and the function starts writing at that location.
  .IR dst .
+The function returns a pointer to the new
+.I end
+after the call,
+so that the programmer can use it to chain such calls.
  .\" ----- DESCRIPTION :: Copy, catenate, and chain-copy ---------------/
  .SS Copy, catenate, and chain-copy
  Originally,



And this is for completeness. :)


> +.\" ----- 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/>