From 3441fd6e04b7735d42b36f9cb2390a3d453c2bfd Mon Sep 17 00:00:00 2001
From: Zughy <63455151+Zughy@users.noreply.github.com>
Date: Wed, 28 Aug 2024 15:37:43 +0200
Subject: [PATCH] Menu docs: clarify that image paths must be escaped to
 correctly render on Windows (#15072)

---
 doc/menu_lua_api.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/menu_lua_api.md b/doc/menu_lua_api.md
index 8f945052c..df14b859d 100644
--- a/doc/menu_lua_api.md
+++ b/doc/menu_lua_api.md
@@ -8,6 +8,15 @@ The main menu is defined as a formspec by Lua in `builtin/mainmenu/`
 Description of formspec language to show your menu is in `lua_api.md`
 
 
+Images and 3D models
+------
+
+Directory delimiters change according to the OS (e.g. on Unix-like systems
+is `/`, on Windows is `\`). When putting an image or a 3D model inside a formspec,
+be sure to sanitize it first with `core.formspec_escape(img)`; otherwise,
+any resource located in a subpath won't be displayed on OSs using `\` as delimiter.
+
+
 Callbacks
 ---------
 
@@ -62,6 +71,12 @@ Functions
 Filesystem
 ----------
 
+To access specific subpaths, use `DIR_DELIM` as a directory delimiter instead
+of manually putting one, as different OSs use different delimiters. E.g.
+```lua
+"my" .. DIR_DELIM .. "custom" .. DIR_DELIM .. "path" -- and not my/custom/path
+```
+
 * `core.get_builtin_path()`
   * returns path to builtin root
 * `core.create_dir(absolute_path)` (possible in async calls)