From 4711e408143b98e6b02f78522f14ef97de0ff71d Mon Sep 17 00:00:00 2001
From: nanahi <130121847+na-na-hi@users.noreply.github.com>
Date: Sat, 14 Dec 2024 11:36:24 -0500
Subject: [PATCH] DOCS/man/input.rst: clarify shift modifier behavior

When shift modifier is used with text key names, it is usually
silently ignored, except for ASCII key names, which can be
confusing. Document it clearly.
---
 DOCS/man/input.rst | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 286c36324c..05679fd2e6 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -97,11 +97,24 @@ All key names can be combined with the modifiers ``Shift``, ``Ctrl``, ``Alt``,
 ``Meta``. They must be prefixed to the actual key name, where each modifier
 is followed by a ``+`` (for example ``ctrl+q``).
 
-The ``Shift`` modifier requires some attention. For instance ``Shift+2`` should
-usually be specified as key-name ``@`` at ``input.conf``, and similarly the
-combination ``Alt+Shift+2`` is usually ``Alt+@``, etc. Special key names like
-``Shift+LEFT`` work as expected. If in doubt - use ``--input-test`` to check
-how a key/combination is seen by mpv.
+.. note::
+
+    The ``Shift`` modifier requires some attention. In general, when the
+    ``Shift`` modifier is combined with a key which produces text, the actual
+    produced text key name when shift is pressed should be used.
+
+    For instance, on the US keyboard layout, ``Shift+2`` should usually be
+    specified as key-name ``@`` at ``input.conf``, and similarly the
+    combination ``Alt+Shift+2`` is usually ``Alt+@``, etc.
+
+    In general, the ``Shift`` modifier, when specified with text key names,
+    is ignored: for instance, mpv interprets ``Shift+2`` as ``2``.
+    The only exceptions are ASCII letters, which are normalized by mpv.
+    For example, ``Shift+a`` is interpreted as ``A``.
+
+    Special key names like ``Shift+LEFT`` work as expected.
+    If in doubt - use ``--input-test`` to check how a key/combination is seen
+    by mpv.
 
 Symbolic key names and modifier names are case-insensitive. Unicode key names
 are case-sensitive because input bindings typically respect the shift key.