Merge pull request #6317 from capital-G/scdoc-katex

Add formula support for SCDoc via kaTeX
supercollider · Jun 8, 2024 · 86ce5a4 · 86ce5a4
2 parents f6a2776 + 6cd9d77
commit 86ce5a4
Show file tree

Hide file tree

Showing 32 changed files with 3,040 additions and 2,715 deletions.
diff --git a/HelpSource/Reference/SCDocSyntax.schelp b/HelpSource/Reference/SCDocSyntax.schelp
@@ -249,9 +249,17 @@ image::foo.png#click this image#Classes/SinOsc::
 
 Just leave the caption empty if you want a link but no caption.
 
+## keyword:: math\::
+teletype:: MATH\:: ::
+|| Converts LaTeX code into an inline formula. E.g.
+teletype::
+math::\frac{\pi}{2}::
+::
+becomes math::\frac{\pi}{2}:: embedded within a line of text.
 ::
 
-The following tags (CODE and TELETYPE) can be written in two forms, either inline or block.
+
+The following tags (CODE, TELETYPE and MATH) can be written in two forms, either inline or block.
 strong::Inline:: form has the end-tag on the same line, and need any enclosed double-colons that should be part of the text to be escaped with backslash (teletype:: \ ::).
 strong::Block:: form has the tag and end-tag on lines by themselves, and can take multi-line text. In block form, only a single end-tag on its own line counts and any end-tags inside the text should not be escaped (except if it's on a single line).
 
@@ -271,6 +279,20 @@ teletype:: CODE\:: ::
 ## keyword:: teletype\::
 teletype:: TELETYPE\:: ::
 || Render monospace text.
+## keyword:: math\::
+teletype:: MATH\:: ::
+|| Renders LaTeX code in display style. E.g.
+teletype::
+math::
+\int_0^{2\pi}\sin(x)~dx = 0
+\::
+::
+becomes
+math::
+\int_0^{2\pi}\sin(x)~dx = 0
+::
+which is separated from the text through a block.
+For specifics check out the used rendering engine kaTeX at https://katex.org
 ::
 
 subsection:: Lists and tables
@@ -428,9 +450,11 @@ inlinetag         ::= "LINK::"
                     | "EMPHASIS::"
                     | "CODE::"
                     | "TELETYPE::"
+                    | "MATH::"
                     | "ANCHOR::"
 blocktag          ::= CODEBLOCK
                     | TELETYPEBLOCK
+                    | MATHBLOCK
 listtag           ::= "LIST::"
                     | "TREE::"
                     | "NUMBEREDLIST::"

diff --git a/HelpSource/lib/katex/README.md b/HelpSource/lib/katex/README.md
@@ -0,0 +1,16 @@
+# KaTeX
+
+SCDocs uses [KaTeX](https://github.com/KaTeX/KaTeX) to render tex code into formulas.
+
+In order to reduce the footprint of KaTex, a custom build of version `0.16.0` is used which only includes the `woff2` fontfiles using
+
+```shell
+USE_TTF="false" USE_WOFF="false" USE_WOFF2="true" yarn build
+```
+
+`woff2` is a sufficient font type, see <https://caniuse.com/woff2>.
+
+## License
+
+KaTeX is published under MIT license.
+The bundled fonts are licensed under SIL Open Font License, see <https://github.com/KaTeX/KaTeX/issues/339#issuecomment-135518223>.
diff --git a/HelpSource/lib/katex/fonts/KaTeX_AMS-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_AMS-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Caligraphic-Bold.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Caligraphic-Bold.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Caligraphic-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Caligraphic-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Fraktur-Bold.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Fraktur-Bold.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Fraktur-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Fraktur-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Main-Bold.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Main-Bold.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Main-BoldItalic.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Main-BoldItalic.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Main-Italic.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Main-Italic.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Main-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Main-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Math-BoldItalic.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Math-BoldItalic.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Math-Italic.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Math-Italic.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_SansSerif-Bold.woff2 b/HelpSource/lib/katex/fonts/KaTeX_SansSerif-Bold.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_SansSerif-Italic.woff2 b/HelpSource/lib/katex/fonts/KaTeX_SansSerif-Italic.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_SansSerif-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_SansSerif-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Script-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Script-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Size1-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Size1-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Size2-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Size2-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Size3-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Size3-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Size4-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Size4-Regular.woff2
diff --git a/HelpSource/lib/katex/fonts/KaTeX_Typewriter-Regular.woff2 b/HelpSource/lib/katex/fonts/KaTeX_Typewriter-Regular.woff2
diff --git a/HelpSource/lib/katex/katex.min.css b/HelpSource/lib/katex/katex.min.css
diff --git a/HelpSource/lib/katex/katex.min.js b/HelpSource/lib/katex/katex.min.js
diff --git a/HelpSource/scdoc.js b/HelpSource/scdoc.js
@@ -282,3 +282,17 @@ function setUpWebChannel(port) {
         });
     }
 }
+
+function renderTex() {
+    for (let aSpan of document.getElementsByClassName("math")) {
+        const tex = aSpan.textContent;
+        katex.render(tex, aSpan, {
+            throwOnError: false,
+            displayMode: aSpan.classList.contains("block"),
+        });
+    }
+}
+
+window.addEventListener('DOMContentLoaded',function () {
+    renderTex();
+});
diff --git a/SCClassLibrary/SCDoc/SCDocRenderer.sc b/SCClassLibrary/SCDoc/SCDocRenderer.sc
@@ -236,11 +236,13 @@ SCDocHTMLRenderer {
 		<< "<link rel='stylesheet' id='scdoc-theme' href='" << baseDir << "/themes/default.css' type='text/css' />\n"
 		<< "<link rel='stylesheet' href='" << baseDir << "/frontend.css' type='text/css' />\n"
 		<< "<link rel='stylesheet' href='" << baseDir << "/custom.css' type='text/css' />\n"
+		<< "<link rel='stylesheet' href='" << baseDir << "/lib/katex/katex.min.css' />\n"
 		<< "<meta name='viewport' content='width=device-width, initial-scale=1'>\n"
 		<< "<meta http-equiv='Content-Type' content='text/html; charset=UTF-8' />\n"
 		<< "<script src='" << baseDir << "/lib/jquery.min.js'></script>\n"
 		<< "<script src='" << baseDir << "/lib/codemirror-5.39.2.min.js' type='text/javascript'></script>\n"
 		<< "<script src='" << baseDir << "/lib/codemirror-addon-simple-5.39.2.min.js' type='text/javascript'></script>\n"
+		<< "<script defer src='" << baseDir << "/lib/katex/katex.min.js' type='text/javascript'></script>\n"
 		<< "<script>\n"
 		<< "var helpRoot = '" << baseDir << "';\n"
 		<< "var scdoc_title = '" << doc.title.escapeChar($') << "';\n"
@@ -592,6 +594,16 @@ SCDocHTMLRenderer {
 					stream << "<a class='anchor' name='kw_" << this.escapeSpacesInAnchor(child.text) << "'>&nbsp;</a>";
 				}
 			},
+			\MATHBLOCK, { // uses temml to convert tex to MathML
+				stream << "<span class='math block'>\n"
+				<< this.escapeSpecialChars(node.text)
+				<< "\n</span>";
+			},
+			\MATH, {
+				stream << "<span class='math'>"
+				<< this.escapeSpecialChars(node.text)
+				<< "</span>";
+			},
 			\IMAGE, {
 				f = node.text.split($#);
 				stream << "<div class='image'>";

diff --git a/SCDoc/SCDoc.l b/SCDoc/SCDoc.l
@@ -98,9 +98,11 @@ if (scdoc_start_token) {
 (?i:emphasis::[ \t\n\r]*)     BEGIN(verbatim); return EMPHASIS;
 (?i:code::[ \t]*)           BEGIN(verbatim); return CODE;
 (?i:teletype::[ \t]*)       BEGIN(verbatim); return TELETYPE;
+(?i:math::[ \t]*) BEGIN(verbatim); return MATH;
 
 (?i:[ \t]*code::[ \t]*\n+)      BEGIN(verbatim2); return CODEBLOCK;
 (?i:[ \t]*teletype::[ \t]*\n+)  BEGIN(verbatim2); return TELETYPEBLOCK;
+(?i:[ \t]*math::[ \t]*\n+) BEGIN(verbatim2); return MATHBLOCK;
 
 <INITIAL,verbatim>[ \t\n\r]*::    BEGIN(0); return TAGSYM;
 <verbatim2>\n[ \t\n\r]*::         BEGIN(0); return TAGSYM;
@@ -168,8 +170,10 @@ if (scdoc_start_token) {
 <eat>(?i:emphasis::[ \t\n\r]*)     BEGIN(eat2);
 <eat>(?i:code::[ \t]*)           BEGIN(eat2);
 <eat>(?i:teletype::[ \t]*)       BEGIN(eat2);
+<eat>(?i:math::[ \t]*) BEGIN(eat2);
 <eat>(?i:[ \t]*code::[ \t]*\n+)      BEGIN(eat3);
 <eat>(?i:[ \t]*teletype::[ \t]*\n+)  BEGIN(eat3);
+<eat>(?i:[ \t]*math::[ \t]*\n+) BEGIN(eat3);
 <eat2>[ \t\n\r]*::            BEGIN(eat);
 <eat3>\n[ \t\n\r]*::         BEGIN(eat);
 <eat,eat2,eat3>.|\n          /* empty */