From 7dd5da97f60da774407969ff87e31fc6c79814f9 Mon Sep 17 00:00:00 2001
From: Benedikt Peetz <benedikt.peetz@b-peetz.de>
Date: Sat, 18 May 2024 19:54:25 +0200
Subject: [PATCH] docs(src): Improve rendering of quotation marks

I have used a unicode lookalike for the single quote, as the normal
latex way to include it is not supported by katex (`\textquotesingle`).
---
 README.md             | 13 +++++++++++++
 docs/docs-header.html | 28 ++++++++++++++++++----------
 src/lib.rs            | 12 +++++++-----
 3 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 05e5773..3fab064 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,19 @@ If not, see <https://www.gnu.org/licenses/>.
 
 > A very simple programming language, used to map functions to commands
 
+## Docs
+If you want to generate the docs locally use this command, as they need KaTeX:
+```sh
+# Generate documentation for the dependencies
+cargo doc
+
+# Generate the documentation for this crate with the KaTeX header.
+RUSTDOCFLAGS="--html-in-header ./docs/docs-header.html" cargo doc --no-deps
+```
+
+`docs.rs` already does this automatically because of the attribute in the `Cargo.toml`
+file.
+
 ## Licence
 
 This program is free software: you can redistribute it and/or modify it
diff --git a/docs/docs-header.html b/docs/docs-header.html
index ae34e2d..5897e41 100644
--- a/docs/docs-header.html
+++ b/docs/docs-header.html
@@ -47,19 +47,27 @@ If not, see <https://www.gnu.org/licenses/>.
       crossorigin="anonymous"
     ></script>
     <script>
+      // Workaround for rustdoc's "smart" quotation mark replacement feature
+      function normalize_quotes(math) {
+          // const orig = math;
+
+          math = math.replace(/”/g, "\"");
+          math = math.replace(/“/g, "\"");
+
+          math = math.replace(/’/g, "'");
+          math = math.replace(/‘/g, "'");
+          // console.log(`[\n${orig}\n] -> [\n${math}\n].`);
+          return math;
+      }
+
       document.addEventListener("DOMContentLoaded", function () {
         renderMathInElement(document.body, {
           delimiters: [
-            { left: "$$", right: "$$", display: true },
-            { left: "\\(", right: "\\)", display: false },
-            { left: "$", right: "$", display: false },
-            { left: "\\[", right: "\\]", display: true },
-          ]
-          // FIXME(@soispha): This removes the quotes completely <2023-10-31>
-          // macros: {
-          //   "”": "\\noexpand ”",
-          //   "“": "\\noexpand “",
-          // },
+            { left: "\\(", right: "\\)", display: false},
+            { left: "$", right: "$", display: false},
+            { left: "\\[", right: "\\]", display: true},
+          ],
+          preProcess: normalize_quotes,
         });
       });
     </script>
diff --git a/src/lib.rs b/src/lib.rs
index 2fd704c..f3c009f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -34,18 +34,20 @@
 //!
 //! Correctly spoken, the Language, containing all valid command names, is just the Kleene closure
 //! over an Alphabet $\Sigma$, which contains all alphanumeric characters:
-//! $$ \Sigma_{cmd} = \\{x | 0 \leqslant x \leqslant 9\\} \cup \\{x | "a" \leqslant x \leqslant "z"\\} \cup \\{x | "A" \leqslant x \leqslant "Z"\\} \cup \\{"\\_", "\text{-}", "."\\} $$
+//! \\[ \Sigma_{cmd} = \\{x | 0 \leqslant x \leqslant 9\\} \cup \\{x | "\text{a}" \leqslant x \leqslant "\text{z}"\\} \cup \\{x | "\text{A}" \leqslant x \leqslant "\text{Z}"\\} \cup \\{"\text{\\_}", "\text{-}", "."\\} \\]
 //!
 //! ## Argument
 //! Arguments constructed from the same alphabet as the commands, but can contain additional chars
-//! listed in the [trinitry.pest](../../../src/trinitry.pest) file.
-//! $$ \Sigma_{args} = \Sigma_{cmd} \cup{} \\{\\dots{}\\} $$
+#![doc = concat!("listed in the [trinitry.pest](https://docs.rs/crate/trinitry/", env!("CARGO_PKG_VERSION"), "/source/src/trinitry.pest) file.")]
+//! \\[ \Sigma_{args} = \Sigma_{cmd} \cup{} \\{\\dots{}\\} \\]
 //!
 //! Besides the extra chars outlined above the arguments can also contain
 //! spaces and quotes, if they are quoted. Quoted args are either double quoted, and can thus
 //! contain single quotes, or single quoted, and can contain double quotes.
-//! $$ \Sigma_{args-double-quoted} = \Sigma_{args} \cup \\{"\\text{\\texttt{'}}", "\\ "} $$
-//! $$ \Sigma_{args-single-quoted} = \Sigma_{args} \cup \\{"\\text{\\texttt{"}}", "\\ "} $$
+//! \\[
+//! \Sigma_{args-double-quoted} = \Sigma_{args} \cup \\{"\texttt{ꞌ}", "\\ "\\} \\\\
+//! \Sigma_{args-single-quoted} = \Sigma_{args} \cup \\{"\texttt{"}", "\\ "\\}
+//! \\]
 //!
 //! # Examples
 //! ## Command