Updates from my own PR review

Author: ncoghlan

source/specifications/core-metadata.rst

@@ -574,14 +574,14 @@ The format of a requirement string contains from one to four parts:
 * An environment marker after a semicolon. This means that the
   requirement is only needed in the specified conditions.
 
-See :ref:`dependency-specifiers` for full details of the allowed format.
-
 The project names should correspond to names as found
 on the `Python Package Index`_.
 
 Version specifiers must follow the rules described in
 :doc:`version-specifiers`.
 
+See :ref:`dependency-specifiers` for full details of the allowed format.
+
 Examples::
 
     Requires-Dist: pkginfo

source/specifications/dependency-specifiers.rst

@@ -243,7 +243,7 @@ The follow comparison operations are defined in the marker expression grammar:
 * ``<=`` (for example, ``python_version <= "3.10"``)
 * ``~=`` (for example, ``python_version ~= "3"``)
 * ``===`` (for example, ``implementation_version === "not.a.valid.version"``)
-* ``in`` (for example, ``"gui" in extras``)
+* ``in`` (for example, ``"gui" in extras``, ``"SMP" in platform_version``)
 * ``not in`` (for example, ``"dev" not in dependency_groups``)
 
 For ``String`` fields, ``==``, ``!=``, ``in``, and ``not in`` are defined as
@@ -272,12 +272,17 @@ emit an error if the user supplied constant cannot be parsed as a valid version
 specifier, while locking and installation tools MAY either emit an error or else
 fall back to ``String`` field comparison logic if either the marker field value
 or the user supplied constant cannot be parsed as a valid version specifier.
+Note that ``in`` and ``not in`` containment checks are NOT valid for ``Version``
+fields.
 
 For ``Version | String`` fields, comparison operations are defined as they are
 for ``Version`` fields. However, there is no expectation that the parsing of
 the marker field value or the user supplied constant as a valid version will
 succeed, so tools MUST fall back to processing the field as a ``String`` field.
 Alternatively, tools MAY unconditionally treat such fields as ``String`` fields.
+Accordingly, comparisons that rely on these fields being processed as
+``Version`` field SHOULD NOT be used in environment markers published to public
+index servers, but they may be appropriate in more constrained environments.
 
 Composing marker expressions
 ''''''''''''''''''''''''''''
@@ -286,8 +291,15 @@ More complex marker expressions may be composed using the ``and`` and ``or``
 logical operators. Parentheses may be used as necessary to control operand
 precedence (with all comparison operations having a higher precedence).
 
+For example::
+
+    sys_platform == "ios" or sys_platform == "darwin"
+    sys_platform == "linux" and "SMP" in platform_version
+    sys_platform == "darwin" and platform_version >= "12"
+
 Python's comparison chaining (such as ``3.4 < python_version < 3.9``) is NOT
-supported in environment markers.
+supported in environment markers (such expressions must instead be written out
+as two separate comparisons joined by ``and``).
 
 User supplied constants
 '''''''''''''''''''''''

source/specifications/entry-points.rst

@@ -106,8 +106,7 @@ Within a value, readers must accept and ignore spaces (including multiple
 consecutive spaces) before or after the colon, between the object reference and
 the left square bracket, between the extra names and the square brackets and
 colons delimiting them, and after the right square bracket. The syntax for
-extras is formally specified as part of :pep:`508` (as ``extras``) and
-restrictions on values specified in :pep:`685`.
+extras is formally specified in :ref:`dependency-specifiers`.
 For tools writing the file, it is recommended only to insert a space between the
 object reference and the left square bracket.
 

source/specifications/pyproject-toml.rst

@@ -449,36 +449,57 @@ be ambiguous in the face of ``[project.scripts]`` and
 
 
 .. _pyproject-toml-dependencies:
-.. _pyproject-toml-optional-dependencies:
 
-``dependencies``/``optional-dependencies``
-------------------------------------------
+``dependencies``
+----------------
 
-- TOML_ type: Array of :ref:`dependency-specifiers` strings (``dependencies``),
-  and a table with values of arrays of :ref:`dependency-specifiers` strings
-  (``optional-dependencies``)
+- TOML_ type: Array of :ref:`dependency specifier <dependency-specifiers>`
+  strings (``dependencies``)
 - Corresponding :ref:`core metadata <core-metadata>` field:
-  :ref:`Requires-Dist <core-metadata-requires-dist>` and
-  :ref:`Provides-Extra <core-metadata-provides-extra>`
+  :ref:`Requires-Dist <core-metadata-requires-dist>`
 
-The (optional) dependencies of the project.
+``dependencies`` lists the expected dependencies of the project as an
+array of strings.
 
-For ``dependencies``, it is a key whose value is an array of strings.
 Each string represents a dependency of the project and MUST be
-formatted as a valid :ref:`dependency-specifiers` string.
+formatted as a valid :ref:`dependency specifier <dependency-specifiers>`.
+
 Each string maps directly to a
 :ref:`Requires-Dist <core-metadata-requires-dist>` entry.
 
-For ``optional-dependencies``, it is a table where each key specifies
-an extra and whose value is an array of strings. The strings of the
-arrays must be valid :ref:`dependency-specifiers` strings.
+Dependencies listed in this array are always considered
+for installation, but may still contain environment markers that cause them
+to be skipped in some environments.
+
+
+.. _pyproject-toml-optional-dependencies:
+
+``optional-dependencies``
+-------------------------
+
+- TOML_ type: table with string keys mapping to arrays of
+  :ref:`dependency specifier <dependency-specifiers>` strings (``optional-dependencies``)
+- Corresponding :ref:`core metadata <core-metadata>` fields:
+  :ref:`Requires-Dist <core-metadata-requires-dist>` and
+  :ref:`Provides-Extra <core-metadata-provides-extra>`
+
+``optional-dependencies`` is a table where each key specifies
+an extra and whose value is an array of strings using the same format as the
+``dependencies`` array (the strings in the
+arrays must be valid :ref:`dependency specifiers <dependency-specifiers>`).
+
 The keys MUST be valid values
 for :ref:`Provides-Extra <core-metadata-provides-extra>`. Each value
 in the array thus becomes a corresponding
 :ref:`Requires-Dist <core-metadata-requires-dist>` entry for the
 matching :ref:`Provides-Extra <core-metadata-provides-extra>`
 metadata.
 
+The optionality of these dependencies is recorded by modifying the environment
+marker clause on the related ``Requires-Dist`` entries to check the extra name.
+Optional dependencies are thus only considered for installation if installation
+if the associated extra name is requested.
+
 
 .. _pyproject-toml-import-names: