DOCS: clarify how client/script names work

This isn't really clearly stated anywhere and could understandably lead
to some confusion.

2 files changed, 12 insertions, 4 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index cf4bd4c649..25f52e3c10 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -1174,7 +1174,8 @@ Input Commands that are Possibly Subject to Change
 ``script-message-to <target> [<arg1> [<arg2> [...]]]``
     Same as ``script-message``, but send it only to the client named
     ``<target>``. Each client (scripts etc.) has a unique name. For example,
-    Lua scripts can get their name via ``mp.get_script_name()``.
+    Lua scripts can get their name via ``mp.get_script_name()``. Note that
+    client names only consist of alphanumeric characters and ``_``.
 
     This command has a variable number of arguments, and cannot be used with
     named arguments.
@@ -1186,7 +1187,8 @@ Input Commands that are Possibly Subject to Change
     The argument is the name of the binding.
 
     It can optionally be prefixed with the name of the script, using ``/`` as
-    separator, e.g. ``script-binding scriptname/bindingname``.
+    separator, e.g. ``script-binding scriptname/bindingname``. Note that script
+    names only consist of alphanumeric characters and ``_``.
 
     For completeness, here is how this command works internally. The details
     could change any time. On any matching key event, ``script-message-to``
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index 3fdb0b2f42..8a8fadc40c 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -37,6 +37,12 @@ scripting backend to use for it. For Lua, it is ``.lua``. If the extension is
 not recognized, an error is printed. (If an error happens, the extension is
 either mistyped, or the backend was not compiled into your mpv binary.)
 
+mpv internally loads the script's name by stripping the ``.lua`` extension and
+replacing all nonalphanumeric characters with ``_``. E.g., ``my-tools.lua``
+becomes ``my_tools``. If there are several scripts with the same name, it is
+made unique by appending a number. This is the name returned by
+``mp.get_script_name()``.
+
 Entries with ``.disable`` extension are always ignored.
 
 If a script is a directory (either if a directory is passed to ``--script``,
@@ -500,11 +506,11 @@ The ``mp`` module is preloaded, although it can be loaded manually with
     Return the name of the current script. The name is usually made of the
     filename of the script, with directory and file extension removed. If
     there are several scripts which would have the same name, it's made unique
-    by appending a number.
+    by appending a number. Any nonalphanumeric characters are replaced with ``_``.
 
     .. admonition:: Example
 
-        The script ``/path/to/fooscript.lua`` becomes ``fooscript``.
+        The script ``/path/to/foo-script.lua`` becomes ``foo_script``.
 
 ``mp.get_script_directory()``
     Return the directory if this is a script packaged as directory (see