docs: add typlite docs (#1828)

* docs: add typlite docs

* docs: update typlite docs

* chore: reduce trim

docs/tinymist/book.typ

@@ -25,6 +25,7 @@
     - #chapter("feature/docs.typ")[Code Documentation]
     - #chapter("guide/completion.typ")[Code Completion]
     - #chapter("feature/export.typ")[Exporting Documents]
+    - #chapter("feature/typlite.typ")[Exporting to Other Markup Formats]
     - #chapter("feature/preview.typ")[Document Preview]
     - #chapter("feature/testing.typ")[Testing]
     - #chapter("feature/linting.typ")[Linting]

docs/tinymist/feature/cli.typ

@@ -60,7 +60,7 @@ To save the compilation command to the lock file at the path `some/tinymist.lock
 tinymist compile --lockfile some/tinymist.lock path/to/main.typ
 ```
 
-The lock file feature is in development. It is to help the language server to understand the structure of your projects. See #link("https://github.com/Myriad-Dreamin/tinymist/blob/main/editors/vscode/Configuration.md#tinymistprojectresolution")[Configuration: tinymist.projectResolution].
+The lock file feature is in development. It is to help the language server to understand the structure of your projects. See #github-link("/editors/vscode/Configuration.md#tinymistprojectresolution")[Configuration: tinymist.projectResolution].
 
 == Running Tests
 

docs/tinymist/feature/docs.typ

@@ -16,7 +16,7 @@ Tinymist will read the documentation from the source code and display it in the
 
 A docstring is an object in source code associating with some typst definition, whose content is the documentation information of the definition. Documentation is placed on consecutive special comments using three forward slashes `///` and an optional space. These are called doc comments.
 
-While the #link("https://github.com/Myriad-Dreamin/tinymist/blob/main/crates/tinymist-query/src/syntax/comment.rs")[`DocCommentMatcher`] matches doc comments in a looser way, we recommend using the strict syntax mentioned in the following sections.
+While the #github-link("/crates/tinymist-query/src/syntax/comment.rs")[`DocCommentMatcher`] matches doc comments in a looser way, we recommend using the strict syntax mentioned in the following sections.
 
 == Example 1
 

docs/tinymist/feature/export.typ

@@ -47,7 +47,17 @@ This requires the following configuration in your `tasks.json` file:
 }
 ```
 
-See the #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode/e2e-workspaces/print-state")[Sample Workspace: print-state] for more details.
+See the #github-link("/editors/vscode/e2e-workspaces/print-state")[Sample Workspace: print-state] for more details.
+
+== IEEE Example (VSCode Tasks)
+
+This workspace gives an example to create and prepare IEEE papers using Typst, which exports typst documents to LaTeX.
+
+#raw(lang: "json", block: true, read("/editors/vscode/e2e-workspaces/ieee-paper/.vscode/tasks.json"))
+
+It uses #typst-func("export") to export the document to LaTeX.
+
+See the #github-link("/editors/vscode/e2e-workspaces/ieee-paper")[Sample Workspace: IEEE Paper] for more details.
 
 == Pdfpc Example (VSCode Tasks)
 
@@ -183,6 +193,7 @@ You can call the following export commands.
 - `tinymist.exportPdf`
 - `tinymist.exportHtml`
 - `tinymist.exportMarkdown`
+- `tinymist.exportTeX`
 - `tinymist.exportText`
 - `tinymist.exportQuery`
 

docs/tinymist/feature/language-content.typ

@@ -56,7 +56,7 @@ Extra features:
 - Provides test, benchmark, coverage collecting on documents and modules. Check #cross-link("/feature/testing.typ")[Docs: Testing Features].
 - Provides builtin linting. Check #cross-link("/feature/linting.typ")[Docs: Linting Features].
 - Provides a status bar item to show the current document's compilation status and words count.
-- #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/tools/editor-tools")[Editor tools]:
+- #github-link("/tools/editor-tools")[Editor tools]:
   - View a list of templates in template gallery. (`tinymist.showTemplateGallery`)
   - Click a button in template gallery to initialize a new project with a template. (`tinymist.initTemplate` and `tinymist.initTemplateInPlace`)
   - Trace execution in current document (`tinymist.profileCurrentFile`).

docs/tinymist/feature/preview.typ

@@ -46,8 +46,8 @@ return {
 
 Also see:
 
-- #link("https://github.com/Myriad-Dreamin/tinymist/blob/main/editors/vscode/Configuration.md")[VS Cod(e,ium): Tinymist Server Configuration]
-- #link("https://github.com/Myriad-Dreamin/tinymist/blob/main/editors/neovim/Configuration.md")[Neovim: Tinymist Server Configuration]
+- #github-link("/editors/vscode/Configuration.md")[VS Cod(e,ium): Tinymist Server Configuration]
+- #github-link("/editors/neovim/Configuration.md")[Neovim: Tinymist Server Configuration]
 
 = Builtin Preview Feature
 

docs/tinymist/feature/testing.typ

@@ -51,7 +51,7 @@ Running test(panic-on-panic)
 
 Since it requires some heavy framework to run benchmarks, a standalone tool is provided to run benchmarks.
 
-Check #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/crates/crityp")[crityp] for more information.
+Check #github-link("/crates/crityp")[crityp] for more information.
 
 = Visualizing Coverage
 

docs/tinymist/feature/typlite.typ

@@ -0,0 +1,203 @@
+#import "mod.typ": *
+
+#show: book-page.with(title: "Exporting to Other Markup Formats")
+
+#note-box[
+  This feature is currently in early development.
+]
+
+#github-link("/crates/typlite")[typlite] is a pure Rust library for converting Typst documents to other markup formats.
+
+
+typlite's goal is to convert docstrings in typst packages to LSP docs (Markdown Format). To achieve this, it runs HTML export and extract semantic information from the HTML document for markup conversion.
+
+#let pg-node = node.with(corner-radius: 2pt, shape: "rect");
+#let out-format = box.with(width: 5em)
+#let typlite-convert-graph = diagram(
+  node-stroke: 1pt,
+  edge-stroke: 1pt,
+  pg-node((0.5, 0), [Typst Source Code]),
+  edge("-|>", link("https://typst.app/docs/reference/html/")[HTML Export]),
+  pg-node((3, 0), [```xml <xml:typlite/>```]),
+  edge("-|>"),
+  pg-node((5, 0), out-format[LaTeX]),
+  edge((3, 0), (5, -0.7), "-|>"),
+  pg-node((5, -0.7), out-format[Markdown]),
+  edge((3, 0), (5, 0.7), "-|>"),
+  pg-node((5, 0.7), out-format[DocX]),
+)
+
+#figure(
+  cond-image(typlite-convert-graph),
+  caption: [The conversion path from typst source code to other markup formats, by typlite.],
+) <fig:typlite-conversion>
+
+= TodoList
+
+- [ ] Renders figures into PDF instead of SVG.
+- [ ] Converts typst equations, might use #link("https://github.com/jgm/texmath")[texmath] or #link("https://codeberg.org/akida/mathyml")[mathyml] plus #link("https://github.com/davidcarlisle/web-xslt/tree/main/pmml2tex")[pmml2tex].
+
+= Perfect Conversion
+
+typlite is called "-ite" because it only ensures that nice docstrings are converted perfectly. Similarly, if your document looks nice, typlite can also convert it to other markup formats perfectly.
+
+This introduces concept of _Semantic Typst._ To help conversion, you should separate styling scripts and semantic content in your typst documents.
+
+A good example in HTML is ```html <strong>``` v.s. ```html <b>```. Written in typst,
+
+```typ
+#strong[Good Content]
+#text(weight: 700)[Bad Content]
+```
+
+typlite can convert "Good Content" perfectly, but not "Bad Content". This is because we can attach markup-specific styles to "Good Content" then, but "Bad Content" may be broken by some reasons, such as failing to find font weight when rendering the content.
+
+Let's show another example. We have a `main.typ`, which contains the abstract of our paper, and style it with the requirement of the journal. We write it like this:
+#let mixed-content = ```typ
+#align(center)[
+  #text(weight: 700, size: 1.5em)[ABSTRACT]
+  #text(size: 1.2em)[This is the abstract of my paper.]
+]
+```
+#mixed-content
+#eval(mixed-content.text, mode: "markup")
+
+typlite has capability to convert the above content to other markup formats, but it feel cursed. This is because we mix the styling scripts and semantic content together. To separate them, a function `abstract` is can be created:
+
+```typ
+// template.typ
+#let abstract(body) = align(center)[
+  #text(weight: 700, size: 1.5em)[ABSTRACT]
+  #text(size: 1.2em, body)
+]
+// main.typ
+#import "/template.typ": abstract
+#abstract[This is the abstract of my paper.]
+```
+
+The four function calls in the above example can well explain the difference between styling scripts and semantic content. calling `#abstract` from `main.typ` only provide "abstract material" and doesn't add any style, so it is a semantic content. while `#text(weight: 700)`, as a styling script, uses assigns styles to content and make difficult to understand the behind semantics.
+
+typlite will feel happy and make perfect conversion if you keep aware of keep pure semantics of `main.typ` documents in the above way. In fact, this is probably also the way of people abstract typst templates from their documents.
+
+= Example: Styling a Typst Document by IEEE LaTeX Template
+
+#let paper-file-link(link, body) = github-link("/editors/vscode/e2e-workspaces/ieee-paper" + link, body)
+
+The `main.typ` in the #paper-file-link("/")[Sample Workspace: IEEE Paper] can be converted perfectly.
+
+- Run the command ```bash
+  typlite main.typ main.tex --processor "/ieee-tex.typ"
+  ```
+- Create a project on Overleaf, using the #link("https://www.overleaf.com/latex/templates/ieee-demo-template-for-computer-society-conferences/hzzszpqfkqky")[IEEE LaTeX Template.]
+- upload the `main.tex` file and exported PDF assets and it will get rendered and ready to submit.
+
+= The core of processors: `article` function
+
+There is a `--processor "/ieee-tex.typ"` option in the command line, which is not a flag of the official `typst-cli`. The option tells typlite to use a processor file to process the HTML export result.
+- `"/ieee-tex.typ"` is the file relative to the current workspace root.
+- `"@local/ieee-tex:0.1.0"` or `"@preview/ieee-tex:0.1.0"` can be used to get functions from local packages or #link("https://typst.app/universe/")[typst universe].
+
+typlite will show your main documents with the `article` function obtained from the processor file.
+
+````typst
+#let verbatim(body) = {
+  show raw.where(lang: "tex"): it => html.elem("m1verbatim", attrs: (src: it.text))
+  body
+}
+#let article(body) = {
+  verbatim(```tex
+  %% Generated by typlite
+  %% Please report to https://github.com/Myriad-Dreamin/tinymist if you find any bugs.
+
+  \begin{document}
+  Hey,
+  ```)
+  body
+  verbatim(```tex
+  \end{document}
+  ```)
+}
+````
+
+#note-box[
+  Currently, ```typc html.elem("m1verbatim")``` is the only `xml` element can be used by processor scripts. When seeing a `<m1verbatim/>` element, typlite writes the inner content to output directly.
+]
+
+It will output like that:
+
+```tex
+%% Generated by typlite
+%% Please report to https://github.com/Myriad-Dreamin/tinymist if you find any bugs.
+
+\begin{document}
+Hey, [CONTENT generated according to body]
+\end{document}
+```
+
+You can implement the `article` function for different markup formats, such as LaTeX, Markdown, DocX, and Plain Text.
+
+
+
+= Implementing `abstract` for IEEE LaTeX Template
+
+Let's explain how #paper-file-link("/ieee-tex.typ")[`/ieee-tex.typ`] works by the `abstract` example. First, we edit #paper-file-link("/ieee-tex.typ")[`/ieee-template.typ`] to store the abstract in state:
+
+```typ
+#let abstract-state = state("tex:abstract", "")
+#let abstract(body) = if is-html-target {
+  abstract-state.update(_ => body)
+} else {
+    // fallback to regular abstract
+}
+```
+
+#note-box[
+  `is-html-target` already distinguishes regular typst PDF export and typlite export (which uses HTML export). We haven't decide a way to let your template aware of typlite export.
+
+  Luckily, typst has `sys.input` mechanism so you can distinguish it by yourself:
+
+  ```typ
+  // typst compile or typlite main.typ --input x-target=typlite
+  #let x-target = sys.inputs.at("x-target", default: "typst")
+  #x-target // "typst" or "typlite"
+  ```
+
+  Or define a state that shares between the template and the processor script:
+
+  ```typ
+  #let is-typlite = state("is-typlite", false)
+  // processor.typ
+  #let article(body) = {
+    is-typlite.update(_ => true)
+    body
+  }
+  // template.typ
+  #let is-typlite = ...
+  #let abstract(body) = context if is-typlite {
+    abstract-state.update(_ => body)
+  } else {
+    // fallback to regular abstract
+  }
+  ```
+]
+
+Next, in the `ieee-tex.typ`, we can get the `abstract` material from the state and render it in the LaTeX template:
+
+````typ
+#let abstract = context {
+  let abstract-body = state("tex:abstract", "").final()
+  verbatim(```tex
+  % As a general rule, do not put math, special symbols or citations
+  % in the abstract
+  \begin{abstract}
+  ```)
+  abstract-body
+  verbatim(```tex
+  \end{abstract}
+  ```)
+}
+````
+
+#note-box[
+  We don't extracts content from `abstract-body`. Inteadly, we put the body directly in the document, to let typlite process the equations in `abstract-body` and convert them to LaTeX.
+]

docs/tinymist/frontend/emacs.typ

@@ -51,7 +51,7 @@ For example, if you want to export PDF on save:
 You can also have configuration per directory. Be sure to look at the
 documentation of `eglot-workspace-configuration` by #link("https://www.gnu.org/software/emacs/manual/html_node/emacs/Name-Help.html")[`describe-symbol`]..
 
-See #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/Configuration.md")[Tinymist Server Configuration]
+See #github-link("/editors/neovim/Configuration.md")[Tinymist Server Configuration]
 for references.
 
 

docs/tinymist/frontend/helix.typ

@@ -34,7 +34,7 @@ language-servers = ["tinymist"]
 
 == Working with Multiple-File Projects
 
-There is a way in #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/README.md#multiple-file-project-support")[Neovim];, but you cannot invoke related commands with arguments by #link("https://docs.helix-editor.com/commands.html")[:lsp-workspace-command] in helix. As a candidate solution, assuming your having following directory layout:
+There is a way in #github-link("/editors/neovim/README.md#multiple-file-project-support")[Neovim];, but you cannot invoke related commands with arguments by #link("https://docs.helix-editor.com/commands.html")[:lsp-workspace-command] in helix. As a candidate solution, assuming your having following directory layout:
 
 ```plain
 ├── .helix
@@ -63,5 +63,5 @@ command = "tinymist"
 config = { exportPdf = "onType", outputPath = "$root/target/$dir/$name" }
 ```
 
-See #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/Configuration.md")[Tinymist Server Configuration]
+See #github-link("/editors/neovim/Configuration.md")[Tinymist Server Configuration]
 for references.

docs/tinymist/frontend/main.typ

@@ -2,7 +2,7 @@
 
 #show: book-page.with(title: [Editor Frontends])
 
-Leveraging the interface of LSP, tinymist provides frontends to each editor, located in the #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors")[editor folders]. They are minimal, meaning that LSP should finish its main LSP features as many as possible without help of editor frontends. The editor frontends just enhances your code experience. For example, the vscode frontend takes responsibility on providing some nice editor tools. It is recommended to install these editors frontend for your editors.
+Leveraging the interface of LSP, tinymist provides frontends to each editor, located in the #github-link("/tree/main/editors")[editor folders]. They are minimal, meaning that LSP should finish its main LSP features as many as possible without help of editor frontends. The editor frontends just enhances your code experience. For example, the vscode frontend takes responsibility on providing some nice editor tools. It is recommended to install these editors frontend for your editors.
 
 Check the following chapters for uses:
 - #cross-link("/frontend/vscode.typ")[VS Cod(e,ium)]

docs/tinymist/frontend/neovim.typ

@@ -66,7 +66,7 @@ Run and configure `tinymist` in Neovim with support for all major distros and pa
   }
   ```
 
-For a full list of available settings see #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/Configuration.md")[Tinymist Server Configuration].
+For a full list of available settings see #github-link("/tree/main/editors/neovim/Configuration.md")[Tinymist Server Configuration].
 
 = Formatting
 

docs/tinymist/guide/completion.typ

@@ -31,19 +31,19 @@ A frequently asked question is how to completing labels in sub files when writin
 #pro-tip[
   === VSCode:
 
-  See #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode#working-with-multiple-file-projects")[VS Code: Working with Multiple File Projects].
+  See #github-link("/editors/vscode#working-with-multiple-file-projects")[VS Code: Working with Multiple File Projects].
 ]
 
 #pro-tip[
   === Neovim:
 
-  See #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim#working-with-multiple-file-projects")[Heovim: Working with Multiple File Projects].
+  See #github-link("/editors/neovim#working-with-multiple-file-projects")[Heovim: Working with Multiple File Projects].
 ]
 
 #pro-tip[
   === Helix:
 
-  See #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/helix#working-with-multiple-file-projects")[Helix: Working with Multiple File Projects].
+  See #github-link("/editors/helix#working-with-multiple-file-projects")[Helix: Working with Multiple File Projects].
 ]
 
 = Using Snippet-Based Completion

docs/tinymist/introduction.typ

@@ -7,11 +7,11 @@
 Tinymist [ˈtaɪni mɪst] is an integrated language service for #link("https://typst.app/")[Typst] [taɪpst]. You can also call it "微霭" [wēi ǎi] in Chinese.
 
 It contains:
-- an analyzing library for Typst, see #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/crates/tinymist-query")[tinymist-query].
-- a CLI for Typst, see #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/crates/tinymist/")[tinymist].
+- an analyzing library for Typst, see #github-link("/crates/tinymist-query")[tinymist-query].
+- a CLI for Typst, see #github-link("/crates/tinymist/")[tinymist].
   - which provides a language server for Typst, see #cross-link("/feature/language.typ")[Language Features].
   - which provides a preview server for Typst, see #cross-link("/feature/preview.typ")[Preview Feature].
-- a VSCode extension for Typst, see #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode/")[Tinymist VSCode Extension].
+- a VSCode extension for Typst, see #github-link("/editors/vscode/")[Tinymist VSCode Extension].
 
 = Features
 
@@ -119,11 +119,11 @@ Please read the #link("CONTRIBUTING.md")[CONTRIBUTING.md] file for contribution
 
 = Sponsoring
 
-Tinymist thrives on community love and remains proudly independent. While we don't accept direct project funding, we warmly welcome support for our maintainers' personal efforts. Please go to #link("https://github.com/Myriad-Dreamin/tinymist/blob/main/MAINTAINERS.md")[Maintainers Page] and #link("https://github.com/Myriad-Dreamin/tinymist/graphs/contributors")[Contributors Page] and find their personal pages for more information. It is also welcomed to directly ask questions about sponsoring on the #link("https://github.com/Myriad-Dreamin/tinymist/issues/new")[GitHub Issues].
+Tinymist thrives on community love and remains proudly independent. While we don't accept direct project funding, we warmly welcome support for our maintainers' personal efforts. Please go to #github-link("/MAINTAINERS.md")[Maintainers Page] and #link("https://github.com/Myriad-Dreamin/tinymist/graphs/contributors")[Contributors Page] and find their personal pages for more information. It is also welcomed to directly ask questions about sponsoring on the #link("https://github.com/Myriad-Dreamin/tinymist/issues/new")[GitHub Issues].
 
 = Acknowledgements
 
 - Partially code is inherited from #link("https://github.com/nvarner/typst-lsp")[typst-lsp]
-- The #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode#symbol-view")[integrating] *offline* handwritten-stroke recognizer is powered by #link("https://detypify.quarticcat.com/")[Detypify].
-- The #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode#preview-command")[integrating] preview service is powered by #link("https://github.com/Enter-tainer/typst-preview")[typst-preview].
-- The #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/vscode#managing-local-packages")[integrating] local package management functions are adopted from #link("https://github.com/OrangeX4/vscode-typst-sync")[vscode-typst-sync].
+- The #github-link("/editors/vscode#symbol-view")[integrating] *offline* handwritten-stroke recognizer is powered by #link("https://detypify.quarticcat.com/")[Detypify].
+- The #github-link("/editors/vscode#preview-command")[integrating] preview service is powered by #link("https://github.com/Enter-tainer/typst-preview")[typst-preview].
+- The #github-link("/editors/vscode#managing-local-packages")[integrating] local package management functions are adopted from #link("https://github.com/OrangeX4/vscode-typst-sync")[vscode-typst-sync].

docs/tinymist/mod.typ

@@ -1,6 +1,7 @@
 
 #import "/docs/tinymist/book.typ": book-page, cross-link
 #import "/typ/templates/page.typ": *
+#import "/typ/templates/git.typ": *
 #import "@preview/fletcher:0.5.6" as fletcher: *
 #import "@preview/numbly:0.1.0": numbly
 

docs/tinymist/principles.typ

@@ -6,7 +6,7 @@ Four principles are followed.
 
 = Multiple Actors
 
-The main component, #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/crates/tinymist")[tinymist], starts as a thread or process, obeying the #link("https://microsoft.github.io/language-server-protocol/")[Language Server Protocol]. tinymist will bootstrap multiple actors, each of which provides some typst feature.
+The main component, #github-link("/crates/tinymist")[tinymist], starts as a thread or process, obeying the #link("https://microsoft.github.io/language-server-protocol/")[Language Server Protocol]. tinymist will bootstrap multiple actors, each of which provides some typst feature.
 
 The each actor holds and maintains some resources exclusively. For example, the compile server actor holds the well known ```rs trait World``` resource.
 
@@ -45,7 +45,7 @@ The `RenderActor`s don't do compilations, but own project-specific rendering cac
 
 = Multi-level Analysis
 
-he most critical features are lsp functions, built on the #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/crates/tinymist-query")[tinymist-query] crate. To achieve higher concurrency, functions are classified into different levels of analysis.
+he most critical features are lsp functions, built on the #github-link("/crates/tinymist-query")[tinymist-query] crate. To achieve higher concurrency, functions are classified into different levels of analysis.
 + `query_source` – `SyntaxRequest` – locks and accesses a single source unit.
 + `query_world` – `SemanticRequest` – locks and accesses multiple source units.
 + `query_state` – `StatefulRequest` – acquires to accesses a specific version of compile results.
@@ -103,4 +103,4 @@ All non-LSP features in tinymist are *optional*. They are optional, as they can
 
 = Minimal Editor Frontends
 
-Leveraging the interface of LSP, tinymist provides frontends to each editor, located in the #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors")[editor folders]. They are minimal, meaning that LSP should finish its main LSP features as many as possible without help of editor frontends. The editor frontends just enhances your code experience. For example, the vscode frontend takes responsibility on providing some nice editor tools. It is recommended to install these editors frontend for your editors.
+Leveraging the interface of LSP, tinymist provides frontends to each editor, located in the #github-link("/editors")[editor folders]. They are minimal, meaning that LSP should finish its main LSP features as many as possible without help of editor frontends. The editor frontends just enhances your code experience. For example, the vscode frontend takes responsibility on providing some nice editor tools. It is recommended to install these editors frontend for your editors.