From 6986b7abf866970ca6edf1058885974ba5a9f465 Mon Sep 17 00:00:00 2001
From: Oneric <1668471+TheOneric@users.noreply.github.com>
Date: Wed, 18 Dec 2024 23:59:47 +0100
Subject: [PATCH] Fix docs for Encoding/\fe and document \kt (#35)

* Fix docs for Encoding, \fe

* Document \kt
---
 content/en/docs/latest/ASS_Tags.md | 48 +++++++-----------------------
 content/en/docs/latest/Styles.md   | 17 ++++++-----
 2 files changed, 20 insertions(+), 45 deletions(-)

diff --git a/content/en/docs/latest/ASS_Tags.md b/content/en/docs/latest/ASS_Tags.md
index 5e0fc1440..a0f74c45d 100644
--- a/content/en/docs/latest/ASS_Tags.md
+++ b/content/en/docs/latest/ASS_Tags.md
@@ -403,41 +403,9 @@ coordinate system used for shearing is not affected by the [rotation origin]({{<
 {{</example-box>}}
 
 {{<tag-def-box title="Font encoding" id="\fe">}}\\fe<i>\<id></i>{{</tag-def-box>}}
-Set the Windows font encoding used to select the font mapping table used to
-translate Unicode codepoints to glyph indices in the font. For some fonts
-without a Unicode mapping table this might be required to get text in certain
-languages to work. For fonts that do have a Unicode mapping table, it might be
-used to pick regional variations, such as picking the correct glyph for a Han
-ideogram that is different in Simplified Chinese, Traditional Chinese,
-Japanese and Korean.
-
-Some common font encoding IDs are:
-
-- 0 - ANSI, Windows CP-1252 for Western-European languages.
-- 1 - Default, depends on the configuration of the user's system, but also
-  allows the font sub-system to dynamically pick a different mapping table in
-  some circumstances.
-- 2 - Symbol, codepoints in the 0-255 range are translated to per-font defined
-  symbol glyphs, this is used for fonts such as Wingdings.
-- 128 - Shift-JIS, used for Japanese.
-- 129 and 130, respectively Hangeul and Johab, two encoding schemes for Korean.
-- 134 - GB2312, used for Simplified Chinese.
-- 136 - BIG5, used for Traditional Chinese.
-- 162 - Turkish.
-- 163 - Vietnamese.
-- 177 - Hebrew.
-- 178 - Arabic.
-
-{{<todo>}}Is that really correct? {{</todo>}}
-
-A more complete list can be seen the [style editor]({{< relref "Styles#thestyleeditor" >}})
-dialog box.
-
-In ASS files stored in non-Unicode encodings, this tag also affects what
-codepage the text following it should be interpreted in. Aegisub doesn't
-support this use and some renderers might not support it either. It is
-recommended you do not rely on this and instead always store your files in a
-Unicode encoding. (Aegisub stores files in Unicode UTF-8 by default.)
+Overrides the `Encoding` value of the style.
+This is rarely ever useful or a good idea and should thus be avoided.
+See the [style docs]({{< relref "styles/#the-style-editor" >}}) for more details.
 
 {{<tag-def-box title="Set color" id="\c">}}
 \\c&H<i>\<bb>\<gg>\<rr></i>&
@@ -547,6 +515,7 @@ top-titles, add 4 to the number, to get mid-titles add 8 to the number:
 \\K<i>\<duration></i>
 \\kf<i>\<duration></i>
 \\ko<i>\<duration></i>
+\\kt<i>\<time></i>
 {{</tag-def-box>}}
 
 > _Please note that these tags alone only create some very specific effects
@@ -574,9 +543,12 @@ The different `\k` tags create various effects:
 - `\ko`: Similar to `\k`, except that before highlight, the border/outline of
   the syllable is removed, and appears instantly when the syllable starts.
 
-_Note: There is an additional karaoke tag, `\kt`, which is very different from
-the other ones. It is rarely useful and Aegisub does not support that tag, so
-it is not documented._
+> _Note: The `\kt` tag is not yet supported by all Aegisub-internal tools
+> and external scripts may also not properly handle it._
+
+Additionally the `\kt` tag sets the start time of the next karaoke syllable
+relative to the event’s start. Without `\kt` each syllable start is implicitly
+determined as the sum of all preceding syllable’s duration.
 
 {{<tag-def-box title="Wrap style" id="\q">}}\\q<i>\<style></i>{{</tag-def-box>}}
 Determine how line breaking is applied to the subtitle line. The following
diff --git a/content/en/docs/latest/Styles.md b/content/en/docs/latest/Styles.md
index e3bb19a42..eb54a50f8 100644
--- a/content/en/docs/latest/Styles.md
+++ b/content/en/docs/latest/Styles.md
@@ -155,13 +155,16 @@ Miscellaneous
     these are script pixels or video pixels is not well defined.
 
   Encoding:
-  : Controls which codepage is used to map codepoints to glyphs; it has
-    nothing to do with the actual text encoding of the script. This is only
-    meaningful on Windows using VSFilter, where it is used to get some old
-    (particularly Japanese) fonts without proper Unicode mappings to render
-    properly. On other systems and renderers, Freetype2 provides the proper
-    mappings. If you didn't understand a word of the above, pretend this
-    setting doesn't exist, as it is rarely important.
+  : Limits font selection to only those fonts declaring support for the set
+    legacy Windows codepage. All valid values are listed by Microsoft in
+    [this page](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-wmf/0d0b32ac-a836-4bd2-a112-b6000a1b4fc9).
+    If it is set to `1` (default charset) font selection is unlimited.<br/>
+    This may have been useful once in times long past, but today you SHOULD NOT set this to anything but `1`.
+    To select the desired fonts, specify their correct, unique name.
+    Furthermore, since libass (as of 0.17.1) does not yet fully support the Encoding field,
+    the result you get during authoring for values other than `1` might be different
+    to what viewers get during playback.<br/>
+    This has nothing to do with the encoding of the actual text.
 
   Preview:
   : Shows a preview of what the text will look like using the current style