diff --git a/docs/changelog/1051.bugfix.rst b/docs/changelog/1051.bugfix.rst
index 398f1cbec..ee9f8cdb4 100644
--- a/docs/changelog/1051.bugfix.rst
+++ b/docs/changelog/1051.bugfix.rst
@@ -1,4 +1,3 @@
-Do the same transformation to egg_info dirs that pkg_resources does. This makes
-it possible for hyphenated names to use the develop-inst-noop optimization (cf.
-#910), which previously only worked with non-hyphenated egg names - by
-:user:`hashbrowncipher`.
+Do the same transformation to egg_info dirs that pkg_resources does.
+This makes it possible for hyphenated names to use the develop-inst-noop optimization (cf. 910), which previously only worked with non-hyphenated egg names - by
+:user:`hashbrowncipher`
diff --git a/docs/changelog/437.doc.rst b/docs/changelog/437.doc.rst
new file mode 100644
index 000000000..bd9ed08ef
--- /dev/null
+++ b/docs/changelog/437.doc.rst
@@ -0,0 +1 @@
+document substitutions with additional content starting with a space cannot be alone on a line inside the ini file - by :user:`gaborbernat`
diff --git a/docs/config.rst b/docs/config.rst
index 720280667..a886dab1b 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -499,6 +499,14 @@ You can escape curly braces with the ``\`` character if you need them, for examp
 
     commands = echo "\{posargs\}" = {posargs}
 
+
+Note some substitutions (e.g. ``posargs``, ``env``) may have addition values attached to it,
+via the ``:`` character (e.g. ``posargs`` - default value, ``env`` - key).
+Such substitutions cannot have a space after the ``:`` character
+(e.g. ``{posargs: magic}`` while being at the start of a line
+inside the ini configuration (this would be parsed as factorial ``{posargs``,
+having value magic).
+
 Globally available substitutions
 ++++++++++++++++++++++++++++++++