Add details to specification and explain use w/ unknown features

Author: zklaus

peps/pep-0780.rst

@@ -191,11 +191,12 @@ expressed as a frozen set of strings of the form ``f"{name}::{value}"``, where
 ``name`` is the name of the field and ``value`` is the string representation of
 its value.
 
+The ``sys_abi_info`` environment variable
+'''''''''''''''''''''''''''''''''''''''''
 To do this, we need to extend the grammar laid out in :pep:`508` and maintained
-in the :ref:`packaging:dependency-specifiers` and document the possible values.
-
-The grammar is extended to include the ``sys_abi_info`` marker variable by
-augmenting the definition of ``env_var`` as follows::
+in the :ref:`packaging:dependency-specifiers` and document the possible values,
+to include the ``sys_abi_info`` marker variable by augmenting the definition of
+``env_var`` as follows::
 
     env_var       = ('python_version' | 'python_full_version' |
                      'os_name' | 'sys_platform' | 'platform_release' |
@@ -206,6 +207,10 @@ augmenting the definition of ``env_var`` as follows::
                      'extra' | 'extras' | 'dependency_groups' # ONLY when defined by a containing layer
                      )
 
+This makes ``sys_abi_info`` available as a variable in marker expressions.
+
+The Values of ``sys_abi_info``
+''''''''''''''''''''''''''''''
 Like the grammar, also the overview table of environment markers in
 :ref:`packaging:dependency-specifiers` is augmented to add the following row:
 
@@ -225,6 +230,31 @@ With these additions, ABI features can be used in dependency specifications via
 the ``in`` operator to test for the presence of a feature, or the ``not in``
 operator to test for the absence of a feature.
 
+This allows for marker expressions such as::
+
+    "free_threaded::True" in sys_abi_info
+    "pointer_bits::32" not in sys_abi_info and "debug::True" in sys_abi_info
+
+Note that this is forward compatible in the sense that future additions to the
+set of ABI features will not be in conflict with the grammar, such that tools
+encountering unknown ABI features in a dependency specification will naturally
+evaluate the test as false. This empowers package authors to decide on the
+default resolution in this case. For example, a package author may decide to
+require a dependency only if an ABI feature is present, by using a presence
+test like ``"new_feature::True" in sys_abi_info``, which will evaluate to
+false on current interpreters that do not support the new feature, or an
+absence test like ``"new_feature::False" not in sys_abi_info``, which will
+evaluate to true on current interpreters.
+
+While covering all ABI features specified at the moment, this mechanism is only
+meaningfully applicable where the ABI feature is unambiguously representable as
+a string. Currently, all ABI features are either booleans, integers, or
+strings, which all satisfy this requirement.
+
+Should the future reveal a need for ABI features that are not unambiguously
+represented as strings, like floating point numbers or more complex data
+structures, this PEP would need to be revisited to address those.
+
 Examples
 ========