From bc3b50331efae4b2d1e97662f01b7d61d2f19372 Mon Sep 17 00:00:00 2001
From: syimyuzya <syimyuzya@gmail.com>
Date: Sat, 4 Dec 2021 15:21:30 +0800
Subject: [PATCH] Document `getglyph` & note about formspec escaping

---
 font_api/API.md       | 7 +++++--
 font_api/font.lua     | 3 +++
 font_api/registry.lua | 8 +++++++-
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/font_api/API.md b/font_api/API.md
index 80b1121..c77085f 100644
--- a/font_api/API.md
+++ b/font_api/API.md
@@ -105,6 +105,7 @@ Font definition table used by **font_api.register_font** and **font\_api.Font:ne
 * `margintop` (optional): Margin (in texture pixels) added on top of each char texture.
 * `marginbottom` (optional): Margin (in texture pixels) added at bottom of each char texture.
 * `linespacing` (optional): Spacing (in texture pixels) between each lines.
+* `getglyph` (optional, advanced usage): Function that takes a Unicode codepoint (number) and returns a custom texture string for the glyph instead of the default `font_{name}_{codepoint}.png` (see *Additional Requirements* below). The texture string can contain filters like `^[sheet` and will be properly escaped when combined.
 
 `margintop`, `marginbottom` and `linespacing` can be negative numbers (default 0) and are to be used to adjust various font styles to each other.
 
@@ -118,7 +119,7 @@ Font attributes effects on several lines:\
 
 Font must have a char 0 which will be used to display any unknown char.
 
-All textures corresponding to the indexes in widths array should be present in textures directory with a name matching the pattern :
+All textures corresponding to the indexes in widths array should be present in textures directory with a name matching the pattern (unless using a custom `getglyph` function):
 
 > font\_**{font_name}**_**{utf_code}**.png
 
@@ -189,7 +190,7 @@ Returns line(s) height. Takes care of top and bottom margins and line spacing.
 Returns the width of a text line. Beware, if line contains any new line char, they are ignored.
   * `line`: Line of text which the width will be computed.
 
-### font:renter(text, texturew, textureh, style)
+### font:render(text, texturew, textureh, style)
 Builds texture for a multiline colored text.
   * `text`: Text to be rendered.
   * `texturew`: Width of the texture (extra text will be truncated).
@@ -199,3 +200,5 @@ Builds texture for a multiline colored text.
     - `halign`: Horizontal text align: "left"/"center"/"right" (default "center")
     - `valign`: Vertical text align: "top"/"middle"/"bottom" (default "middle")
     - `color`: Color of the text (default black)
+    
+Note: When used in formspec, be sure to **escape** the texture string with `minetest.formspec_escape`.
diff --git a/font_api/font.lua b/font_api/font.lua
index 6a99334..b81e10e 100644
--- a/font_api/font.lua
+++ b/font_api/font.lua
@@ -201,6 +201,9 @@ function Font:make_text_texture(text, texturew, textureh, maxlines,
 end
 
 --- Render text with the font in a view
+-- Note: When used in formspec, be sure to escape the texture string with
+-- `minetest.formspec_escape`.
+--
 -- @param text Text to be rendered
 -- @param texturew Width (in pixels) of the texture (extra text will be truncated)
 -- @param textureh Height (in pixels) of the texture (extra text will be truncated)
diff --git a/font_api/registry.lua b/font_api/registry.lua
index e183675..3a72ca1 100644
--- a/font_api/registry.lua
+++ b/font_api/registry.lua
@@ -127,8 +127,14 @@ end
 -- UTF codepoints
 -- @key margintop (optional) Margin (in texture pixels) added on top of each
 -- char texture.
--- @key marginbottom (optional) dded at bottom of each char texture.
+-- @key marginbottom (optional) Margin (in texture pixels) added at bottom of
+-- each char texture.
 -- @key linespacing (optional) Spacing (in texture pixels) between each lines.
+-- @key getglyph (optional, advanced usage) Function that takes a Unicode
+-- codepoint (number) and returns a custom texture string for the glyph instead
+-- of the default `font_{name}_{codepoint}.png`. The texture string can contain
+-- filters like `^[sheet` and will be properly escaped when combined.
+--
 -- margintop, marginbottom and linespacing can be negative numbers (default 0)
 -- and are to be used to adjust various font styles to each other.