Standardise key–value pair usage and argument terminology across documentation - #7495

@JordanHendersonMusic

I have reviewed most of the help files related to key–value pairs and keyword arguments.
The expression keyword arguments is highly context‑dependent and, in some cases, ambiguous.

Up to SC 3.13, this term appears to have referred exclusively to the keyword‑argument syntax used in function calls.
With SC 3.14, however, arbitrary keyword arguments are now permitted after variable arguments.
Because of this change, it has become necessary to distinguish clearly between:

• keyword arguments used in function‑call syntax, and

• keyword arguments belonging to the third group of function parameters.

This PR aims to resolve the resulting ambiguity and standardise the terminology across the documentation.

Unify terminology for keyword arguments and function argument categories across documentation

The term “keyword arguments” has become ambiguous in the documentation due to the recent introduction of “arbitrary keyword arguments” (|... args, kwargs|) in Function definitions.

Historically, The SuperCollider Book and earlier documentation used “keyword arguments” exclusively to mean keyword argument calls (message‑passing syntax), without ambiguity.

This commit standardises terminology across all relevant documents to remove confusion and ensure consistent usage.

• The overloaded term “keyword arguments” is now split into:

  • “keyword argument calls” (message‑passing syntax: f.(x: 1, y: 2))
  • “arbitrary keyword arguments” (Function definition: |... args, kwargs|)

• Likewise:

  • “positional arguments” has been clarified as “positional argument calls”

• The terminology for function arguments has been standardised as follows:

  • declared arguments
  • variable arguments
    • variadic positional arguments
    • arbitrary keyword arguments

All occurrences found in the documentation have been updated for consistency.

If the community prefers alternative terminology, the following substitutions remain entirely possible:

• “keyword argument calls” → “keyword arguments”
• “positional argument calls” → “positional arguments”
• “declared arguments”, “variadic positional arguments”, and “arbitrary keyword arguments” may be replaced with any agreed‑upon terms.

This commit provides a consistent baseline from which such future adjustments may be made.

“keyword argument calls”

This term seems a little off to me. Perhaps just 'keyword arguments'?

Then at the call sight we have positional arguments and keyword arguments.

“arbitrary keyword arguments”

I think this one should be 'variadic keyword arguments'.

“keyword argument calls”

This term seems a little off to me. Perhaps just 'keyword arguments'?
Then at the call sight we have positional arguments and keyword arguments.

OK, I can revert it, and it is better not to change the term has used for a long time.

“arbitrary keyword arguments”

I think this one should be 'variadic keyword arguments'.

The term “arbitrary keyword arguments” is introduced by @telephon in the news in SC3.14:

• supercollider/HelpSource/Guides/News-3_14.schelp

  Line 10 in 3554631

  ## Sclang functions now support collecting arbitrary keyword arguments via code:: { |...args, kwargs| kwargs }. ::

• supercollider/HelpSource/Guides/News-3_14.schelp

  Line 48 in 3554631

  So far, additional function and method arguments could be captured into an array via the syntax: code:: f = { |a, b ... args| args }; f.(1,2,3,4) // returns [3, 4] ::. It was not possible to use other keywords than those explicitly given (here code:: a :: and code:: b ::) Now we can also capture arbitrary keyword arguments, via the syntax: code:: f = { |a, b ... args, kwargs| kwargs }; f.(x:3, y:4) // returns [\x, 3, \y, 4] ::.

If @telephon does not object, in this PR’s last status:

• revert:

  • currently: “keyword argument calls” → will be: “keyword arguments”
  • currently: “positional argument calls” → will be: “positional arguments”

• change:

  • currently: “arbitrary keyword arguments” → will be: “variadic keyword arguments”

• keep:

  • “variadic positional arguments”

I will not touch the supercollider/HelpSource/Guides/News-3_14.schelp.

Otherwise, in the final status of this PR, we could:

• revert:
  • currently: “keyword argument calls” → will be: “keyword arguments”
  • currently: “positional argument calls” → will be: “positional arguments”
• change:
  • currently: “variadic positional arguments” → will be: “ arbitrary positional arguments”
• keep:
  • “arbitrary keyword arguments”

The term arbitrary keyword arguments used in the SC 3.14 release notes is very clear and easy to understand. However, using only keyword arguments in the documentation can be confusing. In most programming contexts, keyword arguments are understood specifically in contrast to positional arguments in function calls, so readers may misinterpret the term.

For consistency across SC versions and to avoid ambiguity, I think continuing to use arbitrary keyword arguments would be clearer.

I agree (with using the term "arbitrary kwargs" for SC), but it's also helpful to include the reference to the wider technical term (variadic) somewhere (just once in the glossary and maybe in Function.schelp, not everywhere)

E.g., add "arbitrary kwargs" to glossary:

Arbitrary keyword arguments: Keyword arguments supplied via { | ... args, kwargs | }, where the number of keyword arguments is indefinite (variadic).

I think you mean Functions.schelp? This PR already has explanations there.

In my opinion, Glossary.schelp should include more technically oriented and SC‑specific terms.

## Variadic positional arguments || Positional arguments supplied via code::{ | ... args | }::, where the number of positional arguments is indefinite. See link::Reference/Functions#Variadic positional arguments::.

## Arbitrary keyword arguments || Keyword arguments supplied via code::{ | ... args, kwargs | }::, where the number of keyword arguments is indefinite (variadic). See link::Reference/Functions#Arbitrary Keyword Arguments::.

Let’s see what other developers say.