Provide more documentation on the SETUPTOOLS_SCM_PRETEND_VERSION_FOR_ variable

Author: pelson

CHANGELOG.rst

@@ -15,6 +15,7 @@ breaking
   and where hiding dirty states that are now explicitly dirty
 * depend on later importlib for the full selectable api
 * move setuptools integration code to private sub-package
+* use normalized dist names for the SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${DIST_NAME}
 
 features
 --------

README.rst

@@ -262,7 +262,7 @@ Note that running this Dockerfile requires docker with BuildKit enabled
 `[docs] <https://github.com/moby/buildkit/blob/v0.8.3/frontend/dockerfile/docs/syntax.md>`_.
 
 To avoid BuildKit and mounting of the .git folder altogether, one can also pass the desired
-version as a build argument. Note that ``SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${UPPERCASED_DIST_NAME}``
+version as a build argument. Note that ``SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${NORMALIZED_DIST_NAME}``
 is preferred over ``SETUPTOOLS_SCM_PRETEND_VERSION``.
 
 
@@ -500,12 +500,15 @@ Environment variables
 :SETUPTOOLS_SCM_PRETEND_VERSION:
     when defined and not empty,
     its used as the primary source for the version number
-    in which case it will be a unparsed string
+    in which case it will be an unparsed string
 
-:SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${UPPERCASED_DIST_NAME}:
+:SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${NORMALIZED_DIST_NAME}:
     when defined and not empty,
     its used as the primary source for the version number
-    in which case it will be a unparsed string
+    in which case it will be an unparsed string
+
+    the dist name normalization follows adapted PEP-503 semantics, with one or
+    more of ".-_" being replaced by a single "_", and the name being upper-cased
 
     it takes precedence over ``SETUPTOOLS_SCM_PRETEND_VERSION``