From e8480abf6bcad9abda2c71d77e2ca2a4e55e1456 Mon Sep 17 00:00:00 2001
From: Myriad-Dreamin <camiyoru@gmail.com>
Date: Sat, 18 Jan 2025 14:33:48 +0800
Subject: [PATCH] docs: add preamble docs and move the internal docs to
 `CONTRIBUTING.md`

---
 CONTRIBUTING.md                      | 24 ++++++++++++++
 README.md                            | 47 +++++++++++++++-------------
 packages/mitex/examples/preamble.typ | 15 +++++++++
 3 files changed, 64 insertions(+), 22 deletions(-)
 create mode 100644 packages/mitex/examples/preamble.typ

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6d33e05..98c5c5a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,29 @@
 # Contributing to MiTeX
 
+Currently, MiTeX maintains following three parts of code:
+
+- A TeX parser library written in **Rust**, see [mitex-lexer](https://github.com/mitex-rs/mitex/tree/main/crates/mitex-lexer) and [mitex-parser](https://github.com/mitex-rs/mitex/tree/main/crates/mitex-parser).
+- A TeX to Typst converter library written in **Rust**, see [mitex](https://github.com/mitex-rs/mitex/tree/main/crates/mitex).
+- A list of TeX packages and commands written in **Typst**, which then used by the typst package, see [MiTeX Command Specification](https://github.com/mitex-rs/mitex/tree/main/packages/mitex/specs).
+
+For a translation process, for example, we have:
+
+```
+\frac{1}{2}
+
+===[parser]===> AST ===[converter]===>
+
+#eval("$frac(1, 2)$", scope: (frac: (num, den) => $(num)/(den)$))
+```
+
+You can use the `#mitex-convert()` function to get the Typst Code generated from LaTeX Code.
+
+### Adding missing TeX commands
+
+Even if you don't know Rust at all, you can still add missing TeX commands to MiTeX by modifying [specification files](https://github.com/mitex-rs/mitex/tree/main/packages/mitex/specs), since they are written in typst! You can open an issue to acquire the commands you want to add, or you can edit the files and submit a pull request.
+
+In the future, we will provide the ability to customize TeX commands, which will make it easier for you to use the commands you create for yourself.
+
 ## Installing Dependencies
 
 You should install [Typst](https://github.com/typst/typst?tab=readme-ov-file#installation) and [Rust](https://www.rust-lang.org/tools/install) for running the build script.
diff --git a/README.md b/README.md
index 6230148..172f56e 100644
--- a/README.md
+++ b/README.md
@@ -118,36 +118,39 @@ Another example is that MiTeX transforms `(\frac{1}{2})` into `\(frac(1, 2)\)` i
 
 **Certainly, the greatest advantage is that you can directly write LaTeX content in Typst without the need for manual conversion!**
 
-## Submitting Issues
-
-If you find missing commands or bugs of MiTeX, please feel free to submit an issue [here](https://github.com/mitex-rs/mitex/issues).
-
-## Contributing to MiTeX
+### Adding customized commands
 
-Currently, MiTeX maintains following three parts of code:
+There are two kinds of commands to add:
 
-- A TeX parser library written in **Rust**, see [mitex-lexer](https://github.com/mitex-rs/mitex/tree/main/crates/mitex-lexer) and [mitex-parser](https://github.com/mitex-rs/mitex/tree/main/crates/mitex-parser).
-- A TeX to Typst converter library written in **Rust**, see [mitex](https://github.com/mitex-rs/mitex/tree/main/crates/mitex).
-- A list of TeX packages and commands written in **Typst**, which then used by the typst package, see [MiTeX Command Specification](https://github.com/mitex-rs/mitex/tree/main/packages/mitex/specs).
+- **Commonly used commands**: If you find there are some builtin or commonly used commands missing in MiTeX, you can submit an issue or contribute them according to [Adding missing TeX commands.](./CONTRIBUTING.md#adding-missing-tex-commands)
 
-For a translation process, for example, we have:
+- **Special commands (Preambles)**: If you want to add some special commands (preambles) for your own use, you can define them by `\newcommand` or `\newenvironment` and override the mitex function in your. Example:
 
-```
-\frac{1}{2}
+  ````typ
+  #let preamble = ```tex
+  \newcommand{\f}[2]{#1f(#2)}
+  ```
 
-===[parser]===> AST ===[converter]===>
+  #let mitex = (it, ..args) => mitex.with(..args)({
+    (preamble, it).map(it => it.text).join("\n")
+  })
+  ````
 
-#eval("$frac(1, 2)$", scope: (frac: (num, den) => $(num)/(den)$))
-```
+  And use them in your Typst code:
 
-You can use the `#mitex-convert()` function to get the Typst Code generated from LaTeX Code.
-
-### Add missing TeX commands
+  ````typ
+  #show raw.where(lang: "mitex"): mitex
+  ```mitex
+  \f\relax{x} = \int_{-\infty}^\infty
+    \f\hat\xi\,e^{2 \pi i \xi x}
+    \,d\xi
+  ```
+  ````
 
-Even if you don't know Rust at all, you can still add missing TeX commands to MiTeX by modifying [specification files](https://github.com/mitex-rs/mitex/tree/main/packages/mitex/specs), since they are written in typst! You can open an issue to acquire the commands you want to add, or you can edit the files and submit a pull request.
+## Submitting Issues
 
-In the future, we will provide the ability to customize TeX commands, which will make it easier for you to use the commands you create for yourself.
+If you find missing commands or bugs of MiTeX, please feel free to submit an issue [here](https://github.com/mitex-rs/mitex/issues).
 
-### Develop the parser and the converter
+## Contributing
 
-See [CONTRIBUTING.md](https://github.com/mitex-rs/mitex/blob/main/CONTRIBUTING.md).
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
diff --git a/packages/mitex/examples/preamble.typ b/packages/mitex/examples/preamble.typ
new file mode 100644
index 0000000..043a043
--- /dev/null
+++ b/packages/mitex/examples/preamble.typ
@@ -0,0 +1,15 @@
+#import "../lib.typ": *
+
+#let preamble = ```tex
+\newcommand{\f}[2]{#1f(#2)}
+```
+
+#let mitex = (it, ..args) => mitex.with(..args)({
+  (preamble, it).map(it => it.text).join("\n")
+})
+
+#mitex(```latex
+\f\relax{x} = \int_{-\infty}^\infty
+  \f\hat\xi\,e^{2 \pi i \xi x}
+  \,d\xi
+```)