Refactor codebase

2026-07-10 21:34:07 +08:00
parent b62a488e11
commit 52c0f83376
61 changed files with 1039 additions and 5107 deletions
@@ -0,0 +1,106 @@
+# MPI Bilingual Typst Template — Design Decisions
+
+## Location
+
+- Repo / project root: `~/documents/mpi/`
+- Template directory (contains `lib/`): `~/documents/mpi/translate-files/`
+- Template: `translate-files/lib/mpi-bilingual-template.typ`
+- Example usage: `translate-files/从物品整理到心灵整理/mindful-organizing.typ`
+
+## Goal
+
+A single reusable Typst template for bilingual Chinese-English 静心学堂丛书
+publications. Host `.typ` files should contain almost no setup code — only an
+`#import`, a `#show: mpi-bilingual.with(...)` call, and the article content.
+
+## Font choice
+
+- **Chinese:** Noto Serif CJK SC (Google Fonts)
+- **English:** Noto Serif (Google Fonts), used as a freely available substitute
+  for Times New Roman.
+
+## Page and paragraph formatting
+
+| Setting | Value | Rationale |
+|---|---|---|
+| Paper | A4 | Standard publication size |
+| Margins | 2.5 cm all around | Matches existing documents |
+| Body size | 10.5 pt | 五号 per the formatting guide |
+| Line spacing (`leading`) | 1.5 em | 1.5× line height per the guide |
+| Paragraph spacing | 1.5 em | Equivalent to one blank line between paragraphs |
+| Alignment | justified | Matches the existing `mindful-organizing.typ` look |
+| First-line indent | 2 em | Keeps bilingual paragraphs visually distinct |
+| Heading numbering | none | Headings are written verbatim in the host file |
+| Heading spacing | `above: 2em`, `below: 1.2em` | Clear section breaks without page breaks |
+| Footnotes | 8 pt, left aligned | Per the formatting guide |
+
+## Title page
+
+Titles and subtitles are passed as free Typst content (`title-cn`, `title-en`,
+`subtitle-cn`, `subtitle-en`).
+
+The gap between title and subtitle uses `linebreak()` inside a single paragraph
+so the spacing follows the `line-height: 1.5` rhythm instead of an arbitrary
+`v()` length. A larger `v(1.5em)` separates the Chinese block from the English
+block.
+
+## Table of contents
+
+The TOC shows only English headings with dotted leaders and page numbers.
+Chinese headings are displayed as compact section headers above their English
+counterparts. This mirrors the behavior of the old `helpers.typ` but lives in
+the template.
+
+## Host file contract
+
+A host file should look like this and nothing else:
+
+```typst
+#import "../lib/mpi-bilingual-template.typ": mpi-bilingual
+
+#show: mpi-bilingual.with(
+  title-cn: [中文标题],
+  title-en: [English Title],
+  subtitle-cn: [——副标题],
+  subtitle-en: [—Subtitle],
+)
+
+= 一、章节标题
+= I. Chapter Title
+
+中文段落……
+
+English paragraph …
+```
+
+Compile with the helper script:
+
+```bash
+~/documents/mpi/toolkit/scripts/compile-typst.fish ./从物品整理到心灵整理/mindful-organizing.typ [output.pdf]
+```
+
+Or manually from the template directory (`~/documents/mpi/translate-files/`):
+
+```bash
+cd ~/documents/mpi/translate-files
+typst compile --root . ./从物品整理到心灵整理/mindful-organizing.typ
+```
+
+The `--root .` is required because the import `../lib/...` would otherwise
+escape Typst's sandbox.
+
+## What is intentionally not in the template
+
+- No inline helpers like `#speaker` or `#quote-cn` in host files. The template
+  sets global formatting only. Dialogue speakers can be marked with `**Name:**`
+  when truly needed.
+- No automatic blue styling for scripture quotes, because reliably detecting
+  quoted classics in plain text requires explicit markup.
+- No per-chapter footnote numbering; Typst's default continuous numbering is
+  used.
+
+## References
+
+- `references/静心学堂丛书英文统一格式-20260211.pdf` — MPI formatting guide
+- `translate-files/从物品整理到心灵整理/mindful-organizing.typ` — example host
+  file and current reference implementation