📝 docs: name the actor across the factor and override prose (#4058)

A second wording pass, over the prose that #4057 did not reach. That
means the explanation, how-to, tutorial and reference text from the
factor and override work, plus the changelog entries already released.

The same fault runs through it. A variable sidesteps a problem, a value
goes through a pass, an override carries a string, an environment picks
a label. tox does each of those things, or you do, and the sentences now
name whichever it is.

Smaller edits alongside. A cleft opener, `which is what makes`, states
its point outright. `carries` and `takes` settle on one word per idea.
`a name that no longer tells the whole story` says what it fails to
record.

Two entries from other contributors changed as well, since the release
notes read as one voice. A vague `Improve` became `Declare`, and `can
now carry` became `now takes`.

No claim changes. Sphinx builds with warnings as errors and the docs
suite executes the examples.

Author: gaborbernat

docs/changelog.rst

@@ -29,8 +29,8 @@ Improved documentation - 4.61.2
 Contributor-facing changes - 4.61.2
 ===================================
 
-- Improve license metadata (PEP 639), add ``license-files`` and remove license classifier in ``pyproject.toml`` - by
-  :user:`mwtoews`. (:issue:`4052`)
+- Declare license metadata per PEP 639, adding ``license-files`` and dropping the license classifier in
+  ``pyproject.toml`` - by :user:`mwtoews`. (:issue:`4052`)
 
 **********************
  v4.61.1 (2026-08-28)
@@ -39,13 +39,13 @@ Contributor-facing changes - 4.61.2
 Bug fixes - 4.61.1
 ==================
 
-- Declare ``prefix`` inside the labeled factor group's ``not`` clause of the generated JSON Schema, so the published
-  schema compiles under the strict mode SchemaStore validates with - by :user:`gaborbernat`. (:issue:`4051`)
+- Publish a JSON Schema that compiles under SchemaStore's validator again, so editors pick up the configuration keys
+  added since 4.56 - by :user:`gaborbernat`. (:issue:`4051`)
 
 Contributor-facing changes - 4.61.1
 ===================================
 
-- Check tox's JSON Schema against SchemaStore's own validator on every pull request that touches it, and before the
+- Check tox's JSON Schema with SchemaStore's own validator on every pull request that changes it, and again before the
   release sync opens a pull request there - by :user:`gaborbernat`. (:issue:`4051`)
 
 **********************
@@ -58,7 +58,7 @@ Features - 4.61.0
 - A labeled factor group can now declare a ``default`` for ``{factor:label}`` to fall back on when no factor of that
   group is active in the environment name. Setting ``TOX_FACTOR_<label>`` resolves that label to a given value for a
   single run - by :user:`gaborbernat`. (:issue:`4045`)
-- A factor range can now carry a label by nesting it under one, as in ``factors = [{ py_version = { prefix = "3.", start
+- A factor range now takes a label when you nest it under one, as in ``factors = [{ py_version = { prefix = "3.", start
   = 12, stop = 14 } }]``, which makes ``{factor:py_version}`` available for ranges - by :user:`gaborbernat`.
   (:issue:`4046`)
 

docs/explanation.rst

@@ -345,25 +345,25 @@ have labeled one shape and left the other out. Nesting covers both with one rule
 and the value describes its factors. Adding a shape later means describing another value, not teaching every earlier
 shape one more key.
 
-A labeled factor value is part of the environment name, which is what makes ``tox run -e test-3.14-django50`` mean one
-thing. That leaves no way to name a version the matrix does not list on the command line, since ``>=4.2,<4.3`` cannot
-serve as a factor. ``TOX_FACTOR_<label>`` sidesteps that by leaving the name alone. The run goes through the environment
-the matrix generated, and only ``{factor:label}`` resolves elsewhere. The cost is a name that no longer tells the whole
-story, so the override suits a one-off check rather than a recorded configuration.
+A labeled factor value is part of the environment name, so ``tox run -e test-3.14-django50`` means one thing. That
+leaves no way to name a version the matrix does not list on the command line, since ``>=4.2,<4.3`` cannot be a factor.
+Set ``TOX_FACTOR_<label>`` instead, which leaves the name alone. tox runs the environment the matrix generated, and only
+``{factor:label}`` resolves elsewhere. The cost is a name that no longer records everything about the run, so the
+override suits a one-off check rather than a recorded configuration.
 
 For the configuration reference, see :ref:`env-base-templates`. For practical recipes, see :ref:`howto_env_base_matrix`.
 
 Overrides and substitution
 ==========================
 
-An override arrives as one command line string, whatever the configuration file format, so tox converts it with the ini
-string rules rather than the TOML ones. That is why ``-x env_run_base.commands=pytest tests`` works in a TOML project
-even though the file itself spells commands as a list of lists.
+tox receives an override as one command line string, whatever the configuration file format, so it converts the value
+with the ini string rules rather than the TOML ones. That is why ``-x env_run_base.commands=pytest tests`` works in a
+TOML project even though the file itself spells commands as a list of lists.
 
-The value still goes through the substitution pass belonging to the loader it overrides, which is what lets
-``{posargs}`` and ``{env:VAR}`` resolve inside it. Skipping that pass would make an override the one place in tox where
-a ``{...}`` reference means nothing, and a command overridden for a single run would stop forwarding the arguments given
-to it with no sign that it had.
+tox still runs the value through the substitution pass of the loader it overrides, so ``{posargs}`` and ``{env:VAR}``
+resolve inside it. Skipping that pass would make an override the one place in tox where a ``{...}`` reference means
+nothing, and a command overridden for a single run would stop forwarding the arguments given to it with no sign that it
+had.
 
 .. _work-dir-placement:
 

docs/how-to/usage.rst

@@ -191,7 +191,7 @@ location can be changed via the ``TOX_CONFIG_FILE`` environment variable.
     # Force editable install for a specific environment
     tox run -e 3.13 -x "testenv:3.13.package=editable"
 
-An override value takes substitutions, so it can reach the same values the configuration file can:
+tox substitutes into an override value, so it reaches the same values a configuration file can:
 
 .. code-block:: bash
 
@@ -1171,7 +1171,7 @@ To override a specific generated environment, add an explicit ``[env.NAME]`` sec
 
 The inheritance chain is: ``[env.{name}]`` > ``[env_base.{template}]`` > ``[env_run_base]``.
 
-Nest a group under a name to label it, so ``{factor:label}`` reaches the value the current environment picked. Both
+Nest a group under a name to label it, so ``{factor:label}`` resolves to the value in the current environment name. Both
 lists and range dicts take a label:
 
 .. code-block:: toml

docs/reference/config.rst

@@ -239,7 +239,7 @@ labeled group is an active factor in the current environment. Every factor group
 For ``sync-oci-pw``, the description resolves to ``Sync oci artifacts to pw`` and the command receives ``--ecosystem
 oci``.
 
-A range dict carries a label when you nest it under one:
+A range dict takes a label when you nest it under one:
 
 .. code-block:: toml
 
@@ -2366,7 +2366,7 @@ An override value goes through the same substitution pass as a value written in
 
     $ tox -x env_run_base.commands='pytest {posargs:tests}' -e py -- -k slow
 
-This runs ``pytest -k slow``. Overrides carry a command line string whatever the configuration file format, so the ini
+This runs ``pytest -k slow``. An override is a command line string whatever the configuration file format, so the ini
 spelling of a substitution applies in a TOML project as well.
 
 Overrides propagate through references

docs/tutorial/getting-started.rst

@@ -212,8 +212,8 @@ environments from factor combinations:
 This generates ``test-3.13`` and ``test-3.14``, each inheriting deps and commands from the template. The template itself
 inherits from ``env_run_base``, so global defaults still apply.
 
-Ranges save spelling out every version, and nesting one under a name lets the rest of the section refer back to
-whichever value the environment picked:
+Ranges save spelling out every version, and nesting one under a name lets the rest of the section refer to the value in
+the environment name:
 
 .. code-block:: toml
 
@@ -223,7 +223,7 @@ whichever value the environment picked:
     commands = [["pytest"]]
     description = "run the tests under Python {factor:py_version}"
 
-A group can also name the value to assume when an environment carries none of its factors, which saves repeating a
+A group can also name the value to assume when an environment contains none of its factors, which saves repeating a
 fallback at every mention. To check one run against a version the matrix does not list, set ``TOX_FACTOR_py_version``
 for that run.