Repository: typst-doc-cn/tutorial
Branch: main
Commit: 64a950fa0650
Files: 134
Total size: 486.1 KB

Directory structure:
gitextract_r5ef022r/

├── .codex/
│   └── skills/
│       ├── openspec-apply-change/
│       │   └── SKILL.md
│       ├── openspec-archive-change/
│       │   └── SKILL.md
│       ├── openspec-explore/
│       │   └── SKILL.md
│       ├── openspec-propose/
│       │   └── SKILL.md
│       ├── typst-grammar-authoring/
│       │   └── SKILL.md
│       └── update-typst-grammar-authoring/
│           ├── SKILL.md
│           ├── agents/
│           │   └── openai.yaml
│           ├── references/
│           │   └── grammar-catalog.json
│           └── scripts/
│               └── generate_grammar_catalog.py
├── .gitattributes
├── .github/
│   └── workflows/
│       ├── build.yml
│       └── gh_pages.yml
├── .gitignore
├── .gitmodules
├── .vscode/
│   └── settings.json
├── .zed/
│   └── settings.json
├── Cargo.toml
├── LICENSE
├── README.md
├── _typos.toml
├── assets/
│   └── files/
│       └── tokyo-night.tmTheme
├── crates/
│   └── embedded-typst/
│       ├── Cargo.toml
│       └── src/
│           └── lib.rs
├── meta.json
├── openspec/
│   ├── changes/
│   │   └── archive/
│   │       └── 2026-03-15-create-english-typst-grammar-skill/
│   │           ├── .openspec.yaml
│   │           ├── design.md
│   │           ├── proposal.md
│   │           ├── specs/
│   │           │   └── typst-document-authoring-skill/
│   │           │       └── spec.md
│   │           └── tasks.md
│   ├── config.yaml
│   └── specs/
│       └── typst-document-authoring-skill/
│           └── spec.md
├── scripts/
│   ├── build.ps1
│   └── build.sh
├── src/
│   ├── book.typ
│   ├── ebook.typ
│   ├── figures.typ
│   ├── graph/
│   │   ├── digraph.typ
│   │   ├── electronics.typ
│   │   ├── mod.typ
│   │   ├── solid-geometry.typ
│   │   ├── state-machine.typ
│   │   ├── statistics.typ
│   │   └── table.typ
│   ├── intermediate/
│   │   └── mod.typ
│   ├── introduction.typ
│   ├── misc/
│   │   ├── code-syntax.typ
│   │   ├── code-theme.typ
│   │   ├── font-setting.typ
│   │   ├── mod.typ
│   │   └── text-processing.typ
│   ├── mod.typ
│   ├── prefaces/
│   │   ├── acknowledgement.typ
│   │   ├── license.typ
│   │   └── mod.typ
│   ├── science/
│   │   ├── algorithm.typ
│   │   ├── chemical.typ
│   │   ├── mod.typ
│   │   └── theorem.typ
│   ├── template/
│   │   ├── book.typ
│   │   ├── mod.typ
│   │   ├── paper.typ
│   │   └── slides.typ
│   ├── topics/
│   │   ├── call-externals.typ
│   │   ├── mod.typ
│   │   ├── template-book.typ
│   │   ├── template-cv.typ
│   │   ├── template-paper.typ
│   │   ├── writing-component-lib.typ
│   │   ├── writing-math.typ
│   │   └── writing-plugin-lib.typ
│   └── tutorial/
│       ├── doc-modulize.typ
│       ├── doc-stateful.typ
│       ├── figure-time-travel.typ
│       ├── latex-look.typ
│       ├── mod.typ
│       ├── other-file.typ
│       ├── packages/
│       │   └── m1.typ
│       ├── reference-bibliography.typ
│       ├── reference-calculation.typ
│       ├── reference-color.typ
│       ├── reference-counter-state.typ
│       ├── reference-data-process.typ
│       ├── reference-date.typ
│       ├── reference-grammar.typ
│       ├── reference-layout.typ
│       ├── reference-length.typ
│       ├── reference-math-mode.typ
│       ├── reference-math-symbols.typ
│       ├── reference-outline.typ
│       ├── reference-syntax-analysis.typ
│       ├── reference-table.typ
│       ├── reference-type-builtin.typ
│       ├── reference-typebase.typ
│       ├── reference-utils.typ
│       ├── reference-visualization.typ
│       ├── reference-wasm-plugin.typ
│       ├── scripting-block-and-expression.typ
│       ├── scripting-color.typ
│       ├── scripting-composite.typ
│       ├── scripting-content.typ
│       ├── scripting-control-flow.typ
│       ├── scripting-layout.typ
│       ├── scripting-literal.typ
│       ├── scripting-main.typ
│       ├── scripting-shape.typ
│       ├── scripting-style.typ
│       ├── scripting-variable.typ
│       ├── stateful/
│       │   ├── q0.typ
│       │   ├── q1.typ
│       │   ├── s1.typ
│       │   ├── s2.typ
│       │   └── s3.typ
│       ├── stateful-v0.12.0/
│       │   ├── q0.typ
│       │   ├── q1.typ
│       │   ├── s1.typ
│       │   ├── s2.typ
│       │   └── s3.typ
│       ├── writing-chinese.typ
│       ├── writing-markup.typ
│       ├── writing-math.typ
│       ├── writing-scripting.typ
│       └── writing.typ
└── typ/
    ├── book/
    │   ├── lib.typ
    │   ├── typst.toml
    │   └── variables.typ
    ├── embedded-typst/
    │   ├── example.typ
    │   └── lib.typ
    ├── templates/
    │   ├── ebook.typ
    │   ├── page.typ
    │   ├── side-notes.typ
    │   ├── template-link.typ
    │   ├── term.typ
    │   └── theme-style.toml
    └── typst-meta/
        └── docs.typ

================================================
FILE CONTENTS
================================================

================================================
FILE: .codex/skills/openspec-apply-change/SKILL.md
================================================
---
name: openspec-apply-change
description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
license: MIT
compatibility: Requires openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.2.0"
---

Implement tasks from an OpenSpec change.

**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

**Steps**

1. **Select the change**

   If a name is provided, use it. Otherwise:
   - Infer from conversation context if the user mentioned a change
   - Auto-select if only one active change exists
   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select

   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).

2. **Check status to understand the schema**
   ```bash
   openspec status --change "<name>" --json
   ```
   Parse the JSON to understand:
   - `schemaName`: The workflow being used (e.g., "spec-driven")
   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)

3. **Get apply instructions**

   ```bash
   openspec instructions apply --change "<name>" --json
   ```

   This returns:
   - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
   - Progress (total, complete, remaining)
   - Task list with status
   - Dynamic instruction based on current state

   **Handle states:**
   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
   - If `state: "all_done"`: congratulate, suggest archive
   - Otherwise: proceed to implementation

4. **Read context files**

   Read the files listed in `contextFiles` from the apply instructions output.
   The files depend on the schema being used:
   - **spec-driven**: proposal, specs, design, tasks
   - Other schemas: follow the contextFiles from CLI output

5. **Show current progress**

   Display:
   - Schema being used
   - Progress: "N/M tasks complete"
   - Remaining tasks overview
   - Dynamic instruction from CLI

6. **Implement tasks (loop until done or blocked)**

   For each pending task:
   - Show which task is being worked on
   - Make the code changes required
   - Keep changes minimal and focused
   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
   - Continue to next task

   **Pause if:**
   - Task is unclear → ask for clarification
   - Implementation reveals a design issue → suggest updating artifacts
   - Error or blocker encountered → report and wait for guidance
   - User interrupts

7. **On completion or pause, show status**

   Display:
   - Tasks completed this session
   - Overall progress: "N/M tasks complete"
   - If all done: suggest archive
   - If paused: explain why and wait for guidance

**Output During Implementation**

```
## Implementing: <change-name> (schema: <schema-name>)

Working on task 3/7: <task description>
[...implementation happening...]
✓ Task complete

Working on task 4/7: <task description>
[...implementation happening...]
✓ Task complete
```

**Output On Completion**

```
## Implementation Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 7/7 tasks complete ✓

### Completed This Session
- [x] Task 1
- [x] Task 2
...

All tasks complete! Ready to archive this change.
```

**Output On Pause (Issue Encountered)**

```
## Implementation Paused

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 4/7 tasks complete

### Issue Encountered
<description of the issue>

**Options:**
1. <option 1>
2. <option 2>
3. Other approach

What would you like to do?
```

**Guardrails**
- Keep going through tasks until done or blocked
- Always read context files before starting (from the apply instructions output)
- If task is ambiguous, pause and ask before implementing
- If implementation reveals issues, pause and suggest artifact updates
- Keep code changes minimal and scoped to each task
- Update task checkbox immediately after completing each task
- Pause on errors, blockers, or unclear requirements - don't guess
- Use contextFiles from CLI output, don't assume specific file names

**Fluid Workflow Integration**

This skill supports the "actions on a change" model:

- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly


================================================
FILE: .codex/skills/openspec-archive-change/SKILL.md
================================================
---
name: openspec-archive-change
description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
license: MIT
compatibility: Requires openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.2.0"
---

Archive a completed change in the experimental workflow.

**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

**Steps**

1. **If no change name provided, prompt for selection**

   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.

   Show only active changes (not already archived).
   Include the schema used for each change if available.

   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.

2. **Check artifact completion status**

   Run `openspec status --change "<name>" --json` to check artifact completion.

   Parse the JSON to understand:
   - `schemaName`: The workflow being used
   - `artifacts`: List of artifacts with their status (`done` or other)

   **If any artifacts are not `done`:**
   - Display warning listing incomplete artifacts
   - Use **AskUserQuestion tool** to confirm user wants to proceed
   - Proceed if user confirms

3. **Check task completion status**

   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.

   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).

   **If incomplete tasks found:**
   - Display warning showing count of incomplete tasks
   - Use **AskUserQuestion tool** to confirm user wants to proceed
   - Proceed if user confirms

   **If no tasks file exists:** Proceed without task-related warning.

4. **Assess delta spec sync state**

   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.

   **If delta specs exist:**
   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
   - Determine what changes would be applied (adds, modifications, removals, renames)
   - Show a combined summary before prompting

   **Prompt options:**
   - If changes needed: "Sync now (recommended)", "Archive without syncing"
   - If already synced: "Archive now", "Sync anyway", "Cancel"

   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.

5. **Perform the archive**

   Create the archive directory if it doesn't exist:
   ```bash
   mkdir -p openspec/changes/archive
   ```

   Generate target name using current date: `YYYY-MM-DD-<change-name>`

   **Check if target already exists:**
   - If yes: Fail with error, suggest renaming existing archive or using different date
   - If no: Move the change directory to archive

   ```bash
   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
   ```

6. **Finalize synced spec purpose**

   If specs were synced or created under `openspec/specs/`:
   - Open each affected main spec at `openspec/specs/<capability>/spec.md`
   - Check the `## Purpose` section
   - If it contains the autogenerated archive placeholder (for example,
     `TBD - created by archiving change ...`) or is still too generic, replace
     it with a concise, capability-specific purpose statement before reporting
     completion

7. **Display summary**

   Show archive completion summary including:
   - Change name
   - Schema that was used
   - Archive location
   - Whether specs were synced (if applicable)
   - Note about any warnings (incomplete artifacts/tasks)

**Output On Success**

```
## Archive Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")

All artifacts complete. All tasks complete.
```

**Guardrails**
- Always prompt for change selection if not provided
- Use artifact graph (openspec status --json) for completion checking
- Don't block archive on warnings - just inform and confirm
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
- Show clear summary of what happened
- If sync is requested, use openspec-sync-specs approach (agent-driven)
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
- If archiving creates or updates canonical specs, do not leave autogenerated placeholder `## Purpose` text behind


================================================
FILE: .codex/skills/openspec-explore/SKILL.md
================================================
---
name: openspec-explore
description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
license: MIT
compatibility: Requires openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.2.0"
---

Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.

**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.

**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.

---

## The Stance

- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
- **Adaptive** - Follow interesting threads, pivot when new information emerges
- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
- **Grounded** - Explore the actual codebase when relevant, don't just theorize

---

## What You Might Do

Depending on what the user brings, you might:

**Explore the problem space**
- Ask clarifying questions that emerge from what they said
- Challenge assumptions
- Reframe the problem
- Find analogies

**Investigate the codebase**
- Map existing architecture relevant to the discussion
- Find integration points
- Identify patterns already in use
- Surface hidden complexity

**Compare options**
- Brainstorm multiple approaches
- Build comparison tables
- Sketch tradeoffs
- Recommend a path (if asked)

**Visualize**
```
┌─────────────────────────────────────────┐
│     Use ASCII diagrams liberally        │
├─────────────────────────────────────────┤
│                                         │
│   ┌────────┐         ┌────────┐        │
│   │ State  │────────▶│ State  │        │
│   │   A    │         │   B    │        │
│   └────────┘         └────────┘        │
│                                         │
│   System diagrams, state machines,      │
│   data flows, architecture sketches,    │
│   dependency graphs, comparison tables  │
│                                         │
└─────────────────────────────────────────┘
```

**Surface risks and unknowns**
- Identify what could go wrong
- Find gaps in understanding
- Suggest spikes or investigations

---

## OpenSpec Awareness

You have full context of the OpenSpec system. Use it naturally, don't force it.

### Check for context

At the start, quickly check what exists:
```bash
openspec list --json
```

This tells you:
- If there are active changes
- Their names, schemas, and status
- What the user might be working on

### When no change exists

Think freely. When insights crystallize, you might offer:

- "This feels solid enough to start a change. Want me to create a proposal?"
- Or keep exploring - no pressure to formalize

### When a change exists

If the user mentions a change or you detect one is relevant:

1. **Read existing artifacts for context**
   - `openspec/changes/<name>/proposal.md`
   - `openspec/changes/<name>/design.md`
   - `openspec/changes/<name>/tasks.md`
   - etc.

2. **Reference them naturally in conversation**
   - "Your design mentions using Redis, but we just realized SQLite fits better..."
   - "The proposal scopes this to premium users, but we're now thinking everyone..."

3. **Offer to capture when decisions are made**

   | Insight Type | Where to Capture |
   |--------------|------------------|
   | New requirement discovered | `specs/<capability>/spec.md` |
   | Requirement changed | `specs/<capability>/spec.md` |
   | Design decision made | `design.md` |
   | Scope changed | `proposal.md` |
   | New work identified | `tasks.md` |
   | Assumption invalidated | Relevant artifact |

   Example offers:
   - "That's a design decision. Capture it in design.md?"
   - "This is a new requirement. Add it to specs?"
   - "This changes scope. Update the proposal?"

4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.

---

## What You Don't Have To Do

- Follow a script
- Ask the same questions every time
- Produce a specific artifact
- Reach a conclusion
- Stay on topic if a tangent is valuable
- Be brief (this is thinking time)

---

## Handling Different Entry Points

**User brings a vague idea:**
```
User: I'm thinking about adding real-time collaboration

You: Real-time collab is a big space. Let me think about this...

      COLLABORATION SPECTRUM
      ════════════════════════════════════════════

      Awareness          Coordination         Sync
          │                   │                 │
          ▼                   ▼                 ▼
      ┌────────┐         ┌────────┐        ┌────────┐
      │Presence│         │Cursors │        │  CRDT  │
      │  "3    │         │ Multi  │        │Conflict│
      │online" │         │ select │        │  free  │
      └────────┘         └────────┘        └────────┘
          │                   │                 │
       trivial            moderate           complex

      Where's your head at?
```

**User brings a specific problem:**
```
User: The auth system is a mess

You: [reads codebase]

     ┌─────────────────────────────────────────────┐
     │              CURRENT AUTH FLOW              │
     └─────────────────────────────────────────────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
     ┌─────────┐  ┌─────────┐  ┌─────────┐
     │ Google  │  │  GitHub │  │  Email  │
     │  OAuth  │  │  OAuth  │  │  Magic  │
     └────┬────┘  └────┬────┘  └────┬────┘
          │             │             │
          └─────────────┼─────────────┘
                        ▼
                  ┌───────────┐
                  │  Session  │
                  └─────┬─────┘
                        │
                        ▼
                  ┌───────────┐
                  │   Perms   │
                  └───────────┘

     I see three tangles. Which one's burning?
```

**User is stuck mid-implementation:**
```
User: /opsx:explore add-auth-system
      The OAuth integration is more complex than expected

You: [reads change artifacts]

     You're on task 4: "Implement OAuth flow"

     Let me trace what's involved...

     [draws diagram, explores options, suggests paths]

     Want to update the design to reflect this?
     Or add a spike task to investigate?
```

**User wants to compare options:**
```
User: Should we use Postgres or SQLite?

You: Generic answer is boring. What's the context?

User: A CLI tool that tracks local dev environments

You: That changes everything.

     ┌─────────────────────────────────────────────────┐
     │         CLI TOOL DATA STORAGE                  │
     └─────────────────────────────────────────────────┘

     Key constraints:
     • No daemon running
     • Must work offline
     • Single user

                  SQLite          Postgres
     Deployment   embedded ✓      needs server ✗
     Offline      yes ✓           no ✗
     Single file  yes ✓           no ✗

     SQLite. Not even close.

     Unless... is there a sync component?
```

---

## Ending Discovery

There's no required ending. Discovery might:

- **Flow into a proposal**: "Ready to start? I can create a change proposal."
- **Result in artifact updates**: "Updated design.md with these decisions"
- **Just provide clarity**: User has what they need, moves on
- **Continue later**: "We can pick this up anytime"

When it feels like things are crystallizing, you might summarize:

```
## What We Figured Out

**The problem**: [crystallized understanding]

**The approach**: [if one emerged]

**Open questions**: [if any remain]

**Next steps** (if ready):
- Create a change proposal
- Keep exploring: just keep talking
```

But this summary is optional. Sometimes the thinking IS the value.

---

## Guardrails

- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
- **Don't fake understanding** - If something is unclear, dig deeper
- **Don't rush** - Discovery is thinking time, not task time
- **Don't force structure** - Let patterns emerge naturally
- **Don't auto-capture** - Offer to save insights, don't just do it
- **Do visualize** - A good diagram is worth many paragraphs
- **Do explore the codebase** - Ground discussions in reality
- **Do question assumptions** - Including the user's and your own


================================================
FILE: .codex/skills/openspec-propose/SKILL.md
================================================
---
name: openspec-propose
description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
license: MIT
compatibility: Requires openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.2.0"
---

Propose a new change - create the change and generate all artifacts in one step.

I'll create a change with artifacts:
- proposal.md (what & why)
- design.md (how)
- tasks.md (implementation steps)

When ready to implement, run /opsx:apply

---

**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.

**Steps**

1. **If no clear input provided, ask what they want to build**

   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
   > "What change do you want to work on? Describe what you want to build or fix."

   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).

   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.

2. **Create the change directory**
   ```bash
   openspec new change "<name>"
   ```
   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.

3. **Get the artifact build order**
   ```bash
   openspec status --change "<name>" --json
   ```
   Parse the JSON to get:
   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
   - `artifacts`: list of all artifacts with their status and dependencies

4. **Create artifacts in sequence until apply-ready**

   Use the **TodoWrite tool** to track progress through the artifacts.

   Loop through artifacts in dependency order (artifacts with no pending dependencies first):

   a. **For each artifact that is `ready` (dependencies satisfied)**:
      - Get instructions:
        ```bash
        openspec instructions <artifact-id> --change "<name>" --json
        ```
      - The instructions JSON includes:
        - `context`: Project background (constraints for you - do NOT include in output)
        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
        - `template`: The structure to use for your output file
        - `instruction`: Schema-specific guidance for this artifact type
        - `outputPath`: Where to write the artifact
        - `dependencies`: Completed artifacts to read for context
      - Read any completed dependency files for context
      - Create the artifact file using `template` as the structure
      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
      - Show brief progress: "Created <artifact-id>"

   b. **Continue until all `applyRequires` artifacts are complete**
      - After creating each artifact, re-run `openspec status --change "<name>" --json`
      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
      - Stop when all `applyRequires` artifacts are done

   c. **If an artifact requires user input** (unclear context):
      - Use **AskUserQuestion tool** to clarify
      - Then continue with creation

5. **Show final status**
   ```bash
   openspec status --change "<name>"
   ```

**Output**

After completing all artifacts, summarize:
- Change name and location
- List of artifacts created with brief descriptions
- What's ready: "All artifacts created! Ready for implementation."
- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."

**Artifact Creation Guidelines**

- Follow the `instruction` field from `openspec instructions` for each artifact type
- The schema defines what each artifact should contain - follow it
- Read dependency artifacts for context before creating new ones
- Use `template` as the structure for your output file - fill in its sections
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
  - These guide what you write, but should never appear in the output

**Guardrails**
- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
- Always read dependency artifacts before creating a new one
- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
- If a change with that name already exists, ask if user wants to continue it or create a new one
- Verify each artifact file exists after writing before proceeding to next


================================================
FILE: .codex/skills/typst-grammar-authoring/SKILL.md
================================================
---
name: typst-grammar-authoring
description: Use when authoring or validating Typst documents from canonical grammar examples, especially when you need compile, HTML, or SVG-based validation workflows.
metadata:
  short-description: Author Typst docs from canonical grammar examples
  from-tutorial-rev: https://github.com/typst-doc-cn/tutorial/tree/971815a6b4898c0339b620e08c62824ec03bba7f
---

# Typst Grammar Authoring

Use this skill when the user wants help drafting, fixing, or validating Typst
documents. Everything needed for grammar lookup lives in this file so it can be
copied into another repository without sibling scripts or reference files.

## Workflow

1. Start with the grammar lookup section in this file and pick the closest
   existing pattern before inventing new syntax.
2. Copy the smallest matching example, then adapt it incrementally.
3. Run `typst compile` after each meaningful edit. Any non-zero exit code is a
   blocking failure.
4. After compile succeeds, use HTML output to inspect rendered text and
   document structure when wording or content ordering matters.
5. Use SVG output plus Playwright MCP when you need to inspect visual layout,
   spacing, numbering, line breaks, or emphasis.

## Validation

Compile validation:

```sh
typst compile --root . path/to/document.typ target/typst-grammar-authoring-check/document.pdf
```

Text validation through HTML:

```sh
typst compile --root . --features html path/to/document.typ target/typst-grammar-authoring-check/document.html
rg "expected text" target/typst-grammar-authoring-check/document.html
```

Visual validation through SVG:

```sh
typst compile --root . path/to/document.typ target/typst-grammar-authoring-check/document.svg
typst compile --root . path/to/document.typ target/typst-grammar-authoring-check/document-{0p}.svg
```

Playwright inspection:

- Use Playwright only after SVG generation succeeds.
- Open the SVG directly if the MCP server supports local files.
- Otherwise use a tiny local HTML wrapper that embeds the SVG, then capture a
  screenshot and inspect layout, spacing, numbering, line breaks, and emphasis.

## Guardrails

- Keep all skill-authored prose and instructions in English.
- Canonical syntax examples may retain non-English literals from their source
  examples.
- Do not treat Tinymist or editor diagnostics as the source of truth.
- Do not assume sibling updater scripts, reference files, or repo-local
  metadata exist when using this skill elsewhere.
- Use `{p}` or `{0p}` in multi-page SVG output paths.
- Treat HTML export as a validation aid, not a production contract.
- Keep command examples platform-neutral by using forward-slash or placeholder
  paths.

## Grammar Lookup

This section is embedded on purpose so the skill stays self-contained. Examples
are derived from the unofficial tutorial grammar samples and kept compact so the
lookup remains usable in a single file.

<!-- BEGIN GENERATED GRAMMAR LOOKUP -->

### Base Elements

- `paragraph`: `writing-markup`
- `heading`: `= Heading`; `== Heading`
- `strong`: `*Strong*`
- `emph`: `_emphasis_`; `*_emphasis_*`
- `list`:

```typ
+ List 1
+ List 2
```

- `continue-list`:

```typ
4. List 1
+ List 2
```

- `emum`:

```typ
- Enum 1
- Enum 2
```

- `mix-list-emum`:

```typ
- Enum 1
  + Item 1
- Enum 2
```

- `raw`:

```typ
`code`
```

- `long-raw`:

````typ
``` code```
````

- `lang-raw`:

````typ
```rs  trait World```
````

- `blocky-raw`:

````typ
```typ
= Heading
```
````

- `image`: `#image("/assets/files/香風とうふ店.jpg", width: 50pt)`
- `image-stretch`: `#image("/assets/files/香風とうふ店.jpg", width: 50pt, height: 50pt, fit: "stretch")`
- `image-inline`: `在一段话中插入一个#box(baseline: 0.15em, image("/assets/files/info-icon.svg", width: 1em))图片。`
- `figure`:

````typ
#figure(```typ
#image("/assets/files/香風とうふ店.jpg")
```, caption: [用于加载香風とうふ店送外卖的宝贵影像的代码])
````

- `link`: `#link("https://zh.wikipedia.org")[维基百科]`
- `http-link`: `https://zh.wikipedia.org`
- `internal-link`:

```typ
== 某个标题 <ref-internal-link>
#link(<ref-internal-link>)[链接到某个标题]
```

- `table`: `#table(columns: 2, [111], [2], [3])`
- `table-align`: `#table(columns: 2, align: center, [111], [2], [3])`
- `inline-math`: `$sum_x$`
- `display-math`: `$ sum_x $`
- `escape-sequences`: `>\_<`
- `unicode-escape-sequences`: `\u{9999}`
- `newline-by-space`: `A \ B`
- `newline`:

```typ
A \
B
```

- `shorthand`: `北京--上海`
- `shorthand-space`: `A~B`
- `inline-comment`: `// 行内注释`
- `cross-line-comment`:

```typ
/* 行间注释
  */
```

- `box`: `在一段话中插入一个#box(baseline: 0.15em, image("/assets/files/info-icon.svg", width: 1em))图片。`

### Text Styling

- `highlight`: `#highlight[高亮一段内容]`
- `underline`: `#underline[Language]`
- `underline-evade`:

```typ
#underline(
  evade: false)[ጿኈቼዽ]
```

- `overline`: `#overline[ጿኈቼዽ]`
- `strike`: `#strike[ጿኈቼዽ]`
- `subscript`: `威严满满#sub[抱头蹲防]`
- `superscript`: `香風とうふ店#super[TM]`
- `text-size`: `#text(size: 24pt)[一斤鸭梨]`
- `text-fill`: `#text(fill: blue)[蓝色鸭梨]`
- `text-font`: `#text(font: "Microsoft YaHei")[板正鸭梨]`

### Script Declarations

- `enter-script`: `#1`
- `code-block`: `#{"a"; "b"}`
- `content-block`: `#[内容块]`
- `none-literal`: `#none`
- `false-literal`: `#false`
- `true-literal`: `#true`
- `integer-literal`: `#(-1), #(0), #(1)`
- `n-adecimal-literal`: `#(-0xdeadbeef), #(-0o644), #(-0b1001)`
- `float-literal`: `#(0.001), #(.1), #(2.)`
- `exp-repr-float`: `#(1e2), #(1.926e3), #(-1e-3)`
- `string-literal`: `#"Hello world!!"`
- `str-escape-sequences`: `#"\""`
- `str-unicode-escape-sequences`: `#"\u{9999}"`
- `array-literal`: `#(1, "OvO", [一段内容])`
- `dict-literal`: `#(neko-mimi: 2, "utterance": "喵喵喵")`
- `empty-array`: `#()`
- `empty-dict`: `#(:)`
- `paren-empty-array`: `#(())`
- `single-member-array`: `#(1,)`
- `var-decl`: `#let x = 1`
- `func-decl`: `#let f(x) = x * 2`
- `closure`: `#let f = (x, y) => x + y`
- `named-param`: `#let g(named: none) = named`
- `variadic-param`: `#let g(..args) = args.pos().join([、])`
- `destruct-array`: `#let (one, hello-world) = (1, "Hello, World")`
- `destruct-array-eliminate`: `#let (_, second, ..) = (1, "Hello, World", []); #second`
- `destruct-dict`: `#let (neko-mimi: mimi) = (neko-mimi: 2); #mimi`
- `array-remapping`:

```typ
#let (a, b, c) = (1, 2, 3)
#let (b, c, a) = (a, b, c)
#a, #b, #c
```

- `array-swap`:

```typ
#let (a, b) = (1, 2)
#((a, b) = (b, a))
#a, #b
```

- `placeholder`:

```typ
#let last-two(t) = {
  let _ = t.pop()
  t.pop()
}
#last-two((1, 2, 3, 4))
```

### Script Statements

- `if`:

```typ
#if true { 1 },
#if false { 1 } else { 0 }
```

- `if-if`:

```typ
#if false { 0 } else if true { 1 },
#if false { 2 } else if false { 1 } else { 0 }
```

- `while`:

```typ
#{
  let i = 0;
  while i < 10 {
    (i * 2, )
    i += 1;
  }
}
```

- `for`:

```typ
#for i in range(10) {
  (i * 2, )
}
```

- `for-destruct`: `#for (特色, 这个) in (neko-mimi: 2) [猫猫的 #特色 是 #这个\ ]`
- `break`: `#for i in range(10) { (i, ); (i + 1926, ); break }`
- `continue`:

```typ
#for i in range(10) {
  if calc.even(i) { continue }
  (i, )
}
```

- `return`:

```typ
#let never(..args) = return
#type(never(1, 2))
```

- `include`: `#include "other-file.typ"`

### Script Styling

- `set`:

```typ
#set text(size: 24pt)
四斤鸭梨
```

- `scope`:

```typ
两只#[兔#set text(fill: rgb("#ffd1dc").darken(15%))
  #[兔白#set text(fill: orange)
  又白]，真可爱
]
```

- `set-if`:

```typ
#let is-dark-theme = true
#set rect(fill: black) if is-dark-theme
#set text(fill: white) if is-dark-theme
#rect([wink!])
```

- `show-set`:

```typ
#show: set text(fill: blue)
wink!
```

- `show`:

````typ
#show raw: it => it.lines.at(1)
获取代码片段第二行内容：```typ
#{
set text(fill: true)
}
```
````

- `text-selector`:

```typ
#show "cpp": strong(emph(box("C++")))
在古代，cpp是一门常用语言。
```

- `regex-selector`:

```typ
#show regex("[”。]+"): it => {
  set text(font: "KaiTi")
  highlight(it, fill: yellow)
}
“无名，万物之始也；有名，万物之母也。”
```

- `label-selector`:

```typ
#show <一整段话>: set text(fill: blue)
#[$lambda$语言是世界上最好的语言。] <一整段话>

另一段话。
```

- `selector-exp`:

```typ
#show heading.where(level: 2): set text(fill: blue)
= 一级标题
== 二级标题
```

- `here`: `#context here().position()`
- `here-calc`: `#context [ 页码是偶数：#calc.even(here().page()) ]`
- `query`: `#context query(<ref-internal-link>).at(0).body`
- `state`: `#state("my-state", 1)`

### Script Expressions

- `func-call`: `#calc.pow(4, 3)`
- `content-param`: `#emph[emphasis]`
- `member-exp`:

```typ
#`OvO`.text
```

- `method-exp`: `#"Hello World".split(" ")`
- `dict-member-exp`:

```typ
#let cat = (neko-mimi: 2)
#cat.neko-mimi
```

- `content-member-exp`:

```typ
#`OvO`.text
```

- `repr`: `#repr[ 一段文本 ]`
- `type`: `#type[一段文本]`
- `eval`: `#type(eval("1"))`
- `eval-markup-mode`: `#eval("== 一个标题", mode: "markup")`
- `array-in`:

```typ
#let pol = (1, "OvO", [])
#(1 in pol)
```

- `array-not-in`:

```typ
#let pol = (1, "OvO", [])
#([另一段内容] not in pol)
```

- `dict-in`:

```typ
#let cat = (neko-mimi: 2)
#("neko-mimi" in cat)
```

- `logical-cmp-exp`:

```typ
#(1 < 0), #(1 >= 2),
#(1 == 2), #(1 != 2)
```

- `logical-calc-exp`: `#(not false), #(false or true), #(true and false)`
- `plus-exp`: `#(+1), #(+0), #(1), #(++1)`
- `minus-exp`:

```typ
#(-1), #(-0), #(--1),
#(-+-1)
```

- `arith-exp`:

```typ
#(1 + 1), #(1 + -1),
#(1 - 1), #(1 - -1)
```

- `assign-exp`: `#let a = 1; #repr(a = 10), #a, #repr(a += 2), #a`
- `string-concat-exp`: `#("a" + "b")`
- `string-mul-exp`: `#("a" * 4), #(4 * "ab")`
- `string-cmp-exp`: `#("a" == "b"), #("a" != "b"), #("a" < "ab"), #("a" >= "a")`
- `int-to-float`: `#float(1), #(type(float(1)))`
- `bool-to-int`: `#int(true), #(type(int(true)))`
- `float-to-int`: `#int(1), #(type(int(1)))`
- `dec-str-to-int`: `#int("1"), #(type(int("1")))`
- `nadec-str-to-int`:

```typ
#let safe-to-int(x) = {
  let res = eval(x)
  assert(type(res) == int, message: "should be integer")
  res
}
#safe-to-int("0xf"), #(type(safe-to-int("0xf"))) \
#safe-to-int("0o755"), #(type(safe-to-int("0o755"))) \
#safe-to-int("0b1011"), #(type(safe-to-int("0b1011"))) \
```

- `num-to-str`:

```typ
#repr(str(1)),
#repr(str(.5))
```

- `int-to-nadec-str`: `#str(501, base:16), #str(0xdeadbeef, base:36)`
- `bool-to-str`: `#repr(false)`
- `int-to-bool`:

```typ
#let to-bool(x) = x != 0
#repr(to-bool(0)),
#repr(to-bool(1))
```

<!-- END GENERATED GRAMMAR LOOKUP -->


================================================
FILE: .codex/skills/update-typst-grammar-authoring/SKILL.md
================================================
---
name: update-typst-grammar-authoring
description: Use when maintaining the portable typst-grammar-authoring skill from this repository's canonical Typst grammar source.
metadata:
  short-description: Regenerate the portable Typst grammar skill
---

# Update Typst Grammar Authoring

Use this skill when a maintainer needs to refresh the portable
`typst-grammar-authoring` skill after changing the canonical grammar examples in
`src/tutorial/reference-grammar.typ`.

## Inputs And Outputs

- Canonical source: `src/tutorial/reference-grammar.typ`
- Portable skill: `.codex/skills/typst-grammar-authoring/SKILL.md`
- Traceability artifact:
  `.codex/skills/update-typst-grammar-authoring/references/grammar-catalog.json`

## Workflow

1. Review the source edits in `src/tutorial/reference-grammar.typ` and confirm
   they are ready to publish into the portable skill.
2. Regenerate the portable skill body and traceability artifact:

   ```sh
   python .codex/skills/update-typst-grammar-authoring/scripts/generate_grammar_catalog.py
   ```

3. Review the generated diff for the portable skill and the traceability JSON:

   ```sh
   git diff -- .codex/skills/typst-grammar-authoring/SKILL.md .codex/skills/update-typst-grammar-authoring/references/grammar-catalog.json
   ```

4. Verify the portable skill stayed single-file:

   ```powershell
   Get-ChildItem -Force .codex/skills/typst-grammar-authoring
   ```

5. Verify the portable skill's command examples stayed platform-neutral and did
   not reintroduce Windows absolute paths:

   ```sh
   rg -n "[A-Za-z]:\\\\|path\\\\to|target\\\\typst-grammar-authoring-check|\\.codex\\\\skills|src\\\\tutorial" .codex/skills/typst-grammar-authoring/SKILL.md
   ```

6. If the regenerated lookup looks correct, keep the portable skill focused on
   author guidance only. Any exact source mapping belongs in the updater-owned
   traceability JSON, not in the portable `SKILL.md`.

## Guardrails

- Keep the distributed `typst-grammar-authoring` folder limited to `SKILL.md`.
- Treat `.codex/skills/update-typst-grammar-authoring/references/grammar-catalog.json`
  as the source-mapping artifact for maintainers.
- Keep maintenance-only commands, source-path references, and review steps in
  this updater skill rather than the portable one.
- If the generator output reveals a design issue in the portable skill, update
  the portable template first and rerun the generator before final review.


================================================
FILE: .codex/skills/update-typst-grammar-authoring/agents/openai.yaml
================================================
interface:
  display_name: "Update Typst Grammar Authoring"
  short_description: "Regenerate the portable Typst grammar skill"
  default_prompt: "Use $update-typst-grammar-authoring to refresh the portable Typst grammar skill and its traceability artifacts from src/tutorial/reference-grammar.typ."


================================================
FILE: .codex/skills/update-typst-grammar-authoring/references/grammar-catalog.json
================================================
{
  "source_path": "src/tutorial/reference-grammar.typ",
  "category_count": 6,
  "entry_count": 127,
  "categories": [
    {
      "id": "base-elements",
      "english_heading": "Base Elements",
      "source_heading": "基本元素",
      "source_anchor": "grammar-table:base-elements",
      "heading_line": 30,
      "entries": [
        {
          "lookup_key": "paragraph",
          "source_label": "段落",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-paragraph>)",
            "module": "writing-markup",
            "anchor": "grammar-paragraph"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 33,
            "entry_line_end": 39,
            "code_line_start": 37,
            "code_line_end": 37
          },
          "code": "writing-markup"
        },
        {
          "lookup_key": "heading",
          "source_label": "标题",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-heading>)",
            "module": "writing-markup",
            "anchor": "grammar-heading"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 40,
            "entry_line_end": 46,
            "code_line_start": 44,
            "code_line_end": 44
          },
          "code": "= Heading"
        },
        {
          "lookup_key": "heading",
          "source_label": "二级标题",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-heading>)",
            "module": "writing-markup",
            "anchor": "grammar-heading"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 47,
            "entry_line_end": 53,
            "code_line_start": 51,
            "code_line_end": 51
          },
          "code": "== Heading"
        },
        {
          "lookup_key": "strong",
          "source_label": "着重标记",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-strong>)",
            "module": "writing-markup",
            "anchor": "grammar-strong"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 54,
            "entry_line_end": 60,
            "code_line_start": 58,
            "code_line_end": 58
          },
          "code": "*Strong*"
        },
        {
          "lookup_key": "emph",
          "source_label": "强调标记",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-emph>)",
            "module": "writing-markup",
            "anchor": "grammar-emph"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 61,
            "entry_line_end": 67,
            "code_line_start": 65,
            "code_line_end": 65
          },
          "code": "_emphasis_"
        },
        {
          "lookup_key": "emph",
          "source_label": "着重且强调标记",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-emph>)",
            "module": "writing-markup",
            "anchor": "grammar-emph"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 68,
            "entry_line_end": 74,
            "code_line_start": 72,
            "code_line_end": 72
          },
          "code": "*_emphasis_*"
        },
        {
          "lookup_key": "list",
          "source_label": "有序列表",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-list>)",
            "module": "writing-markup",
            "anchor": "grammar-list"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 75,
            "entry_line_end": 82,
            "code_line_start": 79,
            "code_line_end": 80
          },
          "code": "+ List 1\n+ List 2"
        },
        {
          "lookup_key": "continue-list",
          "source_label": "有序列表（重新开始标号）",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-continue-list>)",
            "module": "writing-markup",
            "anchor": "grammar-continue-list"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 83,
            "entry_line_end": 90,
            "code_line_start": 87,
            "code_line_end": 88
          },
          "code": "4. List 1\n+ List 2"
        },
        {
          "lookup_key": "emum",
          "source_label": "无序列表",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-emum>)",
            "module": "writing-markup",
            "anchor": "grammar-emum"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 91,
            "entry_line_end": 98,
            "code_line_start": 95,
            "code_line_end": 96
          },
          "code": "- Enum 1\n- Enum 2"
        },
        {
          "lookup_key": "mix-list-emum",
          "source_label": "交替有序与无序列表",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-mix-list-emum>)",
            "module": "writing-markup",
            "anchor": "grammar-mix-list-emum"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 99,
            "entry_line_end": 107,
            "code_line_start": 103,
            "code_line_end": 105
          },
          "code": "- Enum 1\n  + Item 1\n- Enum 2"
        },
        {
          "lookup_key": "raw",
          "source_label": "短代码片段",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-raw>)",
            "module": "writing-markup",
            "anchor": "grammar-raw"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 108,
            "entry_line_end": 114,
            "code_line_start": 112,
            "code_line_end": 112
          },
          "code": "`code`"
        },
        {
          "lookup_key": "long-raw",
          "source_label": "长代码片段",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-long-raw>)",
            "module": "writing-markup",
            "anchor": "grammar-long-raw"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 115,
            "entry_line_end": 121,
            "code_line_start": 119,
            "code_line_end": 119
          },
          "code": "``` code```"
        },
        {
          "lookup_key": "lang-raw",
          "source_label": "语法高亮",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-lang-raw>)",
            "module": "writing-markup",
            "anchor": "grammar-lang-raw"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 122,
            "entry_line_end": 128,
            "code_line_start": 126,
            "code_line_end": 126
          },
          "code": "```rs  trait World```"
        },
        {
          "lookup_key": "blocky-raw",
          "source_label": "块代码片段",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-blocky-raw>)",
            "module": "writing-markup",
            "anchor": "grammar-blocky-raw"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 129,
            "entry_line_end": 137,
            "code_line_start": 133,
            "code_line_end": 135
          },
          "code": "```typ\n= Heading\n```"
        },
        {
          "lookup_key": "image",
          "source_label": "图像",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-image>)",
            "module": "writing-markup",
            "anchor": "grammar-image"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 138,
            "entry_line_end": 144,
            "code_line_start": 142,
            "code_line_end": 142
          },
          "code": "#image(\"/assets/files/香風とうふ店.jpg\", width: 50pt)"
        },
        {
          "lookup_key": "image-stretch",
          "source_label": "拉伸图像",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-image-stretch>)",
            "module": "writing-markup",
            "anchor": "grammar-image-stretch"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 145,
            "entry_line_end": 151,
            "code_line_start": 149,
            "code_line_end": 149
          },
          "code": "#image(\"/assets/files/香風とうふ店.jpg\", width: 50pt, height: 50pt, fit: \"stretch\")"
        },
        {
          "lookup_key": "image-inline",
          "source_label": "内联图像（盒子法）",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-image-inline>)",
            "module": "writing-markup",
            "anchor": "grammar-image-inline"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 152,
            "entry_line_end": 158,
            "code_line_start": 156,
            "code_line_end": 156
          },
          "code": "在一段话中插入一个#box(baseline: 0.15em, image(\"/assets/files/info-icon.svg\", width: 1em))图片。"
        },
        {
          "lookup_key": "figure",
          "source_label": "图像标题",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-figure>)",
            "module": "writing-markup",
            "anchor": "grammar-figure"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 159,
            "entry_line_end": 167,
            "code_line_start": 163,
            "code_line_end": 165
          },
          "code": "#figure(```typ\n#image(\"/assets/files/香風とうふ店.jpg\")\n```, caption: [用于加载香風とうふ店送外卖的宝贵影像的代码])"
        },
        {
          "lookup_key": "link",
          "source_label": "链接",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-link>)",
            "module": "writing-markup",
            "anchor": "grammar-link"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 168,
            "entry_line_end": 174,
            "code_line_start": 172,
            "code_line_end": 172
          },
          "code": "#link(\"https://zh.wikipedia.org\")[维基百科]"
        },
        {
          "lookup_key": "http-link",
          "source_label": "HTTP(S)链接",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-http-link>)",
            "module": "writing-markup",
            "anchor": "grammar-http-link"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 175,
            "entry_line_end": 181,
            "code_line_start": 179,
            "code_line_end": 179
          },
          "code": "https://zh.wikipedia.org"
        },
        {
          "lookup_key": "internal-link",
          "source_label": "内部链接",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-internal-link>)",
            "module": "writing-markup",
            "anchor": "grammar-internal-link"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 182,
            "entry_line_end": 189,
            "code_line_start": 186,
            "code_line_end": 187
          },
          "code": "== 某个标题 <ref-internal-link>\n#link(<ref-internal-link>)[链接到某个标题]"
        },
        {
          "lookup_key": "table",
          "source_label": "表格",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-table>)",
            "module": "writing-markup",
            "anchor": "grammar-table"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 190,
            "entry_line_end": 196,
            "code_line_start": 194,
            "code_line_end": 194
          },
          "code": "#table(columns: 2, [111], [2], [3])"
        },
        {
          "lookup_key": "table-align",
          "source_label": "对齐表格",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-table-align>)",
            "module": "writing-markup",
            "anchor": "grammar-table-align"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 197,
            "entry_line_end": 203,
            "code_line_start": 201,
            "code_line_end": 201
          },
          "code": "#table(columns: 2, align: center, [111], [2], [3])"
        },
        {
          "lookup_key": "inline-math",
          "source_label": "行内数学公式",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-inline-math>)",
            "module": "writing-markup",
            "anchor": "grammar-inline-math"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 204,
            "entry_line_end": 210,
            "code_line_start": 208,
            "code_line_end": 208
          },
          "code": "$sum_x$"
        },
        {
          "lookup_key": "display-math",
          "source_label": "行间数学公式",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-display-math>)",
            "module": "writing-markup",
            "anchor": "grammar-display-math"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 211,
            "entry_line_end": 217,
            "code_line_start": 215,
            "code_line_end": 215
          },
          "code": "$ sum_x $"
        },
        {
          "lookup_key": "escape-sequences",
          "source_label": "标记转义序列",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-escape-sequences>)",
            "module": "writing-markup",
            "anchor": "grammar-escape-sequences"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 218,
            "entry_line_end": 224,
            "code_line_start": 222,
            "code_line_end": 222
          },
          "code": ">\\_<"
        },
        {
          "lookup_key": "unicode-escape-sequences",
          "source_label": "标记的Unicode转义序列",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-unicode-escape-sequences>)",
            "module": "writing-markup",
            "anchor": "grammar-unicode-escape-sequences"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 225,
            "entry_line_end": 231,
            "code_line_start": 229,
            "code_line_end": 229
          },
          "code": "\\u{9999}"
        },
        {
          "lookup_key": "newline-by-space",
          "source_label": "换行符（转义序列）",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-newline-by-space>)",
            "module": "writing-markup",
            "anchor": "grammar-newline-by-space"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 232,
            "entry_line_end": 238,
            "code_line_start": 236,
            "code_line_end": 236
          },
          "code": "A \\ B"
        },
        {
          "lookup_key": "newline",
          "source_label": "换行符情形二",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-newline>)",
            "module": "writing-markup",
            "anchor": "grammar-newline"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 239,
            "entry_line_end": 246,
            "code_line_start": 243,
            "code_line_end": 244
          },
          "code": "A \\\nB"
        },
        {
          "lookup_key": "shorthand",
          "source_label": "速记符",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-shorthand>)",
            "module": "writing-markup",
            "anchor": "grammar-shorthand"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 247,
            "entry_line_end": 253,
            "code_line_start": 251,
            "code_line_end": 251
          },
          "code": "北京--上海"
        },
        {
          "lookup_key": "shorthand-space",
          "source_label": "空格（速记符）",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-shorthand-space>)",
            "module": "writing-markup",
            "anchor": "grammar-shorthand-space"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 254,
            "entry_line_end": 260,
            "code_line_start": 258,
            "code_line_end": 258
          },
          "code": "A~B"
        },
        {
          "lookup_key": "inline-comment",
          "source_label": "行内注释",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-inline-comment>)",
            "module": "writing-markup",
            "anchor": "grammar-inline-comment"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 261,
            "entry_line_end": 267,
            "code_line_start": 265,
            "code_line_end": 265
          },
          "code": "// 行内注释"
        },
        {
          "lookup_key": "cross-line-comment",
          "source_label": "行间注释",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-cross-line-comment>)",
            "module": "writing-markup",
            "anchor": "grammar-cross-line-comment"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 268,
            "entry_line_end": 275,
            "code_line_start": 272,
            "code_line_end": 273
          },
          "code": "/* 行间注释\n  */"
        },
        {
          "lookup_key": "box",
          "source_label": "行内盒子",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-box>)",
            "module": "writing-markup",
            "anchor": "grammar-box"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 276,
            "entry_line_end": 282,
            "code_line_start": 280,
            "code_line_end": 280
          },
          "code": "在一段话中插入一个#box(baseline: 0.15em, image(\"/assets/files/info-icon.svg\", width: 1em))图片。"
        }
      ]
    },
    {
      "id": "text-styling",
      "english_heading": "Text Styling",
      "source_heading": "修饰文本",
      "source_anchor": "grammar-table:text",
      "heading_line": 285,
      "entries": [
        {
          "lookup_key": "highlight",
          "source_label": "背景高亮",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-highlight>)",
            "module": "writing-markup",
            "anchor": "grammar-highlight"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 288,
            "entry_line_end": 294,
            "code_line_start": 292,
            "code_line_end": 292
          },
          "code": "#highlight[高亮一段内容]"
        },
        {
          "lookup_key": "underline",
          "source_label": "下划线",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-underline>)",
            "module": "writing-markup",
            "anchor": "grammar-underline"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 295,
            "entry_line_end": 301,
            "code_line_start": 299,
            "code_line_end": 299
          },
          "code": "#underline[Language]"
        },
        {
          "lookup_key": "underline-evade",
          "source_label": "无驱逐效果的下划线",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-underline-evade>)",
            "module": "writing-markup",
            "anchor": "grammar-underline-evade"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 302,
            "entry_line_end": 309,
            "code_line_start": 306,
            "code_line_end": 307
          },
          "code": "#underline(\n  evade: false)[ጿኈቼዽ]"
        },
        {
          "lookup_key": "overline",
          "source_label": "上划线",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-overline>)",
            "module": "writing-markup",
            "anchor": "grammar-overline"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 310,
            "entry_line_end": 316,
            "code_line_start": 314,
            "code_line_end": 314
          },
          "code": "#overline[ጿኈቼዽ]"
        },
        {
          "lookup_key": "strike",
          "source_label": "中划线（删除线）",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-strike>)",
            "module": "writing-markup",
            "anchor": "grammar-strike"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 317,
            "entry_line_end": 323,
            "code_line_start": 321,
            "code_line_end": 321
          },
          "code": "#strike[ጿኈቼዽ]"
        },
        {
          "lookup_key": "subscript",
          "source_label": "下标",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-subscript>)",
            "module": "writing-markup",
            "anchor": "grammar-subscript"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 324,
            "entry_line_end": 330,
            "code_line_start": 328,
            "code_line_end": 328
          },
          "code": "威严满满#sub[抱头蹲防]"
        },
        {
          "lookup_key": "superscript",
          "source_label": "上标",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-superscript>)",
            "module": "writing-markup",
            "anchor": "grammar-superscript"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 331,
            "entry_line_end": 337,
            "code_line_start": 335,
            "code_line_end": 335
          },
          "code": "香風とうふ店#super[TM]"
        },
        {
          "lookup_key": "text-size",
          "source_label": "设置文本大小",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-text-size>)",
            "module": "writing-markup",
            "anchor": "grammar-text-size"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 338,
            "entry_line_end": 344,
            "code_line_start": 342,
            "code_line_end": 342
          },
          "code": "#text(size: 24pt)[一斤鸭梨]"
        },
        {
          "lookup_key": "text-fill",
          "source_label": "设置文本颜色",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-text-fill>)",
            "module": "writing-markup",
            "anchor": "grammar-text-fill"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 345,
            "entry_line_end": 351,
            "code_line_start": 349,
            "code_line_end": 349
          },
          "code": "#text(fill: blue)[蓝色鸭梨]"
        },
        {
          "lookup_key": "text-font",
          "source_label": "设置字体",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-text-font>)",
            "module": "writing-markup",
            "anchor": "grammar-text-font"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 352,
            "entry_line_end": 358,
            "code_line_start": 356,
            "code_line_end": 356
          },
          "code": "#text(font: \"Microsoft YaHei\")[板正鸭梨]"
        }
      ]
    },
    {
      "id": "script-declarations",
      "english_heading": "Script Declarations",
      "source_heading": "脚本声明",
      "source_anchor": "grammar-table:decl",
      "heading_line": 361,
      "entries": [
        {
          "lookup_key": "enter-script",
          "source_label": "进入脚本模式",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-enter-script>)",
            "module": "writing-markup",
            "anchor": "grammar-enter-script"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 364,
            "entry_line_end": 370,
            "code_line_start": 368,
            "code_line_end": 368
          },
          "code": "#1"
        },
        {
          "lookup_key": "code-block",
          "source_label": "代码块",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-code-block>)",
            "module": "writing-markup",
            "anchor": "grammar-code-block"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 371,
            "entry_line_end": 377,
            "code_line_start": 375,
            "code_line_end": 375
          },
          "code": "#{\"a\"; \"b\"}"
        },
        {
          "lookup_key": "content-block",
          "source_label": "内容块",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-content-block>)",
            "module": "writing-markup",
            "anchor": "grammar-content-block"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 378,
            "entry_line_end": 384,
            "code_line_start": 382,
            "code_line_end": 382
          },
          "code": "#[内容块]"
        },
        {
          "lookup_key": "none-literal",
          "source_label": "空字面量",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-none-literal>)",
            "module": "content-scope-style",
            "anchor": "grammar-none-literal"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 385,
            "entry_line_end": 391,
            "code_line_start": 389,
            "code_line_end": 389
          },
          "code": "#none"
        },
        {
          "lookup_key": "false-literal",
          "source_label": "假（布尔值）",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-false-literal>)",
            "module": "content-scope-style",
            "anchor": "grammar-false-literal"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 392,
            "entry_line_end": 398,
            "code_line_start": 396,
            "code_line_end": 396
          },
          "code": "#false"
        },
        {
          "lookup_key": "true-literal",
          "source_label": "真（布尔值）",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-true-literal>)",
            "module": "content-scope-style",
            "anchor": "grammar-true-literal"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 399,
            "entry_line_end": 405,
            "code_line_start": 403,
            "code_line_end": 403
          },
          "code": "#true"
        },
        {
          "lookup_key": "integer-literal",
          "source_label": "整数字面量",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-integer-literal>)",
            "module": "content-scope-style",
            "anchor": "grammar-integer-literal"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 406,
            "entry_line_end": 412,
            "code_line_start": 410,
            "code_line_end": 410
          },
          "code": "#(-1), #(0), #(1)"
        },
        {
          "lookup_key": "n-adecimal-literal",
          "source_label": "进制数字面量",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-n-adecimal-literal>)",
            "module": "content-scope-style",
            "anchor": "grammar-n-adecimal-literal"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 413,
            "entry_line_end": 419,
            "code_line_start": 417,
            "code_line_end": 417
          },
          "code": "#(-0xdeadbeef), #(-0o644), #(-0b1001)"
        },
        {
          "lookup_key": "float-literal",
          "source_label": "浮点数字面量",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-float-literal>)",
            "module": "content-scope-style",
            "anchor": "grammar-float-literal"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 420,
            "entry_line_end": 426,
            "code_line_start": 424,
            "code_line_end": 424
          },
          "code": "#(0.001), #(.1), #(2.)"
        },
        {
          "lookup_key": "exp-repr-float",
          "source_label": "指数表示法",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-exp-repr-float>)",
            "module": "content-scope-style",
            "anchor": "grammar-exp-repr-float"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 427,
            "entry_line_end": 433,
            "code_line_start": 431,
            "code_line_end": 431
          },
          "code": "#(1e2), #(1.926e3), #(-1e-3)"
        },
        {
          "lookup_key": "string-literal",
          "source_label": "字符串字面量",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-string-literal>)",
            "module": "content-scope-style",
            "anchor": "grammar-string-literal"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 434,
            "entry_line_end": 440,
            "code_line_start": 438,
            "code_line_end": 438
          },
          "code": "#\"Hello world!!\""
        },
        {
          "lookup_key": "str-escape-sequences",
          "source_label": "字符串转义序列",
          "reference": {
            "expression": "refs.scripting-base.with(reference: <grammar-str-escape-sequences>)",
            "module": "scripting-base",
            "anchor": "grammar-str-escape-sequences"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 441,
            "entry_line_end": 447,
            "code_line_start": 445,
            "code_line_end": 445
          },
          "code": "#\"\\\"\""
        },
        {
          "lookup_key": "str-unicode-escape-sequences",
          "source_label": "字符串的Unicode转义序列",
          "reference": {
            "expression": "refs.scripting-base.with(reference: <grammar-str-unicode-escape-sequences>)",
            "module": "scripting-base",
            "anchor": "grammar-str-unicode-escape-sequences"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 448,
            "entry_line_end": 454,
            "code_line_start": 452,
            "code_line_end": 452
          },
          "code": "#\"\\u{9999}\""
        },
        {
          "lookup_key": "array-literal",
          "source_label": "数组字面量",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-array-literal>)",
            "module": "content-scope-style",
            "anchor": "grammar-array-literal"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 455,
            "entry_line_end": 461,
            "code_line_start": 459,
            "code_line_end": 459
          },
          "code": "#(1, \"OvO\", [一段内容])"
        },
        {
          "lookup_key": "dict-literal",
          "source_label": "字典字面量",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-dict-literal>)",
            "module": "content-scope-style",
            "anchor": "grammar-dict-literal"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 462,
            "entry_line_end": 468,
            "code_line_start": 466,
            "code_line_end": 466
          },
          "code": "#(neko-mimi: 2, \"utterance\": \"喵喵喵\")"
        },
        {
          "lookup_key": "empty-array",
          "source_label": "空数组",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-empty-array>)",
            "module": "content-scope-style",
            "anchor": "grammar-empty-array"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 469,
            "entry_line_end": 475,
            "code_line_start": 473,
            "code_line_end": 473
          },
          "code": "#()"
        },
        {
          "lookup_key": "empty-dict",
          "source_label": "空字典",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-empty-dict>)",
            "module": "content-scope-style",
            "anchor": "grammar-empty-dict"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 476,
            "entry_line_end": 482,
            "code_line_start": 480,
            "code_line_end": 480
          },
          "code": "#(:)"
        },
        {
          "lookup_key": "paren-empty-array",
          "source_label": "被括号包裹的空数组",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-paren-empty-array>)",
            "module": "content-scope-style",
            "anchor": "grammar-paren-empty-array"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 483,
            "entry_line_end": 489,
            "code_line_start": 487,
            "code_line_end": 487
          },
          "code": "#(())"
        },
        {
          "lookup_key": "single-member-array",
          "source_label": "含有一个元素的数组",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-single-member-array>)",
            "module": "content-scope-style",
            "anchor": "grammar-single-member-array"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 490,
            "entry_line_end": 496,
            "code_line_start": 494,
            "code_line_end": 494
          },
          "code": "#(1,)"
        },
        {
          "lookup_key": "var-decl",
          "source_label": "变量声明",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-var-decl>)",
            "module": "content-scope-style",
            "anchor": "grammar-var-decl"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 497,
            "entry_line_end": 503,
            "code_line_start": 501,
            "code_line_end": 501
          },
          "code": "#let x = 1"
        },
        {
          "lookup_key": "func-decl",
          "source_label": "函数声明",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-func-decl>)",
            "module": "content-scope-style",
            "anchor": "grammar-func-decl"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 504,
            "entry_line_end": 510,
            "code_line_start": 508,
            "code_line_end": 508
          },
          "code": "#let f(x) = x * 2"
        },
        {
          "lookup_key": "closure",
          "source_label": "函数闭包",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-closure>)",
            "module": "content-scope-style",
            "anchor": "grammar-closure"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 511,
            "entry_line_end": 517,
            "code_line_start": 515,
            "code_line_end": 515
          },
          "code": "#let f = (x, y) => x + y"
        },
        {
          "lookup_key": "named-param",
          "source_label": "具名参数声明",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-named-param>)",
            "module": "content-scope-style",
            "anchor": "grammar-named-param"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 518,
            "entry_line_end": 524,
            "code_line_start": 522,
            "code_line_end": 522
          },
          "code": "#let g(named: none) = named"
        },
        {
          "lookup_key": "variadic-param",
          "source_label": "含变参函数",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-variadic-param>)",
            "module": "content-scope-style",
            "anchor": "grammar-variadic-param"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 525,
            "entry_line_end": 531,
            "code_line_start": 529,
            "code_line_end": 529
          },
          "code": "#let g(..args) = args.pos().join([、])"
        },
        {
          "lookup_key": "destruct-array",
          "source_label": "数组解构赋值",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-destruct-array>)",
            "module": "content-scope-style",
            "anchor": "grammar-destruct-array"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 532,
            "entry_line_end": 538,
            "code_line_start": 536,
            "code_line_end": 536
          },
          "code": "#let (one, hello-world) = (1, \"Hello, World\")"
        },
        {
          "lookup_key": "destruct-array-eliminate",
          "source_label": "数组解构赋值情形二",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-destruct-array-eliminate>)",
            "module": "content-scope-style",
            "anchor": "grammar-destruct-array-eliminate"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 539,
            "entry_line_end": 545,
            "code_line_start": 543,
            "code_line_end": 543
          },
          "code": "#let (_, second, ..) = (1, \"Hello, World\", []); #second"
        },
        {
          "lookup_key": "destruct-dict",
          "source_label": "字典解构赋值",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-destruct-dict>)",
            "module": "content-scope-style",
            "anchor": "grammar-destruct-dict"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 546,
            "entry_line_end": 552,
            "code_line_start": 550,
            "code_line_end": 550
          },
          "code": "#let (neko-mimi: mimi) = (neko-mimi: 2); #mimi"
        },
        {
          "lookup_key": "array-remapping",
          "source_label": "数组内容重映射",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-array-remapping>)",
            "module": "content-scope-style",
            "anchor": "grammar-array-remapping"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 553,
            "entry_line_end": 561,
            "code_line_start": 557,
            "code_line_end": 559
          },
          "code": "#let (a, b, c) = (1, 2, 3)\n#let (b, c, a) = (a, b, c)\n#a, #b, #c"
        },
        {
          "lookup_key": "array-swap",
          "source_label": "数组内容交换",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-array-swap>)",
            "module": "content-scope-style",
            "anchor": "grammar-array-swap"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 562,
            "entry_line_end": 570,
            "code_line_start": 566,
            "code_line_end": 568
          },
          "code": "#let (a, b) = (1, 2)\n#((a, b) = (b, a))\n#a, #b"
        },
        {
          "lookup_key": "placeholder",
          "source_label": "占位符（`let _ = ..`）",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-placeholder>)",
            "module": "content-scope-style",
            "anchor": "grammar-placeholder"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 571,
            "entry_line_end": 581,
            "code_line_start": 575,
            "code_line_end": 579
          },
          "code": "#let last-two(t) = {\n  let _ = t.pop()\n  t.pop()\n}\n#last-two((1, 2, 3, 4))"
        }
      ]
    },
    {
      "id": "script-statements",
      "english_heading": "Script Statements",
      "source_heading": "脚本语句",
      "source_anchor": null,
      "heading_line": 584,
      "entries": [
        {
          "lookup_key": "if",
          "source_label": "`if`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-if>)",
            "module": "content-scope-style",
            "anchor": "grammar-if"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 587,
            "entry_line_end": 594,
            "code_line_start": 591,
            "code_line_end": 592
          },
          "code": "#if true { 1 },\n#if false { 1 } else { 0 }"
        },
        {
          "lookup_key": "if-if",
          "source_label": "串联`if`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-if-if>)",
            "module": "content-scope-style",
            "anchor": "grammar-if-if"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 595,
            "entry_line_end": 602,
            "code_line_start": 599,
            "code_line_end": 600
          },
          "code": "#if false { 0 } else if true { 1 },\n#if false { 2 } else if false { 1 } else { 0 }"
        },
        {
          "lookup_key": "while",
          "source_label": "`while`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-while>)",
            "module": "content-scope-style",
            "anchor": "grammar-while"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 603,
            "entry_line_end": 615,
            "code_line_start": 607,
            "code_line_end": 613
          },
          "code": "#{\n  let i = 0;\n  while i < 10 {\n    (i * 2, )\n    i += 1;\n  }\n}"
        },
        {
          "lookup_key": "for",
          "source_label": "`for`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-for>)",
            "module": "content-scope-style",
            "anchor": "grammar-for"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 616,
            "entry_line_end": 624,
            "code_line_start": 620,
            "code_line_end": 622
          },
          "code": "#for i in range(10) {\n  (i * 2, )\n}"
        },
        {
          "lookup_key": "for-destruct",
          "source_label": "`for`语句解构赋值",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-for-destruct>)",
            "module": "content-scope-style",
            "anchor": "grammar-for-destruct"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 625,
            "entry_line_end": 631,
            "code_line_start": 629,
            "code_line_end": 629
          },
          "code": "#for (特色, 这个) in (neko-mimi: 2) [猫猫的 #特色 是 #这个\\ ]"
        },
        {
          "lookup_key": "break",
          "source_label": "`break`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-break>)",
            "module": "content-scope-style",
            "anchor": "grammar-break"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 632,
            "entry_line_end": 638,
            "code_line_start": 636,
            "code_line_end": 636
          },
          "code": "#for i in range(10) { (i, ); (i + 1926, ); break }"
        },
        {
          "lookup_key": "continue",
          "source_label": "`continue`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-continue>)",
            "module": "content-scope-style",
            "anchor": "grammar-continue"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 639,
            "entry_line_end": 648,
            "code_line_start": 643,
            "code_line_end": 646
          },
          "code": "#for i in range(10) {\n  if calc.even(i) { continue }\n  (i, )\n}"
        },
        {
          "lookup_key": "return",
          "source_label": "`return`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-return>)",
            "module": "content-scope-style",
            "anchor": "grammar-return"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 649,
            "entry_line_end": 656,
            "code_line_start": 653,
            "code_line_end": 654
          },
          "code": "#let never(..args) = return\n#type(never(1, 2))"
        },
        {
          "lookup_key": "include",
          "source_label": "`include`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-include>)",
            "module": "content-scope-style",
            "anchor": "grammar-include"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 657,
            "entry_line_end": 663,
            "code_line_start": 661,
            "code_line_end": 661
          },
          "code": "#include \"other-file.typ\""
        }
      ]
    },
    {
      "id": "script-styling",
      "english_heading": "Script Styling",
      "source_heading": "脚本样式",
      "source_anchor": null,
      "heading_line": 666,
      "entries": [
        {
          "lookup_key": "set",
          "source_label": "`set`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-set>)",
            "module": "content-scope-style",
            "anchor": "grammar-set"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 669,
            "entry_line_end": 676,
            "code_line_start": 673,
            "code_line_end": 674
          },
          "code": "#set text(size: 24pt)\n四斤鸭梨"
        },
        {
          "lookup_key": "scope",
          "source_label": "作用域",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-scope>)",
            "module": "content-scope-style",
            "anchor": "grammar-scope"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 677,
            "entry_line_end": 686,
            "code_line_start": 681,
            "code_line_end": 684
          },
          "code": "两只#[兔#set text(fill: rgb(\"#ffd1dc\").darken(15%))\n  #[兔白#set text(fill: orange)\n  又白]，真可爱\n]"
        },
        {
          "lookup_key": "set-if",
          "source_label": "`set if`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-set-if>)",
            "module": "content-scope-style",
            "anchor": "grammar-set-if"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 687,
            "entry_line_end": 696,
            "code_line_start": 691,
            "code_line_end": 694
          },
          "code": "#let is-dark-theme = true\n#set rect(fill: black) if is-dark-theme\n#set text(fill: white) if is-dark-theme\n#rect([wink!])"
        },
        {
          "lookup_key": "show-set",
          "source_label": "`show set`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-show-set>)",
            "module": "content-scope-style",
            "anchor": "grammar-show-set"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 697,
            "entry_line_end": 704,
            "code_line_start": 701,
            "code_line_end": 702
          },
          "code": "#show: set text(fill: blue)\nwink!"
        },
        {
          "lookup_key": "show",
          "source_label": "`show`语句",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-show>)",
            "module": "content-scope-style",
            "anchor": "grammar-show"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 705,
            "entry_line_end": 716,
            "code_line_start": 709,
            "code_line_end": 714
          },
          "code": "#show raw: it => it.lines.at(1)\n获取代码片段第二行内容：```typ\n#{\nset text(fill: true)\n}\n```"
        },
        {
          "lookup_key": "text-selector",
          "source_label": "文本选择器",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-text-selector>)",
            "module": "content-scope-style",
            "anchor": "grammar-text-selector"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 717,
            "entry_line_end": 724,
            "code_line_start": 721,
            "code_line_end": 722
          },
          "code": "#show \"cpp\": strong(emph(box(\"C++\")))\n在古代，cpp是一门常用语言。"
        },
        {
          "lookup_key": "regex-selector",
          "source_label": "正则文本选择器",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-regex-selector>)",
            "module": "content-scope-style",
            "anchor": "grammar-regex-selector"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 725,
            "entry_line_end": 735,
            "code_line_start": 729,
            "code_line_end": 733
          },
          "code": "#show regex(\"[”。]+\"): it => {\n  set text(font: \"KaiTi\")\n  highlight(it, fill: yellow)\n}\n“无名，万物之始也；有名，万物之母也。”"
        },
        {
          "lookup_key": "label-selector",
          "source_label": "标签选择器",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-label-selector>)",
            "module": "content-scope-style",
            "anchor": "grammar-label-selector"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 736,
            "entry_line_end": 745,
            "code_line_start": 740,
            "code_line_end": 743
          },
          "code": "#show <一整段话>: set text(fill: blue)\n#[$lambda$语言是世界上最好的语言。] <一整段话>\n\n另一段话。"
        },
        {
          "lookup_key": "selector-exp",
          "source_label": "选择器表达式",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-selector-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-selector-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 746,
            "entry_line_end": 754,
            "code_line_start": 750,
            "code_line_end": 752
          },
          "code": "#show heading.where(level: 2): set text(fill: blue)\n= 一级标题\n== 二级标题"
        },
        {
          "lookup_key": "here",
          "source_label": "获取位置",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-here>)",
            "module": "content-scope-style",
            "anchor": "grammar-here"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 755,
            "entry_line_end": 761,
            "code_line_start": 759,
            "code_line_end": 759
          },
          "code": "#context here().position()"
        },
        {
          "lookup_key": "here-calc",
          "source_label": "检测当前页面是否为偶数页（位置相关计算）",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-here-calc>)",
            "module": "content-scope-style",
            "anchor": "grammar-here-calc"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 762,
            "entry_line_end": 768,
            "code_line_start": 766,
            "code_line_end": 766
          },
          "code": "#context [ 页码是偶数：#calc.even(here().page()) ]"
        },
        {
          "lookup_key": "query",
          "source_label": "查询文档内容",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-query>)",
            "module": "content-scope-style",
            "anchor": "grammar-query"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 769,
            "entry_line_end": 775,
            "code_line_start": 773,
            "code_line_end": 773
          },
          "code": "#context query(<ref-internal-link>).at(0).body"
        },
        {
          "lookup_key": "state",
          "source_label": "声明全局状态",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-state>)",
            "module": "content-scope-style",
            "anchor": "grammar-state"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 776,
            "entry_line_end": 782,
            "code_line_start": 780,
            "code_line_end": 780
          },
          "code": "#state(\"my-state\", 1)"
        }
      ]
    },
    {
      "id": "script-expressions",
      "english_heading": "Script Expressions",
      "source_heading": "脚本表达式",
      "source_anchor": null,
      "heading_line": 785,
      "entries": [
        {
          "lookup_key": "func-call",
          "source_label": "函数调用",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-func-call>)",
            "module": "writing-markup",
            "anchor": "grammar-func-call"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 788,
            "entry_line_end": 794,
            "code_line_start": 792,
            "code_line_end": 792
          },
          "code": "#calc.pow(4, 3)"
        },
        {
          "lookup_key": "content-param",
          "source_label": "函数调用传递内容参数",
          "reference": {
            "expression": "refs.writing-markup.with(reference: <grammar-content-param>)",
            "module": "writing-markup",
            "anchor": "grammar-content-param"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 795,
            "entry_line_end": 801,
            "code_line_start": 799,
            "code_line_end": 799
          },
          "code": "#emph[emphasis]"
        },
        {
          "lookup_key": "member-exp",
          "source_label": "成员访问",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-member-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-member-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 802,
            "entry_line_end": 808,
            "code_line_start": 806,
            "code_line_end": 806
          },
          "code": "#`OvO`.text"
        },
        {
          "lookup_key": "method-exp",
          "source_label": "方法调用",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-method-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-method-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 809,
            "entry_line_end": 815,
            "code_line_start": 813,
            "code_line_end": 813
          },
          "code": "#\"Hello World\".split(\" \")"
        },
        {
          "lookup_key": "dict-member-exp",
          "source_label": "字典成员访问",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-dict-member-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-dict-member-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 816,
            "entry_line_end": 823,
            "code_line_start": 820,
            "code_line_end": 821
          },
          "code": "#let cat = (neko-mimi: 2)\n#cat.neko-mimi"
        },
        {
          "lookup_key": "content-member-exp",
          "source_label": "内容成员访问",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-content-member-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-content-member-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 824,
            "entry_line_end": 830,
            "code_line_start": 828,
            "code_line_end": 828
          },
          "code": "#`OvO`.text"
        },
        {
          "lookup_key": "repr",
          "source_label": "代码表示的自省函数",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-repr>)",
            "module": "content-scope-style",
            "anchor": "grammar-repr"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 831,
            "entry_line_end": 837,
            "code_line_start": 835,
            "code_line_end": 835
          },
          "code": "#repr[ 一段文本 ]"
        },
        {
          "lookup_key": "type",
          "source_label": "类型的自省函数",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-type>)",
            "module": "content-scope-style",
            "anchor": "grammar-type"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 838,
            "entry_line_end": 844,
            "code_line_start": 842,
            "code_line_end": 842
          },
          "code": "#type[一段文本]"
        },
        {
          "lookup_key": "eval",
          "source_label": "求值函数",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-eval>)",
            "module": "content-scope-style",
            "anchor": "grammar-eval"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 845,
            "entry_line_end": 851,
            "code_line_start": 849,
            "code_line_end": 849
          },
          "code": "#type(eval(\"1\"))"
        },
        {
          "lookup_key": "eval-markup-mode",
          "source_label": "求值函数（标记模式）",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-eval-markup-mode>)",
            "module": "content-scope-style",
            "anchor": "grammar-eval-markup-mode"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 852,
            "entry_line_end": 858,
            "code_line_start": 856,
            "code_line_end": 856
          },
          "code": "#eval(\"== 一个标题\", mode: \"markup\")"
        },
        {
          "lookup_key": "array-in",
          "source_label": "判断数组内容",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-array-in>)",
            "module": "content-scope-style",
            "anchor": "grammar-array-in"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 859,
            "entry_line_end": 866,
            "code_line_start": 863,
            "code_line_end": 864
          },
          "code": "#let pol = (1, \"OvO\", [])\n#(1 in pol)"
        },
        {
          "lookup_key": "array-not-in",
          "source_label": "判断数组内容不在",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-array-not-in>)",
            "module": "content-scope-style",
            "anchor": "grammar-array-not-in"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 867,
            "entry_line_end": 874,
            "code_line_start": 871,
            "code_line_end": 872
          },
          "code": "#let pol = (1, \"OvO\", [])\n#([另一段内容] not in pol)"
        },
        {
          "lookup_key": "dict-in",
          "source_label": "判断字典内容",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-dict-in>)",
            "module": "content-scope-style",
            "anchor": "grammar-dict-in"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 875,
            "entry_line_end": 882,
            "code_line_start": 879,
            "code_line_end": 880
          },
          "code": "#let cat = (neko-mimi: 2)\n#(\"neko-mimi\" in cat)"
        },
        {
          "lookup_key": "logical-cmp-exp",
          "source_label": "逻辑比较表达式",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-logical-cmp-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-logical-cmp-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 883,
            "entry_line_end": 890,
            "code_line_start": 887,
            "code_line_end": 888
          },
          "code": "#(1 < 0), #(1 >= 2),\n#(1 == 2), #(1 != 2)"
        },
        {
          "lookup_key": "logical-calc-exp",
          "source_label": "逻辑运算表达式",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-logical-calc-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-logical-calc-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 891,
            "entry_line_end": 897,
            "code_line_start": 895,
            "code_line_end": 895
          },
          "code": "#(not false), #(false or true), #(true and false)"
        },
        {
          "lookup_key": "plus-exp",
          "source_label": "取正运算",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-plus-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-plus-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 898,
            "entry_line_end": 904,
            "code_line_start": 902,
            "code_line_end": 902
          },
          "code": "#(+1), #(+0), #(1), #(++1)"
        },
        {
          "lookup_key": "minus-exp",
          "source_label": "取负运算",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-minus-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-minus-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 905,
            "entry_line_end": 912,
            "code_line_start": 909,
            "code_line_end": 910
          },
          "code": "#(-1), #(-0), #(--1),\n#(-+-1)"
        },
        {
          "lookup_key": "arith-exp",
          "source_label": "算术运算表达式",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-arith-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-arith-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 913,
            "entry_line_end": 920,
            "code_line_start": 917,
            "code_line_end": 918
          },
          "code": "#(1 + 1), #(1 + -1),\n#(1 - 1), #(1 - -1)"
        },
        {
          "lookup_key": "assign-exp",
          "source_label": "赋值表达式",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-assign-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-assign-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 921,
            "entry_line_end": 927,
            "code_line_start": 925,
            "code_line_end": 925
          },
          "code": "#let a = 1; #repr(a = 10), #a, #repr(a += 2), #a"
        },
        {
          "lookup_key": "string-concat-exp",
          "source_label": "字符串连接",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-string-concat-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-string-concat-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 928,
            "entry_line_end": 934,
            "code_line_start": 932,
            "code_line_end": 932
          },
          "code": "#(\"a\" + \"b\")"
        },
        {
          "lookup_key": "string-mul-exp",
          "source_label": "重复连接字符串",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-string-mul-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-string-mul-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 935,
            "entry_line_end": 941,
            "code_line_start": 939,
            "code_line_end": 939
          },
          "code": "#(\"a\" * 4), #(4 * \"ab\")"
        },
        {
          "lookup_key": "string-cmp-exp",
          "source_label": "字符串比较",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-string-cmp-exp>)",
            "module": "content-scope-style",
            "anchor": "grammar-string-cmp-exp"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 942,
            "entry_line_end": 948,
            "code_line_start": 946,
            "code_line_end": 946
          },
          "code": "#(\"a\" == \"b\"), #(\"a\" != \"b\"), #(\"a\" < \"ab\"), #(\"a\" >= \"a\")"
        },
        {
          "lookup_key": "int-to-float",
          "source_label": "整数转浮点数",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-int-to-float>)",
            "module": "content-scope-style",
            "anchor": "grammar-int-to-float"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 949,
            "entry_line_end": 955,
            "code_line_start": 953,
            "code_line_end": 953
          },
          "code": "#float(1), #(type(float(1)))"
        },
        {
          "lookup_key": "bool-to-int",
          "source_label": "布尔值转整数",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-bool-to-int>)",
            "module": "content-scope-style",
            "anchor": "grammar-bool-to-int"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 956,
            "entry_line_end": 962,
            "code_line_start": 960,
            "code_line_end": 960
          },
          "code": "#int(true), #(type(int(true)))"
        },
        {
          "lookup_key": "float-to-int",
          "source_label": "浮点数转整数",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-float-to-int>)",
            "module": "content-scope-style",
            "anchor": "grammar-float-to-int"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 963,
            "entry_line_end": 969,
            "code_line_start": 967,
            "code_line_end": 967
          },
          "code": "#int(1), #(type(int(1)))"
        },
        {
          "lookup_key": "dec-str-to-int",
          "source_label": "十进制字符串转整数",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-dec-str-to-int>)",
            "module": "content-scope-style",
            "anchor": "grammar-dec-str-to-int"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 970,
            "entry_line_end": 976,
            "code_line_start": 974,
            "code_line_end": 974
          },
          "code": "#int(\"1\"), #(type(int(\"1\")))"
        },
        {
          "lookup_key": "nadec-str-to-int",
          "source_label": "十六进制/八进制/二进制字符串转整数",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-nadec-str-to-int>)",
            "module": "content-scope-style",
            "anchor": "grammar-nadec-str-to-int"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 977,
            "entry_line_end": 990,
            "code_line_start": 981,
            "code_line_end": 988
          },
          "code": "#let safe-to-int(x) = {\n  let res = eval(x)\n  assert(type(res) == int, message: \"should be integer\")\n  res\n}\n#safe-to-int(\"0xf\"), #(type(safe-to-int(\"0xf\"))) \\\n#safe-to-int(\"0o755\"), #(type(safe-to-int(\"0o755\"))) \\\n#safe-to-int(\"0b1011\"), #(type(safe-to-int(\"0b1011\"))) \\"
        },
        {
          "lookup_key": "num-to-str",
          "source_label": "数字转字符串",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-num-to-str>)",
            "module": "content-scope-style",
            "anchor": "grammar-num-to-str"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 991,
            "entry_line_end": 998,
            "code_line_start": 995,
            "code_line_end": 996
          },
          "code": "#repr(str(1)),\n#repr(str(.5))"
        },
        {
          "lookup_key": "int-to-nadec-str",
          "source_label": "整数转十六进制字符串",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-int-to-nadec-str>)",
            "module": "content-scope-style",
            "anchor": "grammar-int-to-nadec-str"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 999,
            "entry_line_end": 1005,
            "code_line_start": 1003,
            "code_line_end": 1003
          },
          "code": "#str(501, base:16), #str(0xdeadbeef, base:36)"
        },
        {
          "lookup_key": "bool-to-str",
          "source_label": "布尔值转字符串",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-bool-to-str>)",
            "module": "content-scope-style",
            "anchor": "grammar-bool-to-str"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 1006,
            "entry_line_end": 1012,
            "code_line_start": 1010,
            "code_line_end": 1010
          },
          "code": "#repr(false)"
        },
        {
          "lookup_key": "int-to-bool",
          "source_label": "数字转布尔值",
          "reference": {
            "expression": "refs.content-scope-style.with(reference: <grammar-int-to-bool>)",
            "module": "content-scope-style",
            "anchor": "grammar-int-to-bool"
          },
          "source": {
            "path": "src/tutorial/reference-grammar.typ",
            "entry_line_start": 1013,
            "entry_line_end": 1021,
            "code_line_start": 1017,
            "code_line_end": 1019
          },
          "code": "#let to-bool(x) = x != 0\n#repr(to-bool(0)),\n#repr(to-bool(1))"
        }
      ]
    }
  ]
}


================================================
FILE: .codex/skills/update-typst-grammar-authoring/scripts/generate_grammar_catalog.py
================================================
#!/usr/bin/env python3
"""Generate Typst grammar data and sync it into the portable skill."""

from __future__ import annotations

import argparse
import json
import os
import re
import sys
import textwrap
from collections import OrderedDict
from pathlib import Path


CATEGORY_MAP = {
    "基本元素": {
        "id": "base-elements",
        "title": "Base Elements",
    },
    "修饰文本": {
        "id": "text-styling",
        "title": "Text Styling",
    },
    "脚本声明": {
        "id": "script-declarations",
        "title": "Script Declarations",
    },
    "脚本语句": {
        "id": "script-statements",
        "title": "Script Statements",
    },
    "脚本样式": {
        "id": "script-styling",
        "title": "Script Styling",
    },
    "脚本表达式": {
        "id": "script-expressions",
        "title": "Script Expressions",
    },
}

CATEGORY_PATTERN = re.compile(
    r"^==\s+分类：(?P<source_heading>.+?)(?:\s+<(?P<source_anchor>[^>]+)>)?\s*$",
    re.MULTILINE,
)

ENTRY_PATTERN = re.compile(
    r"""
    \(\s*\n
    \s*\[(?P<source_label>.*?)\],\s*\n
    \s*(?P<reference_expr>refs\.(?P<reference_module>[\w-]+)\.with\(reference:\s*<(?P<reference_anchor>[^>]+)>\)),\s*\n
    \s*`{3,4}typ\s*\n
    (?P<code>.*?)
    \n\s*`{3,4},\s*\n
    \s*\),
    """,
    re.DOTALL | re.VERBOSE,
)

GENERATED_BEGIN = "<!-- BEGIN GENERATED GRAMMAR LOOKUP -->"
GENERATED_END = "<!-- END GENERATED GRAMMAR LOOKUP -->"
INLINE_CODE_LIMIT = 88


def line_number(text: str, offset: int) -> int:
    return text.count("\n", 0, offset) + 1


def normalize_code(raw_code: str) -> str:
    return textwrap.dedent(raw_code).strip("\n")


def lookup_key(reference_anchor: str) -> str:
    prefix = "grammar-"
    if reference_anchor.startswith(prefix):
        return reference_anchor[len(prefix) :]
    return reference_anchor


def repo_relative(path: Path, repo_root: Path) -> str:
    try:
        return Path(os.path.relpath(path.resolve(), repo_root.resolve())).as_posix()
    except ValueError:
        return path.resolve().as_posix()


def parse_categories(
    source_text: str, source_path: Path, repo_root: Path
) -> list[dict]:
    categories = []
    category_matches = list(CATEGORY_PATTERN.finditer(source_text))
    if not category_matches:
        raise ValueError(f"No categories found in {source_path}")

    for index, match in enumerate(category_matches):
        section_start = match.end()
        section_end = (
            category_matches[index + 1].start()
            if index + 1 < len(category_matches)
            else len(source_text)
        )
        section_text = source_text[section_start:section_end]
        source_heading = match.group("source_heading")
        english_heading = CATEGORY_MAP.get(source_heading, {}).get(
            "title", source_heading
        )
        category_id = CATEGORY_MAP.get(source_heading, {}).get(
            "id",
            f"category-{index + 1}",
        )
        category = {
            "id": category_id,
            "english_heading": english_heading,
            "source_heading": source_heading,
            "source_anchor": match.group("source_anchor"),
            "heading_line": line_number(source_text, match.start()),
            "entries": [],
        }

        for entry_match in ENTRY_PATTERN.finditer(section_text):
            absolute_start = section_start + entry_match.start()
            absolute_end = section_start + entry_match.end()
            code_start = section_start + entry_match.start("code")
            code_end = section_start + entry_match.end("code")
            entry = {
                "lookup_key": lookup_key(entry_match.group("reference_anchor")),
                "source_label": entry_match.group("source_label").strip(),
                "reference": {
                    "expression": entry_match.group("reference_expr").strip(),
                    "module": entry_match.group("reference_module"),
                    "anchor": entry_match.group("reference_anchor"),
                },
                "source": {
                    "path": repo_relative(source_path, repo_root),
                    "entry_line_start": line_number(source_text, absolute_start),
                    "entry_line_end": line_number(source_text, absolute_end),
                    "code_line_start": line_number(source_text, code_start),
                    "code_line_end": line_number(source_text, code_end),
                },
                "code": normalize_code(entry_match.group("code")),
            }
            category["entries"].append(entry)

        if not category["entries"]:
            raise ValueError(
                f"No entries parsed for category '{source_heading}' in {source_path}"
            )

        categories.append(category)

    return categories


def build_catalog(source_path: Path, repo_root: Path) -> dict:
    source_text = source_path.read_text(encoding="utf-8")
    categories = parse_categories(source_text, source_path, repo_root)
    return {
        "source_path": repo_relative(source_path, repo_root),
        "category_count": len(categories),
        "entry_count": sum(len(category["entries"]) for category in categories),
        "categories": categories,
    }


def is_inline_safe(code: str) -> bool:
    return "\n" not in code and "`" not in code and len(code) <= INLINE_CODE_LIMIT


def grouped_entries(entries: list[dict]) -> list[dict]:
    groups: OrderedDict[str, list[str]] = OrderedDict()
    for entry in entries:
        groups.setdefault(entry["lookup_key"], [])
        if entry["code"] not in groups[entry["lookup_key"]]:
            groups[entry["lookup_key"]].append(entry["code"])
    return [
        {
            "lookup_key": lookup_key,
            "examples": examples,
        }
        for lookup_key, examples in groups.items()
    ]


def render_example_block(code: str) -> list[str]:
    return [
        "```typ",
        code,
        "```",
    ]


def render_skill_lookup(catalog: dict) -> str:
    lines: list[str] = []
    for category in catalog["categories"]:
        lines.extend(
            [
                f"### {category['english_heading']}",
                "",
            ]
        )
        for group in grouped_entries(category["entries"]):
            inline_examples = [
                code for code in group["examples"] if is_inline_safe(code)
            ]
            if len(inline_examples) == len(group["examples"]):
                joined = "; ".join(f"`{code}`" for code in inline_examples)
                lines.append(f"- `{group['lookup_key']}`: {joined}")
                continue

            lines.append(f"- `{group['lookup_key']}`:")
            lines.append("")
            for index, code in enumerate(group["examples"]):
                lines.extend(render_example_block(code))
                if index != len(group["examples"]) - 1:
                    lines.append("")
            lines.append("")

    while lines and not lines[-1]:
        lines.pop()
    return "\n".join(lines) + "\n"


def update_skill(skill_path: Path, generated_lookup: str) -> None:
    skill_text = skill_path.read_text(encoding="utf-8")
    pattern = re.compile(
        rf"{re.escape(GENERATED_BEGIN)}(?P<newline>\r?\n).*?{re.escape(GENERATED_END)}",
        re.DOTALL,
    )

    def _replacement(match: re.Match[str]) -> str:
        newline = match.group("newline")
        return f"{GENERATED_BEGIN}{newline}{generated_lookup}{GENERATED_END}"

    updated_text, count = pattern.subn(_replacement, skill_text, count=1)
    if count != 1:
        raise ValueError(f"Could not find generated section markers in {skill_path}")
    skill_path.write_text(updated_text, encoding="utf-8")


def write_outputs(
    catalog: dict,
    output_dir: Path,
    skill_path: Path,
) -> None:
    output_dir.mkdir(parents=True, exist_ok=True)
    json_path = output_dir / "grammar-catalog.json"
    json_path.write_text(
        json.dumps(catalog, indent=2, ensure_ascii=False) + "\n",
        encoding="utf-8",
    )
    update_skill(skill_path, render_skill_lookup(catalog))
    print(f"[OK] Wrote {json_path}")
    print(f"[OK] Updated {skill_path}")


def default_source(script_path: Path) -> Path:
    return script_path.parents[4] / "src" / "tutorial" / "reference-grammar.typ"


def default_skill_path(script_path: Path) -> Path:
    return script_path.parents[2] / "typst-grammar-authoring" / "SKILL.md"


def main() -> int:
    script_path = Path(__file__).resolve()
    parser = argparse.ArgumentParser(
        description="Generate Typst grammar data from reference-grammar.typ.",
    )
    parser.add_argument(
        "--source",
        type=Path,
        default=default_source(script_path),
        help="Path to src/tutorial/reference-grammar.typ",
    )
    parser.add_argument(
        "--output-dir",
        type=Path,
        default=script_path.parent.parent / "references",
        help="Directory for generated reference files",
    )
    parser.add_argument(
        "--skill-path",
        type=Path,
        default=default_skill_path(script_path),
        help="Path to the portable SKILL.md file to sync",
    )
    args = parser.parse_args()

    try:
        repo_root = script_path.parents[4]
        source_path = args.source.resolve()
        catalog = build_catalog(source_path, repo_root)
        write_outputs(
            catalog,
            args.output_dir.resolve(),
            args.skill_path.resolve(),
        )
    except Exception as exc:  # pragma: no cover - CLI error surface
        print(f"[ERROR] {exc}", file=sys.stderr)
        return 1

    return 0


if __name__ == "__main__":
    raise SystemExit(main())


================================================
FILE: .gitattributes
================================================
.zed/settings.json linguist-language=json5

================================================
FILE: .github/workflows/build.yml
================================================
name: tutorial::ci
on: push
jobs:
  render_pdf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: typst-community/setup-typst@v3
      - run: git submodule update --init --recursive
      - name: Download & install shiroa
        run: |
          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Myriad-Dreamin/shiroa/releases/download/v0.3.1-rc2/shiroa-installer.sh | sh
      - name: Build Book
        run: |
          shiroa build --font-path ./assets/typst-fonts/ --font-path ./assets/fonts/ --path-to-root /tutorial/ -w . src
      - run: typst compile --root . --font-path ./assets/typst-fonts/ --font-path ./assets/fonts/ ./src/ebook.typ
      - uses: actions/upload-artifact@v4
        id: artifact-upload-step
        with:
          name: ebook
          path: src/ebook.pdf
      - run: echo 'Artifact URL is ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts/${{ steps.artifact-upload-step.outputs.artifact-id }}'


================================================
FILE: .github/workflows/gh_pages.yml
================================================
name: tutorial::gh_pages
on:
  push:
    branches:
      - main
  workflow_dispatch:
    
permissions:
  pages: write
  id-token: write
  contents: read

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: 'pages'
  cancel-in-progress: false

jobs:
  build-gh-pages:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - run: git submodule update --init --recursive
      - name: Download font assets
        # use fonts in stable releases
        run: |
          mkdir -p assets/fonts/
          curl -L https://github.com/Myriad-Dreamin/shiroa/releases/download/v0.1.2/font-assets.tar.gz | tar -xvz -C assets/fonts
      - name: Download & install shiroa
        run: |
          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Myriad-Dreamin/shiroa/releases/download/v0.3.1-rc2/shiroa-installer.sh | sh
      - name: Build Book
        run: |
          shiroa build --font-path ./assets/typst-fonts/ --font-path ./assets/fonts/ --path-to-root /tutorial/ -w . src 
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: "./dist"
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

================================================
FILE: .gitignore
================================================
dist/
target/
.DS_Store
src/*.pdf
.idea


================================================
FILE: .gitmodules
================================================
[submodule "assets/typst-fonts"]
	path = assets/typst-fonts
	url = https://github.com/typst-doc-cn/fonts
	branch = typst-v0.10.0
[submodule "assets/artifacts"]
	path = assets/artifacts
	url = https://github.com/typst-doc-cn/tutorial-artifacts
	branch = v0.1.0
[submodule "assets/fonts"]
	path = assets/fonts
	url = https://github.com/typst-doc-cn/fonts
	branch = tutorial-v0.1.0


================================================
FILE: .vscode/settings.json
================================================
{
  "tinymist.fontPaths": ["${workspaceFolder}/assets/fonts"],
  "tinymist.exportPdf": "onSave",
  "tinymist.outputPath": "$root/target/$dir/$name",
  "tinymist.formatterMode": "typstyle",
  "editor.pasteAs.preferences": [
    "typst.link.uri",
    "typst.link.image",
    "typst.link"
  ],
  "tinymist.preview.invertColors": "auto",
  "tinymist.lint.enabled": true,
  "tinymist.lint.when": "onSave",
  "[typst]": {
    "editor.inlayHints.enabled": "off"
  },
  "files.watcherExclude": {
    "**/target": true
  }
}


================================================
FILE: .zed/settings.json
================================================
// Folder-specific settings
//
// For a full list of overridable settings, and general information on folder-specific settings,
// see the documentation: https://zed.dev/docs/configuring-zed#settings-files
{
  "lsp": {
    "tinymist": {
      "initialization_options": {
        "exportPdf": "onSave",
        "outputPath": "$root/target/typst/$name"
      }
    }
  }
}


================================================
FILE: Cargo.toml
================================================
[workspace.package]
description = "The Raindrop Book - Typst中文教程"
authors = ["Myriad-Dreamin <camiyoru@gmail.com>"]
version = "0.1.0"
edition = "2021"
readme = "README.md"
license = "Apache-2.0"
homepage = "https://github.com/typst-doc-cn/tutorial"
repository = "https://github.com/typst-doc-cn/tutorial"

[workspace]
resolver = "2"
members = ["crates/*"]

[workspace.dependencies]
typst = "0.13.1"
typst-svg = "0.13.1"

serde_json = "1"

reflexo-typst = { version = "0.6.0-rc1", default-features = false }

[profile.release]
# to satisfy stubber
lto = false       # Enable link-time optimization
strip = true      # Strip symbols from binary*
opt-level = 3     # Optimize for speed
codegen-units = 2 # Reduce number of codegen units to increase optimizations
panic = 'abort'   # Abort on panic

[patch.crates-io]
typst = { git = "https://github.com/Myriad-Dreamin/typst.git", tag = "typst.ts/v0.6.0-rc1" }
typst-library = { git = "https://github.com/Myriad-Dreamin/typst.git", tag = "typst.ts/v0.6.0-rc1" }
typst-syntax = { git = "https://github.com/Myriad-Dreamin/typst.git", tag = "typst.ts/v0.6.0-rc1" }
typst-utils = { git = "https://github.com/Myriad-Dreamin/typst.git", tag = "typst.ts/v0.6.0-rc1" }
typst-svg = { git = "https://github.com/Myriad-Dreamin/typst.git", tag = "typst.ts/v0.6.0-rc1" }
# reflexo-typst = { git = "https://github.com/Myriad-Dreamin/typst.ts", tag = "v0.5.5-rc7" }
# typst-ts-core = { path = "../../rust/typst.ts/core" }
# typst-ts-compiler = { path = "../../rust/typst.ts/compiler" }

[workspace.lints.rust]
missing_docs = "warn"

[workspace.lints.clippy]
uninlined_format_args = "warn"
missing_safety_doc = "warn"
undocumented_unsafe_blocks = "warn"


================================================
FILE: LICENSE
================================================
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


================================================
FILE: README.md
================================================
# Tutorial

Typst 中文教程

[![下载最新版本](https://custom-icon-badges.demolab.com/badge/-Download-blue?style=for-the-badge&logo=download&logoColor=white "下载最新版本")](https://nightly.link/typst-doc-cn/tutorial/workflows/build/main/ebook.zip) **(latest 版本)**

[![下载最新版本](https://custom-icon-badges.demolab.com/badge/-Download-blue?style=for-the-badge&logo=download&logoColor=white "下载最新版本")](https://github.com/typst-doc-cn/tutorial/releases/download/v0.1.0/Typst.Tutorial.CN.v0.1.0.pdf) **(0.1.0 版本)**

## 安装字体

```bash
git submodule update --init --recursive
```

## 托管为静态网站

```bash
shiroa serve --font-path ./assets/typst-fonts/ --font-path ./assets/fonts/ -w . ./src/
```

## 编译为静态网站

```bash
shiroa build --font-path ./assets/typst-fonts/ --font-path ./assets/fonts/ -w . ./src/
```

## 编译电子书

```bash
typst compile --root . --font-path ./assets/typst-fonts/ --font-path ./assets/fonts/ ./src/ebook.typ
```

## 编译单独章节

选择一个章节文件，比如 `第一章.typ`，然后执行：

```bash
typst compile --root . --font-path ./assets/typst-fonts/ --font-path ./assets/fonts/ 章节文件.typ
```

## 复现 Artifacts

生成`typst-docs-v0.11.0.json`：

```bash
cargo install --git https://github.com/typst/typst --locked typst-docs --features="cli" --tag v0.11.0
typst-docs --out-file ./assets/artifacts/typst-docs-v0.11.0.json --assets-dir target/typst-docs/assets
```


================================================
FILE: _typos.toml
================================================
[default]
extend-ignore-identifiers-re = ["typ", "typc", "typm"]


================================================
FILE: assets/files/tokyo-night.tmTheme
================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>name</key>
    <string>Tokyo Night</string>
    <key>settings</key>
    <array>
      <dict>
        <key>settings</key>
        <dict>
          <key>caret</key>
          <string>#c0caf5</string>
          <key>selection</key>
          <string>#515c7e4d</string>
          <key>lineHighlight</key>
          <string>#1e202e</string>
          <key>foreground</key>
          <string>#a9b1d6</string>
          <key>background</key>
          <string>#1a1b26</string>
          <key>invisibles</key>
          <string>#363b54</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Italics - Comments, Storage, Keyword Flow, Vue attributes, Decorators</string>
        <key>scope</key>
        <string>comment,meta.var.expr storage.type,keyword.control.flow,keyword.control.return,meta.directive.vue punctuation.separator.key-value.html,meta.directive.vue entity.other.attribute-name.html,tag.decorator.js entity.name.tag.js,tag.decorator.js punctuation.definition.tag.js,storage.modifier</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>italic</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Fix YAML block scalar</string>
        <key>scope</key>
        <string>keyword.control.flow.block-scalar.literal</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string/>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Comment</string>
        <key>scope</key>
        <string>comment,comment.block.documentation,punctuation.definition.comment,comment.block.documentation punctuation</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#444b6a</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Comment Doc</string>
        <key>scope</key>
        <string>keyword.operator.assignment.jsdoc,comment.block.documentation variable,comment.block.documentation storage,comment.block.documentation keyword,comment.block.documentation support,comment.block.documentation markup,comment.block.documentation markup.inline.raw.string.markdown,meta.other.type.phpdoc.php keyword.other.type.php,meta.other.type.phpdoc.php support.other.namespace.php,meta.other.type.phpdoc.php punctuation.separator.inheritance.php,meta.other.type.phpdoc.php support.class,keyword.other.phpdoc.php,log.date</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#5a638c</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Comment Doc Emphasized</string>
        <key>scope</key>
        <string>meta.other.type.phpdoc.php support.class,comment.block.documentation storage.type,comment.block.documentation punctuation.definition.block.tag,comment.block.documentation entity.name.type.instance</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#646e9c</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Number, Boolean, Undefined, Null</string>
        <key>scope</key>
        <string>variable.other.constant,punctuation.definition.constant,constant.language,constant.numeric,support.constant</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#ff9e64</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>String, Symbols</string>
        <key>scope</key>
        <string>string,constant.other.symbol,constant.other.key,meta.attribute-selector</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string/>
          <key>foreground</key>
          <string>#9ece6a</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Colors</string>
        <key>scope</key>
        <string>constant.other.color,constant.other.color.rgb-value.hex punctuation.definition.constant</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9aa5ce</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Invalid</string>
        <key>scope</key>
        <string>invalid,invalid.illegal</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#ff5370</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Invalid deprecated</string>
        <key>scope</key>
        <string>invalid.deprecated</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Storage Type</string>
        <key>scope</key>
        <string>storage.type</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Storage - modifier, var, const, let</string>
        <key>scope</key>
        <string>meta.var.expr storage.type,storage.modifier</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9d7cd8</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Interpolation, PHP tags, Smarty tags</string>
        <key>scope</key>
        <string>punctuation.definition.template-expression,punctuation.section.embedded,meta.embedded.line.tag.smarty,support.constant.handlebars,punctuation.section.tag.twig</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7dcfff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Blade, Twig, Smarty Handlebars keywords</string>
        <key>scope</key>
        <string>keyword.control.smarty,keyword.control.twig,support.constant.handlebars keyword.control,keyword.operator.comparison.twig,keyword.blade,entity.name.function.blade</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#0db9d7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Spread</string>
        <key>scope</key>
        <string>keyword.operator.spread,keyword.operator.rest</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
          <key>fontStyle</key>
          <string>bold</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Operator, Misc</string>
        <key>scope</key>
        <string>keyword.operator,keyword.control.as,keyword.other,keyword.operator.bitwise.shift,punctuation,expression.embbeded.vue punctuation.definition.tag,text.html.twig meta.tag.inline.any.html,meta.tag.template.value.twig meta.function.arguments.twig,meta.directive.vue punctuation.separator.key-value.html,punctuation.definition.constant.markdown,punctuation.definition.string,punctuation.support.type.property-name,text.html.vue-html meta.tag,meta.attribute.directive,punctuation.definition.keyword,punctuation.terminator.rule,punctuation.definition.entity,punctuation.separator.inheritance.php,keyword.other.template,keyword.other.substitution,entity.name.operator,meta.property-list punctuation.separator.key-value,meta.at-rule.mixin punctuation.separator.key-value,meta.at-rule.function variable.parameter.url</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#89ddff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Import, Export, From, Default</string>
        <key>scope</key>
        <string>keyword.control.import,keyword.control.export,keyword.control.from,keyword.control.default,meta.import keyword.other</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7dcfff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Keyword</string>
        <key>scope</key>
        <string>keyword,keyword.control,keyword.other.important</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Keyword SQL</string>
        <key>scope</key>
        <string>keyword.other.DML</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7dcfff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Keyword Operator Logical, Arrow, Ternary, Comparison</string>
        <key>scope</key>
        <string>keyword.operator.logical,storage.type.function,keyword.operator.bitwise,keyword.operator.ternary,keyword.operator.comparison,keyword.operator.relational,keyword.operator.or.regexp</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Tag</string>
        <key>scope</key>
        <string>entity.name.tag</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Tag - Custom</string>
        <key>scope</key>
        <string>entity.name.tag support.class.component,meta.tag.custom entity.name.tag,meta.tag</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#de5971</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Tag Punctuation</string>
        <key>scope</key>
        <string>punctuation.definition.tag</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#ba3c97</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Globals, PHP Constants, etc</string>
        <key>scope</key>
        <string>constant.other.php,variable.other.global.safer,variable.other.global.safer punctuation.definition.variable,variable.other.global,variable.other.global punctuation.definition.variable,constant.other</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#e0af68</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Variables</string>
        <key>scope</key>
        <string>variable,support.variable,string constant.other.placeholder,variable.parameter.handlebars,variable.other.object</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Variable Array Key</string>
        <key>scope</key>
        <string>meta.array.literal variable</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7dcfff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Object Key</string>
        <key>scope</key>
        <string>meta.object-literal.key,entity.name.type.hcl,string.alias.graphql,string.unquoted.graphql,string.unquoted.alias.graphql,meta.group.braces.curly constant.other.object.key.js string.unquoted.label.js,meta.field.declaration.ts variable.object.property,meta.block entity.name.label</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#73daca</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Object Property</string>
        <key>scope</key>
        <string>variable.other.property,support.variable.property,support.variable.property.dom,meta.function-call variable.other.object.property</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7dcfff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Object Property</string>
        <key>scope</key>
        <string>variable.other.object.property</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Object Literal Member lvl 3 (Vue Prop Validation)</string>
        <key>scope</key>
        <string>meta.objectliteral meta.object.member meta.objectliteral meta.object.member meta.objectliteral meta.object.member meta.object-literal.key</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#41a6b5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>C-related Block Level Variables</string>
        <key>scope</key>
        <string>source.cpp meta.block variable.other</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Other Variable</string>
        <key>scope</key>
        <string>support.other.variable</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Methods</string>
        <key>scope</key>
        <string>meta.class-method.js entity.name.function.js,entity.name.method.js,variable.function.constructor,keyword.other.special-method,storage.type.cs</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7aa2f7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Function Definition</string>
        <key>scope</key>
        <string>entity.name.function,variable.other.enummember,meta.function-call,meta.function-call entity.name.function,variable.function,meta.definition.method entity.name.function,meta.object-literal entity.name.function</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7aa2f7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Function Argument</string>
        <key>scope</key>
        <string>variable.parameter.function.language.special,variable.parameter,meta.function.parameters punctuation.definition.variable,meta.function.parameter variable</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#e0af68</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Constant, Tag Attribute</string>
        <key>scope</key>
        <string>keyword.other.type.php,storage.type.php,constant.character,constant.escape,keyword.other.unit</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Variable Definition</string>
        <key>scope</key>
        <string>meta.definition.variable variable.other.constant,meta.definition.variable variable.other.readwrite,variable.declaration.hcl variable.other.readwrite.hcl,meta.mapping.key.hcl variable.other.readwrite.hcl,variable.other.declaration</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Inherited Class</string>
        <key>scope</key>
        <string>entity.other.inherited-class</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string/>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Class, Support, DOM, etc</string>
        <key>scope</key>
        <string>support.class,support.type,variable.other.readwrite.alias,support.orther.namespace.use.php,meta.use.php,support.other.namespace.php,support.type.sys-types,support.variable.dom,support.constant.math,support.type.object.module,support.constant.json,entity.name.namespace,meta.import.qualifier,variable.other.constant.object</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#0db9d7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Class Name</string>
        <key>scope</key>
        <string>entity.name</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Support Function</string>
        <key>scope</key>
        <string>support.function</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#0db9d7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS Class and Support</string>
        <key>scope</key>
        <string>source.css support.type.property-name,source.sass support.type.property-name,source.scss support.type.property-name,source.less support.type.property-name,source.stylus support.type.property-name,source.postcss support.type.property-name,support.type.property-name.css,support.type.vendored.property-name,support.type.map.key</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7aa2f7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS Font</string>
        <key>scope</key>
        <string>support.constant.font-name,meta.definition.variable</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9ece6a</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS Class</string>
        <key>scope</key>
        <string>entity.other.attribute-name.class,meta.at-rule.mixin.scss entity.name.function.scss</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9ece6a</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS ID</string>
        <key>scope</key>
        <string>entity.other.attribute-name.id</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#fc7b7b</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS Tag</string>
        <key>scope</key>
        <string>entity.name.tag.css</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#0db9d7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS Tag Reference, Pseudo &amp; Class Punctuation</string>
        <key>scope</key>
        <string>entity.other.attribute-name.pseudo-class punctuation.definition.entity,entity.other.attribute-name.pseudo-element punctuation.definition.entity,entity.other.attribute-name.class punctuation.definition.entity,entity.name.tag.reference</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#e0af68</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS Punctuation</string>
        <key>scope</key>
        <string>meta.property-list</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9abdf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS at-rule fix</string>
        <key>scope</key>
        <string>meta.property-list meta.at-rule.if,meta.at-rule.return variable.parameter.url,meta.property-list meta.at-rule.else</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#ff9e64</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS Parent Selector Entity</string>
        <key>scope</key>
        <string>entity.other.attribute-name.parent-selector-suffix punctuation.definition.entity.css</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#73daca</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS Punctuation comma fix</string>
        <key>scope</key>
        <string>meta.property-list meta.property-list</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9abdf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>SCSS @</string>
        <key>scope</key>
        <string>meta.at-rule.mixin keyword.control.at-rule.mixin,meta.at-rule.include entity.name.function.scss,meta.at-rule.include keyword.control.at-rule.include</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>SCSS Mixins, Extends, Include Keyword</string>
        <key>scope</key>
        <string>keyword.control.at-rule.include punctuation.definition.keyword,keyword.control.at-rule.mixin punctuation.definition.keyword,meta.at-rule.include keyword.control.at-rule.include,keyword.control.at-rule.extend punctuation.definition.keyword,meta.at-rule.extend keyword.control.at-rule.extend,entity.other.attribute-name.placeholder.css punctuation.definition.entity.css,meta.at-rule.media keyword.control.at-rule.media,meta.at-rule.mixin keyword.control.at-rule.mixin,meta.at-rule.function keyword.control.at-rule.function,keyword.control punctuation.definition.keyword</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9d7cd8</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>SCSS Include Mixin Argument</string>
        <key>scope</key>
        <string>meta.property-list meta.at-rule.include</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS value</string>
        <key>scope</key>
        <string>support.constant.property-value</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#ff9e64</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Sub-methods</string>
        <key>scope</key>
        <string>entity.name.module.js,variable.import.parameter.js,variable.other.class.js</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Language methods</string>
        <key>scope</key>
        <string>variable.language</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Variable punctuation</string>
        <key>scope</key>
        <string>variable.other punctuation.definition.variable</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Keyword this with Punctuation, ES7 Bind Operator</string>
        <key>scope</key>
        <string>source.js constant.other.object.key.js string.unquoted.label.js,variable.language.this punctuation.definition.variable,keyword.other.this</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>HTML Attributes</string>
        <key>scope</key>
        <string>entity.other.attribute-name,text.html.basic entity.other.attribute-name.html,text.html.basic entity.other.attribute-name</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>HTML Character Entity</string>
        <key>scope</key>
        <string>text.html constant.character.entity</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#0DB9D7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Vue (Vetur / deprecated) Template attributes</string>
        <key>scope</key>
        <string>entity.other.attribute-name.id.html,meta.directive.vue entity.other.attribute-name.html</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS ID's</string>
        <key>scope</key>
        <string>source.sass keyword.control</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7aa2f7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS psuedo selectors</string>
        <key>scope</key>
        <string>entity.other.attribute-name.pseudo-class,entity.other.attribute-name.pseudo-element,entity.other.attribute-name.placeholder,meta.property-list meta.property-value</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Inserted</string>
        <key>scope</key>
        <string>markup.inserted</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#449dab</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Deleted</string>
        <key>scope</key>
        <string>markup.deleted</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#914c54</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Changed</string>
        <key>scope</key>
        <string>markup.changed</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#6183bb</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Regular Expressions</string>
        <key>scope</key>
        <string>string.regexp</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#b4f9f8</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Regular Expressions - Punctuation</string>
        <key>scope</key>
        <string>punctuation.definition.group</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Regular Expressions - Character Class</string>
        <key>scope</key>
        <string>constant.other.character-class.regexp</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Regular Expressions - Character Class Set</string>
        <key>scope</key>
        <string>constant.other.character-class.set.regexp,punctuation.definition.character-class.regexp</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#e0af68</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Regular Expressions - Quantifier</string>
        <key>scope</key>
        <string>keyword.operator.quantifier.regexp</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#89ddff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Regular Expressions - Backslash</string>
        <key>scope</key>
        <string>constant.character.escape.backslash</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Escape Characters</string>
        <key>scope</key>
        <string>constant.character.escape</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#89ddff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Decorators</string>
        <key>scope</key>
        <string>tag.decorator.js entity.name.tag.js,tag.decorator.js punctuation.definition.tag.js</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7aa2f7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>CSS Units</string>
        <key>scope</key>
        <string>keyword.other.unit</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>JSON Key - Level 0</string>
        <key>scope</key>
        <string>source.json meta.structure.dictionary.json support.type.property-name.json</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7aa2f7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>JSON Key - Level 1</string>
        <key>scope</key>
        <string>source.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json support.type.property-name.json</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#0db9d7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>JSON Key - Level 2</string>
        <key>scope</key>
        <string>source.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json support.type.property-name.json</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7dcfff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>JSON Key - Level 3</string>
        <key>scope</key>
        <string>source.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json support.type.property-name.json</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>JSON Key - Level 4</string>
        <key>scope</key>
        <string>source.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json support.type.property-name.json</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#e0af68</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>JSON Key - Level 5</string>
        <key>scope</key>
        <string>source.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json support.type.property-name.json</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#0db9d7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>JSON Key - Level 6</string>
        <key>scope</key>
        <string>source.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json support.type.property-name.json</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#73daca</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>JSON Key - Level 7</string>
        <key>scope</key>
        <string>source.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json support.type.property-name.json</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>JSON Key - Level 8</string>
        <key>scope</key>
        <string>source.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json meta.structure.dictionary.value.json meta.structure.dictionary.json support.type.property-name.json</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9ece6a</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Plain Punctuation</string>
        <key>scope</key>
        <string>punctuation.definition.list_item.markdown</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9abdf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Block Punctuation</string>
        <key>scope</key>
        <string>meta.block,meta.brace,punctuation.definition.block,punctuation.definition.use,punctuation.definition.class,punctuation.definition.begin.bracket,punctuation.definition.end.bracket,punctuation.definition.switch-expression.begin.bracket,punctuation.definition.switch-expression.end.bracket,punctuation.definition.section.switch-block.begin.bracket,punctuation.definition.section.switch-block.end.bracket,punctuation.definition.group.shell,punctuation.definition.parameters,punctuation.definition.arguments,punctuation.definition.dictionary,punctuation.definition.array,punctuation.section</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9abdf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Plain</string>
        <key>scope</key>
        <string>meta.jsx.children,meta.embedded.block</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>HTML text</string>
        <key>scope</key>
        <string>text.html,text.log</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#9aa5ce</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Markup Raw Inline</string>
        <key>scope</key>
        <string>text.html.markdown markup.inline.raw.markdown</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#bb9af7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Markup Raw Inline Punctuation</string>
        <key>scope</key>
        <string>text.html.markdown markup.inline.raw.markdown punctuation.definition.raw.markdown</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#4E5579</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Heading 1</string>
        <key>scope</key>
        <string>heading.1.markdown entity.name,heading.1.markdown punctuation.definition.heading.markdown</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>bold</string>
          <key>foreground</key>
          <string>#89ddff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Heading 2</string>
        <key>scope</key>
        <string>heading.2.markdown entity.name,heading.2.markdown punctuation.definition.heading.markdown</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>bold</string>
          <key>foreground</key>
          <string>#61bdf2</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Heading 3</string>
        <key>scope</key>
        <string>heading.3.markdown entity.name,heading.3.markdown punctuation.definition.heading.markdown</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>bold</string>
          <key>foreground</key>
          <string>#7aa2f7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Heading 4</string>
        <key>scope</key>
        <string>heading.4.markdown entity.name,heading.4.markdown punctuation.definition.heading.markdown</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>bold</string>
          <key>foreground</key>
          <string>#6d91de</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Heading 5</string>
        <key>scope</key>
        <string>heading.5.markdown entity.name,heading.5.markdown punctuation.definition.heading.markdown</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>bold</string>
          <key>foreground</key>
          <string>#9aa5ce</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Heading 6</string>
        <key>scope</key>
        <string>heading.6.markdown entity.name,heading.6.markdown punctuation.definition.heading.markdown</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>bold</string>
          <key>foreground</key>
          <string>#747ca1</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markup - Italic</string>
        <key>scope</key>
        <string>markup.italic,markup.italic punctuation</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>italic</string>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markup - Bold</string>
        <key>scope</key>
        <string>markup.bold,markup.bold punctuation</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>bold</string>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markup - Bold-Italic</string>
        <key>scope</key>
        <string>markup.bold markup.italic,markup.bold markup.italic punctuation</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>bold italic</string>
          <key>foreground</key>
          <string>#c0caf5</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markup - Underline</string>
        <key>scope</key>
        <string>markup.underline,markup.underline punctuation</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>underline</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Blockquote</string>
        <key>scope</key>
        <string>markup.quote punctuation.definition.blockquote.markdown</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#4e5579</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markup - Quote</string>
        <key>scope</key>
        <string>markup.quote</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>italic</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Link</string>
        <key>scope</key>
        <string>string.other.link,markup.underline.link,constant.other.reference.link.markdown,string.other.link.description.title.markdown</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#73daca</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Fenced Code Block</string>
        <key>scope</key>
        <string>markup.fenced_code.block.markdown,markup.inline.raw.string.markdown,variable.language.fenced.markdown</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#89ddff</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markdown - Separator</string>
        <key>scope</key>
        <string>meta.separator</string>
        <key>settings</key>
        <dict>
          <key>fontStyle</key>
          <string>bold</string>
          <key>foreground</key>
          <string>#444b6a</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Markup - Table</string>
        <key>scope</key>
        <string>markup.table</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#c0cefc</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Token - Info</string>
        <key>scope</key>
        <string>token.info-token</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#0db9d7</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Token - Warn</string>
        <key>scope</key>
        <string>token.warn-token</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#ffdb69</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Token - Error</string>
        <key>scope</key>
        <string>token.error-token</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#db4b4b</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Token - Debug</string>
        <key>scope</key>
        <string>token.debug-token</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#b267e6</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Apache Tag</string>
        <key>scope</key>
        <string>entity.tag.apacheconf</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#f7768e</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>Preprocessor</string>
        <key>scope</key>
        <string>meta.preprocessor</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#73daca</string>
        </dict>
      </dict>
      <dict>
        <key>name</key>
        <string>ENV value</string>
        <key>scope</key>
        <string>source.env</string>
        <key>settings</key>
        <dict>
          <key>foreground</key>
          <string>#7aa2f7</string>
        </dict>
      </dict>
    </array>
  </dict>
</plist>


================================================
FILE: crates/embedded-typst/Cargo.toml
================================================
[package]
name = "embedded-typst"
description = "Run typst inside of typst"
authors.workspace = true
version.workspace = true
license.workspace = true
edition.workspace = true
homepage.workspace = true
repository.workspace = true

[lib]
crate-type = ["cdylib"]

[dependencies]
typst.workspace = true
typst-svg.workspace = true
reflexo-typst.workspace = true
serde_json.workspace = true
flate2 = "1"
tar = "0.4"

wasm-minimal-protocol = { git = "https://github.com/astrale-sharp/wasm-minimal-protocol", optional = true }

[features]
typst-plugin = ["wasm-minimal-protocol"]

default = ["typst-plugin"]

[lints]
workspace = true


================================================
FILE: crates/embedded-typst/src/lib.rs
================================================
//! This is a WASM wrapper of the embedded Typst.

#![cfg_attr(feature = "typst-plugin", allow(missing_docs))]

use std::{
    collections::HashMap,
    io::Read,
    path::{Path, PathBuf},
    str::FromStr,
    sync::{Arc, Mutex, RwLock},
    vec,
};

use reflexo_typst::{
    font::{pure::MemoryFontSearcher, FontResolverImpl},
    package::{PackageRegistry, PackageSpec, RegistryPathMapper},
    typst::prelude::EcoVec,
    vfs::{dummy::DummyAccessModel, FileSnapshot},
    CompilerUniverse, EntryReader, EntryState, ShadowApi, TaskInputs, TypstDocument,
    TypstPagedDocument,
};
use typst::{
    diag::{eco_format, FileResult, PackageError},
    foundations::Bytes,
    Features,
};

use wasm_minimal_protocol::*;
initiate_protocol!();

type StrResult<T> = Result<T, String>;

/// Allocates a data reference, return the key of the data reference.
///
/// # Panics
///
/// Panics if the world is not initialized.
///
/// # Errors
///
/// Error if there is an error
#[cfg_attr(feature = "typst-plugin", wasm_func)]
pub fn allocate_data(kind: &[u8], data: &[u8]) -> StrResult<Vec<u8>> {
    allocate_data_inner(kind, data, None)
}

/// Allocates a file reference, return the key of the data reference.
///
/// # Panics
///
/// Panics if the world is not initialized.
///
/// # Errors
///
/// Error if there is an error
#[cfg_attr(feature = "typst-plugin", wasm_func)]
pub fn allocate_file(kind: &[u8], path: &[u8], data: &[u8]) -> StrResult<Vec<u8>> {
    allocate_data_inner(kind, data, Some(path))
}

/// Allocates a data reference
fn allocate_data_inner(kind: &[u8], data: &[u8], path: Option<&[u8]>) -> StrResult<Vec<u8>> {
    let kind = std::str::from_utf8(kind).map_err(|e| e.to_string())?;
    let data = ImmutBytes(Bytes::new(data.to_owned()));

    let data_ref = match kind {
        "font" => DataRef::Font { data: Some(data) },
        "package" => {
            let path = std::str::from_utf8(path.unwrap()).map_err(|e| e.to_string())?;
            DataRef::Package {
                spec: path.to_string(),
                data: Some(data),
            }
        }
        "file" => {
            let path = std::str::from_utf8(path.unwrap()).map_err(|e| e.to_string())?;
            DataRef::File {
                path: path.to_owned(),
                data: Some(data),
            }
        }
        _ => return Err(format!("Unknown data kind: {kind}")),
    };

    let mut data = DATA.lock().unwrap();

    data.data.push(data_ref);

    Ok(vec![0])
}

/// A context that is used to resolve a world context.
pub struct Context {
    /// The data that are used in the main file.
    data: Vec<DataRef>,
}

static DATA: Mutex<Context> = Mutex::new(Context { data: vec![] });

/// A bytes object that is cheap to clone.
#[derive(Clone)]
struct ImmutBytes(Bytes);

/// A data reference in global data storage.
#[derive(Clone)]
enum DataRef {
    Font {
        data: Option<ImmutBytes>,
    },
    Package {
        spec: String,
        data: Option<ImmutBytes>,
    },
    File {
        path: String,
        data: Option<ImmutBytes>,
    },
}

impl DataRef {
    /// Gets the data of the object.
    pub fn data(&self) -> Option<&ImmutBytes> {
        match self {
            Self::Font { data, .. } => data.as_ref(),
            Self::Package { data, .. } => data.as_ref(),
            Self::File { data, .. } => data.as_ref(),
        }
    }
}

static VERSE: RwLock<Option<WorldRepr>> = RwLock::new(None);

/// Resolves a world
#[cfg_attr(feature = "typst-plugin", wasm_func)]
pub fn resolve_world() -> StrResult<Vec<u8>> {
    let resolved = create_world()?;
    let mut world = VERSE.write().unwrap();
    if world.is_some() {
        return Err("World is already initialized".to_string());
    }

    *world = Some(resolved);

    Ok(vec![])
}

/// Creates a world
fn create_world() -> StrResult<WorldRepr> {
    /// Extracts a package.
    fn extract_package(
        data: &[u8],
        mut cb: impl FnMut(String, &[u8], u64) -> StrResult<()>,
    ) -> StrResult<()> {
        let decompressed = flate2::read::GzDecoder::new(data);
        let mut reader = tar::Archive::new(decompressed);
        let entries = reader.entries();
        let entries = entries.map_err(|err| {
            let t = PackageError::MalformedArchive(Some(eco_format!("{err}")));
            format!("{t:?}",)
        })?;

        let mut buf = Vec::with_capacity(1024);
        for entry in entries {
            // Read single entry
            let mut entry = entry.map_err(|e| e.to_string())?;
            let header = entry.header();

            let is_file = header.entry_type().is_file();
            if !is_file {
                continue;
            }

            let mtime = header.mtime().unwrap_or(0);

            let path = header.path().map_err(|e| e.to_string())?;
            let path = path.to_string_lossy().as_ref().to_owned();

            let size = header.size().map_err(|e| e.to_string())?;
            buf.clear();
            buf.reserve(size as usize);
            entry.read_to_end(&mut buf).map_err(|e| e.to_string())?;

            cb(path, &buf, mtime)?
        }

        Ok(())
    }

    /// Creates a world based on the context.
    fn resolve_world_inner() -> StrResult<WorldRepr> {
        let data_guard = DATA.lock().unwrap();

        // Adds embedded fonts.
        let mut fb = MemoryFontSearcher::new();
        let mut pb = MemoryRegistry::default();

        for data in &data_guard.data {
            match data {
                DataRef::Font { data, .. } => {
                    fb.add_memory_font(data.clone().unwrap().0);
                }
                DataRef::Package { spec, .. } => {
                    let spec = PackageSpec::from_str(spec).map_err(|e| e.to_string())?;
                    pb.add_memory_package(spec);
                }
                DataRef::File { .. } => {}
            }
        }

        let registry = Arc::new(pb);
        let resolver = Arc::new(RegistryPathMapper::new(registry.clone()));
        let mut vfs = reflexo_typst::vfs::Vfs::new(resolver, DummyAccessModel);

        for data in &data_guard.data {
            match data {
                DataRef::Package { data, spec, .. } => {
                    let spec = PackageSpec::from_str(spec).map_err(|e| e.to_string())?;
                    let path = registry.resolve(&spec).map_err(|e| e.to_string())?;

                    let data = data.clone().unwrap().0;
                    extract_package(&data, |key, value, _mtime| {
                        vfs.revise()
                            .map_shadow(
                                &path.join(key.as_str()),
                                FileSnapshot::from(FileResult::Ok(Bytes::new(value.to_owned()))),
                            )
                            .map_err(|e| e.to_string())
                    })?;
                }
                DataRef::Font { .. } | DataRef::File { .. } => {}
            }
        }

        for data in EMBEDDED_FONT {
            fb.add_memory_font(Bytes::new(data));
        }

        // Creates a world.
        let world = WorldRepr::new_raw(
            EntryState::new_workspace(PathBuf::from("/").into()),
            Features::default(),
            None,
            vfs,
            registry,
            Arc::new(fb.build()),
        );

        Ok(world)
    }

    // Removes files from the context as they are not used for resolving a world.
    let mut files = Vec::new();
    let _ = &DATA.lock().unwrap().data.retain(|f| match f {
        DataRef::File { .. } => {
            files.push(f.clone());
            false
        }
        _ => true,
    });
    let mut world = resolve_world_inner()?;

    for f in files.into_iter() {
        let path = match &f {
            DataRef::File { path, .. } => path,
            _ => unreachable!(),
        };
        let path = Path::new(path);
        let data = f.data().cloned().unwrap().0;
        world.map_shadow(path, data).map_err(|e| e.to_string())?;
    }
    Ok(world)
}

/// Compile a typst file to svg.
///
/// # Panics
///
/// Panics if the world is not initialized.
///
/// # Errors
///
/// Error if there is an error
#[cfg_attr(feature = "typst-plugin", wasm_func)]
pub fn svg(input: &[u8]) -> StrResult<Vec<u8>> {
    let verse = VERSE.read().unwrap();
    let Some(verse) = verse.as_ref() else {
        return Err("World is not initialized".to_string());
    };

    // Prepare main file.
    let entry_file = Path::new("/main.typ");
    let entry = verse.entry_state().select_in_workspace(entry_file);

    // Compile.
    let mut world = verse.snapshot_with(Some(TaskInputs {
        entry: Some(entry),
        inputs: None,
    }));
    world
        .map_shadow(entry_file, Bytes::new(input.to_owned()))
        .map_err(|e| e.to_string())?;

    // todo: warning
    let doc: TypstPagedDocument =
        typst::compile(&world)
            .output
            .map_err(|e: EcoVec<typst::diag::SourceDiagnostic>| {
                let mut error_log = String::new();
                for c in e.into_iter() {
                    error_log.push_str(&format!(
                        "{:?}\n",
                        reflexo_typst::error::diag_from_std(c, Some(&world))
                    ));
                }
                error_log
            })?;

    let pages_data: Vec<_> = doc
        .pages
        .iter()
        .map(|page| typst_svg::svg(page).into_bytes())
        .collect();

    let doc = Arc::new(doc);
    let typ_doc = TypstDocument::Paged(doc);
    // Query header.
    let header = reflexo_typst::query::retrieve(&world, "<embedded-typst>", &typ_doc);
    let header = match header {
        Ok(header) => serde_json::to_vec(&header).map_err(|e| e.to_string())?,
        Err(e) => serde_json::to_vec(&e).map_err(|e| e.to_string())?,
    };

    // Build payload.
    Ok((Some(header).into_iter())
        .chain(pages_data)
        .collect::<Vec<_>>()
        .join(&b"\n\n\n\n\n\n\n\n"[..]))
}

/// type trait of [`TypstWasmWorld`].
#[derive(Debug, Clone, Copy)]
pub struct WasmCompilerFeat;

impl reflexo_typst::world::CompilerFeat for WasmCompilerFeat {
    /// It accesses no file system.
    type FontResolver = FontResolverImpl;
    /// It accesses no file system.
    type AccessModel = DummyAccessModel;
    /// It cannot load any package.
    type Registry = MemoryRegistry;
}

type WorldRepr = reflexo_typst::world::CompilerUniverse<WasmCompilerFeat>;

/// The compiler world in wasm environment.
#[allow(unused)]
pub struct TypstWasmWorld(WorldRepr);

impl Default for TypstWasmWorld {
    fn default() -> Self {
        Self::new()
    }
}

impl TypstWasmWorld {
    /// Create a new [`TypstWasmWorld`].
    pub fn new() -> Self {
        // Creates a virtual file system.
        let registry = Arc::new(MemoryRegistry::default());
        let resolver = Arc::new(RegistryPathMapper::new(registry.clone()));
        let vfs = reflexo_typst::vfs::Vfs::new(resolver, DummyAccessModel);

        // Adds embedded fonts.
        let mut fb = MemoryFontSearcher::new();

        for data in EMBEDDED_FONT {
            fb.add_memory_font(Bytes::new(data));
        }

        // Creates a world.
        Self(CompilerUniverse::new_raw(
            EntryState::new_workspace(PathBuf::from("/").into()),
            Features::default(),
            None,
            vfs,
            registry,
            Arc::new(fb.build()),
        ))
    }
}

pub static EMBEDDED_FONT: &[&[u8]] = &[];

/// Creates a memory package registry from the builder.
#[derive(Default, Debug)]
pub struct MemoryRegistry(HashMap<PackageSpec, Arc<Path>>);

impl MemoryRegistry {
    /// Adds a memory package.
    pub fn add_memory_package(&mut self, spec: PackageSpec) -> Arc<Path> {
        let package_root: Arc<Path> = PathBuf::from("/internal-packages")
            .join(spec.name.as_str())
            .join(spec.version.to_string())
            .into();

        self.0.insert(spec, package_root.clone());

        package_root
    }
}

impl PackageRegistry for MemoryRegistry {
    /// Resolves a package.
    fn resolve(&self, spec: &PackageSpec) -> Result<Arc<Path>, PackageError> {
        self.0
            .get(spec)
            .cloned()
            .ok_or_else(|| PackageError::NotFound(spec.clone()))
    }
}

/// Makes `instant::SystemTime::now` happy
pub extern "C" fn now() -> f64 {
    0.0
}


================================================
FILE: meta.json
================================================
{
  "contributors": ["Myriad-Dreamin"]
}


================================================
FILE: openspec/changes/archive/2026-03-15-create-english-typst-grammar-skill/.openspec.yaml
================================================
schema: spec-driven
created: 2026-03-14


================================================
FILE: openspec/changes/archive/2026-03-15-create-english-typst-grammar-skill/design.md
================================================
## Context

This repository contains a detailed Typst grammar catalog in
`src/tutorial/reference-grammar.typ`. The original change turned that tutorial
asset into a Codex skill, but the first implementation blended portable author
guidance with repo-local maintenance machinery. As a result,
`typst-grammar-authoring` now includes updater scripts, traceability artifacts,
and path examples that are not ideal for copying into another repository.

The revised direction is to separate those responsibilities:

- `typst-grammar-authoring` is the portable skill that authors use.
- `update-typst-grammar-authoring` is the repo-local maintenance skill that
  updates the portable one from canonical tutorial examples.

## Goals / Non-Goals

**Goals:**
- Keep `typst-grammar-authoring` as a self-contained, English-only,
  distributable skill with only `SKILL.md`.
- Keep grammar lookup and validation workflows available inside the portable
  `SKILL.md`.
- Move generator scripts, traceability data, and repo-specific maintenance
  instructions into `update-typst-grammar-authoring`.
- Eliminate Windows-specific command paths and other platform-specific path
  examples from the distributed `SKILL.md`.
- Preserve the ability to regenerate the portable skill from
  `src/tutorial/reference-grammar.typ`.

**Non-Goals:**
- Translate the full Chinese tutorial into English.
- Replace Typst's own compiler diagnostics with a custom parser or validator.
- Depend on Tinymist, VS Code, or any specific editor integration for required
  validation.
- Create a package manager or external publishing workflow for distributing the
  portable skill.

## Decisions

### Decision: Split authoring and maintenance into two skills

The repository will contain two skills with different responsibilities:

- `typst-grammar-authoring` for portable author guidance
- `update-typst-grammar-authoring` for repo-local regeneration and maintenance

Why this approach:
- It keeps the distributed skill easy to copy into other repositories.
- It lets the updater skill retain repo-specific scripts and source references
  without polluting the authoring skill.
- It makes it clearer which instructions are for end users versus maintainers.

Alternative considered:
- Keep one repo-local skill with embedded updater logic. Rejected because it
  mixes portability and maintenance concerns in the same artifact.

### Decision: Make the portable skill a single-file skill

`typst-grammar-authoring` will consist only of `SKILL.md`. It must not depend
on sibling scripts, references, or optional UI metadata to function after being
copied to another repository.

Why this approach:
- A single file is the easiest form to distribute and review.
- It minimizes accidental coupling to repo-local layout and helper artifacts.
- It keeps the authoring experience simple for downstream repositories.

Alternative considered:
- Keep `agents/`, `references/`, or `scripts/` alongside the distributed skill.
  Rejected because the user explicitly wants the authoring skill to remain only
  a Markdown file.

### Decision: Put all repo-specific updater assets under `update-typst-grammar-authoring`

The updater skill will own:

- regeneration scripts
- traceability artifacts
- repo-specific instructions that mention `src/tutorial/reference-grammar.typ`
- any maintenance-only metadata

Why this approach:
- It centralizes maintenance behavior in one place.
- It keeps downstream consumers from carrying unnecessary repo-specific files.
- It preserves exact source traceability without expanding the portable skill
  context.

Alternative considered:
- Leave traceability JSON and generator scripts under the portable skill folder.
  Rejected because those files are maintenance artifacts, not distributed
  authoring guidance.

### Decision: Use platform-neutral path examples in the portable skill

The distributed `SKILL.md` will use forward-slash, repo-relative, or placeholder
paths such as `path/to/document.typ` and `target/typst-grammar-authoring-check/document.html`.
It must not use Windows absolute paths or Windows-style backslash-only command
examples.

Why this approach:
- It keeps the skill readable across operating systems.
- It avoids downstream users mistaking repo-local Windows commands for required
  syntax.
- It makes the portable skill genuinely portable instead of just copyable.

Alternative considered:
- Keep PowerShell-oriented backslash paths because the repo is currently being
  edited on Windows. Rejected because the distributed skill should not inherit a
  single machine's path style.

### Decision: Keep the portable skill self-contained, but keep verbose traceability out of it

The portable skill will still embed a compact grammar lookup and validation
workflow inside `SKILL.md`, but verbose canonical references and source-line
traceability will live in updater-owned artifacts instead.

Why this approach:
- It preserves low-context usability for authors.
- It keeps the portable skill smaller than a fully traceable catalog.
- It still gives maintainers a way to audit generated entries precisely.

Alternative considered:
- Remove all generated grammar data from the portable skill and require a sidecar
  reference file. Rejected because the portable skill must remain single-file.

## Risks / Trade-offs

- A single-file portable skill is still larger than a minimal skill because it
  embeds grammar lookup content. → Mitigation: keep examples compact and keep
  verbose traceability in the updater skill only.
- Splitting the skills adds another artifact to maintain. → Mitigation: make the
  updater skill the clear owner of regeneration and validation steps.
- Portable path examples may drift back toward platform-specific syntax during
  updates. → Mitigation: add explicit tasks and verification for path style.

## Migration Plan

1. Create a repo-local `update-typst-grammar-authoring` skill under
   `.codex/skills/`.
2. Move generator scripts, traceability artifacts, and repo-specific update
   instructions into the updater skill.
3. Reduce `.codex/skills/typst-grammar-authoring/` to a single distributable
   `SKILL.md`.
4. Rewrite distributed validation commands and examples to use platform-neutral
   paths.
5. Verify the updater still regenerates the distributed skill correctly.

Rollback strategy:
- Restore the previous single-skill folder layout if the split causes an
  unacceptable maintenance burden.

## Open Questions

- None at proposal update time. The split between portable and maintenance
  skills is the intended direction.


================================================
FILE: openspec/changes/archive/2026-03-15-create-english-typst-grammar-skill/proposal.md
================================================
## Why

The current `typst-grammar-authoring` implementation mixes two different jobs:
portable Typst authoring guidance for end users and repo-local maintenance
logic for regenerating that guidance from `src/tutorial/reference-grammar.typ`.
That coupling makes the distributed skill harder to copy into another
repository, and it has already allowed Windows-style command paths and
repo-specific maintenance details to leak into `SKILL.md`.

We want to split those concerns cleanly:

- `typst-grammar-authoring` should become the portable skill that users can copy
  to another repository as a single `SKILL.md` file.
- `update-typst-grammar-authoring` should become the repo-local maintenance
  skill that regenerates and validates the portable skill from this tutorial's
  canonical grammar source.

## What Changes

- Split the current single skill implementation into two separate skills:
  `typst-grammar-authoring` and `update-typst-grammar-authoring`.
- Make `typst-grammar-authoring` a self-contained, English-only, distributable
  skill consisting only of `SKILL.md`.
- Move generator scripts, traceability artifacts, repo-specific update
  instructions, and any maintenance-only metadata into
  `update-typst-grammar-authoring`.
- Require the distributed `typst-grammar-authoring/SKILL.md` to use
  platform-neutral path examples instead of Windows-specific command paths.
- Keep compile, HTML, and SVG validation guidance in the portable skill while
  keeping verbose traceability data outside its default context.

## Capabilities

### New Capabilities
- `typst-document-authoring-skill`: Provide a portable, single-file Typst
  authoring skill with embedded grammar lookup and compile-based validation
  guidance.
- `typst-document-authoring-skill-maintenance`: Provide a repo-local updater
  skill that regenerates the portable Typst authoring skill from
  `src/tutorial/reference-grammar.typ`.

### Modified Capabilities
- None.

## Impact

- Affects repo-local skill content under `.codex/skills/`.
- Changes `typst-grammar-authoring` from a repo-local folder with support files
  into a portable single-file skill.
- Adds or updates a separate `update-typst-grammar-authoring` skill for
  generation, validation, and traceability workflows.
- Removes Windows-specific command path examples from the distributed authoring
  skill.


================================================
FILE: openspec/changes/archive/2026-03-15-create-english-typst-grammar-skill/specs/typst-document-authoring-skill/spec.md
================================================
## ADDED Requirements

### Requirement: Portable authoring skill is English-facing and self-contained
The distributed `typst-grammar-authoring` skill SHALL be complete as a
single-file, English-facing `SKILL.md` so it can be copied into another
repository without requiring sibling support files.

#### Scenario: Single-file portable distribution
- **WHEN** `typst-grammar-authoring` is prepared for downstream use
- **THEN** the skill folder MUST be complete with only `SKILL.md`
- **AND** that `SKILL.md` MUST contain the authoring guidance, grammar lookup,
  and validation workflow needed by the consuming repository

### Requirement: Portable authoring skill avoids Windows-specific path examples
The distributed `typst-grammar-authoring/SKILL.md` SHALL use platform-neutral,
forward-slash, or placeholder filesystem paths in commands and examples.

#### Scenario: Portable command examples
- **WHEN** `typst-grammar-authoring/SKILL.md` is authored or regenerated
- **THEN** command examples MUST use repo-relative or placeholder paths such as
  `path/to/document.typ`
- **AND** the file MUST NOT include Windows absolute paths or Windows-style
  backslash-only command paths

### Requirement: Portable authoring skill embeds compact grammar lookup
The distributed `typst-grammar-authoring/SKILL.md` SHALL embed a compact Typst
grammar lookup derived from `src/tutorial/reference-grammar.typ` so it remains
single-file while still teaching canonical syntax patterns.

#### Scenario: Grammar lookup without sidecar references
- **WHEN** Codex needs a Typst syntax pattern while using
  `typst-grammar-authoring`
- **THEN** the skill MUST provide that lookup inside `SKILL.md`
- **AND** the lookup MUST be derived from canonical examples in
  `src/tutorial/reference-grammar.typ`

### Requirement: Updater skill owns regeneration of the portable skill
The repo-local `update-typst-grammar-authoring` skill SHALL own the workflow
that regenerates the distributed `typst-grammar-authoring/SKILL.md` from
`src/tutorial/reference-grammar.typ`.

#### Scenario: Repo-local regeneration
- **WHEN** a maintainer updates canonical grammar examples from
  `src/tutorial/reference-grammar.typ`
- **THEN** `update-typst-grammar-authoring` MUST provide the update workflow
- **AND** that workflow MUST produce the distributed
  `typst-grammar-authoring/SKILL.md`

### Requirement: Updater skill preserves verbose traceability outside portable context
The updater workflow SHALL preserve exact source traceability in separate
maintenance artifacts without injecting verbose canonical reference and
traceability sections into the distributed `typst-grammar-authoring/SKILL.md`.

#### Scenario: Maintainer needs exact source mapping
- **WHEN** a maintainer needs exact source mapping for a generated grammar entry
- **THEN** `update-typst-grammar-authoring` MUST provide a separate
  traceability artifact
- **AND** the distributed `typst-grammar-authoring/SKILL.md` MUST omit verbose
  canonical reference and traceability sections from its active context

### Requirement: Grammar validation uses Typst compilation
The portable authoring skill SHALL define `typst compile` as the required
validation workflow for grammar and compile-time errors in authored Typst
documents.

#### Scenario: Compile failure is treated as invalid grammar or document state
- **WHEN** Codex validates a `.typ` file with the skill's required workflow
- **THEN** a non-zero `typst compile` result MUST be treated as a blocking
  validation failure

### Requirement: Text output can be validated through HTML export
The portable authoring skill SHALL define a text-validation workflow based on
Typst HTML output so Codex can inspect textual structure and rendered text
separately from compile success.

#### Scenario: HTML validation of authored text
- **WHEN** Codex needs to verify rendered text or document structure after a
  successful compile
- **THEN** the skill MUST direct Codex to use `typst compile --features html`
  to produce HTML output for inspection

### Requirement: Visual output can be validated through SVG and Playwright
The portable authoring skill SHALL define a visual-validation workflow based on
Typst SVG output and Playwright MCP inspection so Codex can review rendered
layout after compilation.

#### Scenario: SVG and Playwright visual inspection
- **WHEN** Codex needs to inspect rendered layout or visual regressions in a
  user Typst document
- **THEN** the skill MUST direct Codex to compile the document to SVG
- **AND** the skill MUST direct Codex to use Playwright MCP as the visual
  inspection step


================================================
FILE: openspec/changes/archive/2026-03-15-create-english-typst-grammar-skill/tasks.md
================================================
## 1. Split the skill topology

- [x] 1.1 Create a repo-local `update-typst-grammar-authoring` skill target under `.codex/skills/`
- [x] 1.2 Move generator scripts, traceability artifacts, and updater-only metadata out of `typst-grammar-authoring` and into `update-typst-grammar-authoring`
- [x] 1.3 Reduce `.codex/skills/typst-grammar-authoring/` to a distributable single-file skill that contains only `SKILL.md`

## 2. Rewrite the portable authoring skill

- [x] 2.1 Rewrite `typst-grammar-authoring/SKILL.md` to remove Windows-specific command paths and use platform-neutral path examples
- [x] 2.2 Keep grammar lookup and validation guidance self-contained inside the distributed `typst-grammar-authoring/SKILL.md`
- [x] 2.3 Remove repo-local maintenance instructions, source-path dependencies, and sidecar-file assumptions from the distributed `typst-grammar-authoring/SKILL.md`

## 3. Build the updater skill workflow

- [x] 3.1 Add updater instructions for regenerating `typst-grammar-authoring/SKILL.md` from `src/tutorial/reference-grammar.typ`
- [x] 3.2 Keep exact source traceability available as updater-owned artifacts without expanding the portable skill context
- [x] 3.3 Add updater validation guidance for refreshing, reviewing, and diffing the distributed skill output

## 4. Verify the split

- [x] 4.1 Verify `.codex/skills/typst-grammar-authoring/` contains only `SKILL.md`
- [x] 4.2 Verify the distributed `SKILL.md` contains no Windows-specific or absolute repo-local paths in command examples
- [x] 4.3 Smoke-test the updater workflow and the portable skill after the split


================================================
FILE: openspec/config.yaml
================================================
schema: spec-driven

context: |
  When a change is archived and syncs or creates canonical specs under
  `openspec/specs/`, review each resulting `## Purpose` section before calling
  the archive complete.
  Replace any autogenerated placeholder like
  `TBD - created by archiving change ...` with a concise, domain-specific
  purpose statement that describes the capability.

rules:
  specs:
    - Every spec in `openspec/specs/*/spec.md` must include a concrete `## Purpose` section.
    - Never leave the autogenerated archive placeholder in a canonical spec purpose; replace it before reporting archive success.


================================================
FILE: openspec/specs/typst-document-authoring-skill/spec.md
================================================
# typst-document-authoring-skill Specification

## Purpose
Define the canonical requirements for a portable, English-facing Typst authoring skill and the updater and validation workflows that maintain it.

This specification defines the `typst-document-authoring-skill` capability, which is concretely implemented by the portable `typst-grammar-authoring` skill (distributed as `typst-grammar-authoring/SKILL.md`) and its repo-local updater workflow `update-typst-grammar-authoring`.

## Requirements
### Requirement: Portable authoring skill is English-facing and self-contained
The distributed `typst-grammar-authoring` skill SHALL be complete as a
single-file, English-facing `SKILL.md` so it can be copied into another
repository without requiring sibling support files.

#### Scenario: Single-file portable distribution
- **WHEN** `typst-grammar-authoring` is prepared for downstream use
- **THEN** the skill folder MUST be complete with only `SKILL.md`
- **AND** that `SKILL.md` MUST contain the authoring guidance, grammar lookup,
  and validation workflow needed by the consuming repository

### Requirement: Portable authoring skill avoids Windows-specific path examples
The distributed `typst-grammar-authoring/SKILL.md` SHALL use platform-neutral,
forward-slash, or placeholder filesystem paths in commands and examples.

#### Scenario: Portable command examples
- **WHEN** `typst-grammar-authoring/SKILL.md` is authored or regenerated
- **THEN** command examples MUST use repo-relative or placeholder paths such as
  `path/to/document.typ`
- **AND** the file MUST NOT include Windows absolute paths or Windows-style
  backslash-only command paths

### Requirement: Portable authoring skill embeds compact grammar lookup
The distributed `typst-grammar-authoring/SKILL.md` SHALL embed a compact Typst
grammar lookup derived from `src/tutorial/reference-grammar.typ` so it remains
single-file while still teaching canonical syntax patterns.

#### Scenario: Grammar lookup without sidecar references
- **WHEN** Codex needs a Typst syntax pattern while using
  `typst-grammar-authoring`
- **THEN** the skill MUST provide that lookup inside `SKILL.md`
- **AND** the lookup MUST be derived from canonical examples in
  `src/tutorial/reference-grammar.typ`

### Requirement: Updater skill owns regeneration of the portable skill
The repo-local `update-typst-grammar-authoring` skill SHALL own the workflow
that regenerates the distributed `typst-grammar-authoring/SKILL.md` from
`src/tutorial/reference-grammar.typ`.

#### Scenario: Repo-local regeneration
- **WHEN** a maintainer updates canonical grammar examples from
  `src/tutorial/reference-grammar.typ`
- **THEN** `update-typst-grammar-authoring` MUST provide the update workflow
- **AND** that workflow MUST produce the distributed
  `typst-grammar-authoring/SKILL.md`

### Requirement: Updater skill preserves verbose traceability outside portable context
The updater workflow SHALL preserve exact source traceability in separate
maintenance artifacts without injecting verbose canonical reference and
traceability sections into the distributed `typst-grammar-authoring/SKILL.md`.

#### Scenario: Maintainer needs exact source mapping
- **WHEN** a maintainer needs exact source mapping for a generated grammar entry
- **THEN** `update-typst-grammar-authoring` MUST provide a separate
  traceability artifact
- **AND** the distributed `typst-grammar-authoring/SKILL.md` MUST omit verbose
  canonical reference and traceability sections from its active context

### Requirement: Grammar validation uses Typst compilation
The portable authoring skill SHALL define `typst compile` as the required
validation workflow for grammar and compile-time errors in authored Typst
documents.

#### Scenario: Compile failure is treated as invalid grammar or document state
- **WHEN** Codex validates a `.typ` file with the skill's required workflow
- **THEN** a non-zero `typst compile` result MUST be treated as a blocking
  validation failure

### Requirement: Text output can be validated through HTML export
The portable authoring skill SHALL define a text-validation workflow based on
Typst HTML output so Codex can inspect textual structure and rendered text
separately from compile success.

#### Scenario: HTML validation of authored text
- **WHEN** Codex needs to verify rendered text or document structure after a
  successful compile
- **THEN** the skill MUST direct Codex to use `typst compile --features html`
  to produce HTML output for inspection

### Requirement: Visual output can be validated through SVG and Playwright
The portable authoring skill SHALL define a visual-validation workflow based on
Typst SVG output and Playwright MCP inspection so Codex can review rendered
layout after compilation.

#### Scenario: SVG and Playwright visual inspection
- **WHEN** Codex needs to inspect rendered layout or visual regressions in a
  user Typst document
- **THEN** the skill MUST direct Codex to compile the document to SVG
- **AND** the skill MUST direct Codex to use Playwright MCP as the visual
  inspection step


================================================
FILE: scripts/build.ps1
================================================
cargo build --release --target wasm32-unknown-unknown --manifest-path ./crates/embedded-typst/Cargo.toml --features typst-plugin
$InstallPath = "assets/artifacts/embedded_typst.wasm"
if (Test-Path $InstallPath) {
    Remove-Item $InstallPath
}
Move-Item target/wasm32-unknown-unknown/release/embedded_typst.wasm $InstallPath


================================================
FILE: scripts/build.sh
================================================
#!/bin/bash

cargo build --release --target wasm32-unknown-unknown

INSTALL_PATH="assets/artifacts/embedded_typst.wasm"
if [ -f "$INSTALL_PATH" ]; then
    rm "$INSTALL_PATH"
fi

mv target/wasm32-unknown-unknown/release/embedded_typst.wasm $INSTALL_PATH


================================================
FILE: src/book.typ
================================================
#import "@preview/shiroa:0.2.3": *

#show: book

#let book-info = json("/meta.json")

#book-meta(
  title: "The Raindrop-Blue Book (Typst中文教程)",
  description: "Typst中文教程",
  repository: "https://github.com/typst-doc-cn/tutorial",
  repository-edit: "https://github.com/typst-doc-cn/tutorial/edit/main/src/{path}",
  authors: book-info.contributors,
  language: "zh-cn",
  summary: [
    #prefix-chapter("introduction.typ")[导引]
    = 模式
    - #chapter("tutorial/writing-markup.typ")[标记模式]
    - #chapter("tutorial/writing-scripting.typ")[脚本模式]
    = 脚本
    - #chapter("tutorial/scripting-literal.typ")[基本类型]
    - #chapter("tutorial/scripting-variable.typ")[变量与函数]
    - #chapter("tutorial/scripting-composite.typ")[复合类型]
    - #chapter("tutorial/doc-modulize.typ")[模块化（多文件）]
    - #chapter("tutorial/scripting-block-and-expression.typ")[表达式]
    - #chapter("tutorial/scripting-control-flow.typ")[控制流]
    - #chapter("tutorial/doc-stateful.typ")[状态化]
    = 中文排版
    - #chapter("tutorial/scripting-main.typ")[编译流程]
    - #chapter("tutorial/writing-chinese.typ")[中文排版]
    - #chapter("tutorial/scripting-style.typ")[样式模型]
    = 科技排版
    - #chapter("tutorial/writing-math.typ")[数学排版]
    - #chapter("tutorial/scripting-shape.typ")[图形排版]
    - #chapter("tutorial/scripting-layout.typ")[布局模型]
    - #chapter("tutorial/scripting-content.typ")[文档模型]
    = 附录
    // - #chapter("tutorial/reference-grammar.typ")[语法示例检索表]
    - #chapter("tutorial/reference-utils.typ")[常用函数表]
    - #chapter("tutorial/reference-math-symbols.typ")[常用数学符号]
    - #chapter(none)[特殊Unicode字符]
    = 参考
    - #chapter("tutorial/reference-typebase.typ")[基本类型]
    - #chapter("tutorial/reference-type-builtin.typ")[内置类型]
    - #chapter("tutorial/reference-date.typ")[时间类型]
    // - #chapter("tutorial/reference-visualization.typ")[图形与几何元素]
    // - #chapter("tutorial/reference-color.typ")[颜色、色彩渐变与模式]
    - #chapter("tutorial/reference-data-process.typ")[数据读写]
    - #chapter("tutorial/reference-data-process.typ")[数据处理]
    - #chapter("tutorial/reference-calculation.typ")[数值计算]
    - #chapter("tutorial/reference-math-mode.typ")[数学模式]
    - #chapter("tutorial/reference-bibliography.typ")[参考文献]
    - #chapter("tutorial/reference-wasm-plugin.typ")[WASM插件]
    // = 进阶教程 — 排版Ⅳ
    // 6. 脚本Ⅱ
    // - IO与数据处理
    // - 内置类型
    // - 数值计算
    // - WASM插件
    // 7. 排版Ⅱ
    // - 代码高亮
    // - 参考文献
    // - 文档大纲
    // 8. 科技排版
    // - 数学模式
    // - 数学公式和定理
    // - 物理公式
    // - 化学方程式
    // 9. 图表
    // - 立体几何
    // - 统计图
    // - 状态机
    // - 电路图
    // 10. 模板
    // 11. 参考Ⅰ
    // - 基本类型
    // - 内置类型
    // - 时间
    // - 高级颜色
    // - 长度单位
    // 12. 参考Ⅱ
    // - 图形
    = 专题
    - #chapter("topics/writing-math.typ")[编写一篇数学文档]
    // https://github.com/PgBiel/typst-oxifmt/blob/main/oxifmt.typ
    // - #chapter("topics/format-lib.typ")[制作一个格式化库]
    // https://github.com/Pablo-Gonzalez-Calderon/showybox-package/blob/main/showy.typ
    - #chapter("topics/writing-component-lib.typ")[制作一个组件库]
    - #chapter("topics/writing-plugin-lib.typ")[制作一个外部插件]
    - #chapter("topics/call-externals.typ")[在Typst内执行Js、Python、Typst等]
    // https://github.com/frugal-10191/frugal-typst
    - #chapter("topics/template-book.typ")[制作一个书籍模板]
    // chicv
    - #chapter("topics/template-cv.typ")[制作一个CV模板]
    // official template
    - #chapter("topics/template-paper.typ")[制作一个IEEE模板]
    = 专题 — 公式和定理
    - #chapter("science/chemical.typ")[化学方程式]
    - #chapter("science/algorithm.typ")[伪算法]
    - #chapter("science/theorem.typ")[定理环境]
    = 专题 — 杂项
    - #chapter("misc/font-setting.typ")[字体设置]
    // - #chapter("misc/font-style.typ")[伪粗体、伪斜体]
    - #chapter("misc/code-syntax.typ")[自定义代码高亮规则]
    - #chapter("misc/code-theme.typ")[自定义代码主题]
    - #chapter("misc/text-processing.typ")[读取外部文件和文本处理]
    = 专题 — 绘制图表
    - #chapter("graph/table.typ")[制表]
    - #chapter("graph/solid-geometry.typ")[立体几何]
    - #chapter("graph/digraph.typ")[拓扑图]
    - #chapter("graph/statistics.typ")[统计图]
    - #chapter("graph/state-machine.typ")[状态机]
    - #chapter("graph/electronics.typ")[电路图]
    = 专题 — 附录Ⅱ
    - #chapter("tutorial/reference-grammar.typ")[语法示例检索表Ⅱ]
    - #chapter("template/slides.typ")[演示文稿（PPT）]
    - #chapter("template/paper.typ")[论文模板]
    - #chapter("template/book.typ")[书籍模板]
    = 专题参考
    - #chapter("tutorial/reference-counter-state.typ")[计数器和状态]
    - #chapter("tutorial/reference-length.typ")[长度单位]
    - #chapter("tutorial/reference-layout.typ")[布局函数]
    - #chapter("tutorial/reference-table.typ")[表格]
    - #chapter("tutorial/reference-outline.typ")[文档大纲]
  ],
)

#build-meta(dest-dir: "../dist")

// #get-book-meta()

// re-export page template
#import "/typ/templates/page.typ": heading-reference, project
#let page = project
#let ref-page = project.with(kind: "reference-page")
#let cross-link = cross-link
#let heading-reference = heading-reference


================================================
FILE: src/ebook.typ
================================================
#import "@preview/shiroa:0.2.3": *
#import "/typ/templates/ebook.typ"

#show: ebook.project.with(
  title: "typst-tutorial-cn",
  display-title: "Typst中文教程",
  spec: "book.typ",
  // set a resolver for inclusion
  styles: (
    inc: it => include it,
  ),
)


================================================
FILE: src/figures.typ
================================================
#import "@preview/fletcher:0.5.7" as fletcher: edge, node
#import "/typ/templates/page.typ": is-light-theme, main-color, page-width
#import "mod.typ": typst-func

#let figure-typst-arch(
  stroke-color: main-color,
  light-theme: is-light-theme,
) = {
  let node = node.with(stroke: main-color + 0.5pt)
  let xd = align.with(center)

  fletcher.diagram(
    node-outset: 2pt,
    axes: (ltr, btt),
    // nodes
    node((0, 0), xd[文件解析\ （Parsing）]),
    node((1.5, 0), xd[表达式求值\ （Evaluation）]),
    node((3, 0), xd[内容排版\ （Typesetting）]),
    node((3, -1), xd[结构导出\ （Exporting）]),
    // edges
    edge((0, 0), (1.5, 0), "..}>", bend: 25deg),
    edge((1.5, 0), (0, 0), xd[`import`或\ `include`], "..}>", bend: 25deg),
    edge((1.5, 0), (3, 0), "..}>", bend: 25deg),
    edge((3, 0), (1.5, 0), xd[`styled`等], "..}>", bend: 25deg),
    edge((3, 0), (3, -1), "..}>", bend: 25deg),
  )
}

#let figure-content-decoration(
  stroke-color: main-color,
  light-theme: is-light-theme,
  width: page-width,
) = {
  // let node = node.with(stroke: main-color + 0.5pt)
  let node-text = align.with(center)

  // todo: 消除重复
  if width < 500pt {
    let node-rect-text(content) = rect(node-text(content), width: 125pt)
    fletcher.diagram(
      node-outset: 2pt,
      axes: (ltr, btt),
      // nodes
      node((0, 0), node-rect-text[```typ 左#[一段文本]右```]),
      node((0, -1.5), node-rect-text(```typc text(blue)```)),
      node((0, -3), node-rect-text([左] + text(blue)[一段文本] + [右])),

      node((0, -0.5 + 0), node-text[选中内容]),
      node((0, -0.5 + -1.5), node-text[对内容块应用#typst-func("text")函数]),
      node((0, -0.5 + -3), node-text[最终效果]),

      // edges
      edge((0, -0.5 + 0), (0, -1.5), "..}>"),
      edge((0, -0.5 + -1.5), (0, -3), "..}>"),
    )
  } else {
    fletcher.diagram(
      node-outset: 2pt,
      axes: (ltr, btt),
      // nodes
      node((0, 0), node-text[```typ 左#[一段文本]右```]),
      node((1.5, 0), node-text(```typc text(blue)```)),
      node((3, 0), node-text([左] + text(blue)[一段文本] + [右])),
      node((0, -0.5), node-text[选中内容]),
      node((1.5, -0.5), node-text[对内容块应用#typst-func("text")函数]),
      node((3, -0.5), node-text[最终效果]),
      // edges
      edge((0, 0), (1.5, 0), "..}>"),
      edge((1.5, 0), (3, 0), "..}>"),
    )
  }
}


================================================
FILE: src/graph/digraph.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [拓扑图])


================================================
FILE: src/graph/electronics.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [电路图])


================================================
FILE: src/graph/mod.typ
================================================
#import "/src/book.typ"
#import "/typ/templates/page.typ"

#import "../mod.typ": code, exec-code, todo-box


================================================
FILE: src/graph/solid-geometry.typ
================================================
#import "mod.typ": *
#import "@preview/cetz:0.3.4": *

#show: book.page.with(title: "立体几何")

== 变换「坐标系」

在绘制立体图形（以及其他抽象图形）时，最重要的思路是变换「坐标系」（Viewport），以方便绘制。

#code(```typ
#import "@preview/cetz:0.3.4": *
#canvas({
  import draw: *
  let axis-line(p) = {
    line((0, 0), (x: 1.5), stroke: red)
    line((0, 0), (y: 1.5), stroke: blue)
    line((0, 0), (z: 1.5), stroke: green)
    circle((0, 0, 0), fill: black, radius: 0.05)
    content((-0.4, 0.1, -0.2), p)
  }
  set-viewport((0, 0, 0), (4, 4, -4), bounds: (4, 4, 4))
  axis-line("A")
  set-viewport((4, 4, 4), (0, 0, 0), bounds: (4, 4, 4))
  axis-line("B")
})
```)

== 使用「空间变换」

由于「空间变换」（Transformation）的存在，你可以先绘制基本图形，再使用变换完成图形的绘制：

```typ
#let 六面体 = {
  import draw: *
  let neg(u) = if u == 0 { 1 } else { -1 }
  for (p, c) in (
    ((0, 0, 0), black), ((1, 1, 0), red),
    ((1, 0, 1), blue), ((0, 1, 1), green),
  ) {
    line(vector.add(p, (0, 0, neg(p.at(2)))), p, stroke: c)
    line(vector.add(p, (0, neg(p.at(1)), 0)), p, stroke: c)
    line(vector.add(p, (neg(p.at(0)), 0, 0)), p, stroke: c)
  }
}
```

#let 六面体 = {
  import draw: *
  let neg(u) = if u == 0 {
    1
  } else {
    -1
  }
  for (p, c) in (
    ((0, 0, 0), black),
    ((1, 1, 0), red),
    ((1, 0, 1), blue),
    ((0, 1, 1), green),
  ) {
    line(vector.add(p, (0, 0, neg(p.at(2)))), p, stroke: c)
    line(vector.add(p, (0, neg(p.at(1)), 0)), p, stroke: c)
    line(vector.add(p, (neg(p.at(0)), 0, 0)), p, stroke: c)
  }
}

运行以下代码你将获得：

#code(
  ```typ
  #import "@preview/cetz:0.3.4": *
  #align(center, canvas(六面体))
  ```,
  scope: (六面体: 六面体),
)

#pagebreak(weak: true)

== 六面体

#code(
  ```typ
  #import "@preview/cetz:0.3.4": *
  #align(center, canvas({
    import draw: *
    set-viewport((0, 0, 0), (4, 4, -4), bounds: (1, 1, 1))
    group(name: "S", translate((0, 0, 0)) + {
      anchor("O", (0, 0, 0))
      六面体
    })
    group(name: "T", translate((1.4, 0, 0)) + scale(x: 120%, y: 80%) + {
      line((0, 0, 0.5), (0.5, 0, 0), stroke: black)
      anchor("A", (0, 0, 0.5))
      anchor("B", (0.5, 0, 0))
      六面体
    })
    circle("S.O", fill: black, radius: 0.05 / 4)
    content((rel: (-0.08, 0.04, 0), to: "S.O"), [O])
    circle("T.A", fill: black, radius: 0.05 / 4)
    content((rel: (0.02, -0.08, 0), to: "T.A"), [A])
    circle("T.B", fill: black, radius: 0.05 / 4)
    content((rel: (0, 0.1, 0), to: "T.B"), [B])
  }))
  ```,
  scope: (六面体: 六面体),
)


================================================
FILE: src/graph/state-machine.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [状态机])


================================================
FILE: src/graph/statistics.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [统计图])


================================================
FILE: src/graph/table.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [制表])


================================================
FILE: src/intermediate/mod.typ
================================================
#import "/src/book.typ"
#import "../mod.typ": code as _code, exec-code as _exec-code, pro-tip, refs, todo-box, typst-func
#import "/typ/templates/page.typ": main-color
#import "/typ/embedded-typst/lib.typ": default-cjk-fonts, default-fonts, svg-doc


================================================
FILE: src/introduction.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [导引])

本书面向所有Typst用户，按三种方式讲解Typst语言。《教程》等章节循序渐进，讲述了Typst的排版方式和原理；《参考》等章节拓展广度；《专题》等则专注解决具体问题。本书希望缓解Typst相关资料严重缺失的问题，与官方文档相互补充，帮助大家入门和学习Typst。

其中，《教程》的主要定位是较低的阅读门槛。即使你没有编程语言基础，也能通过《教程》上手使用Typst，在日常生活中编写各式各样的文档。

《教程》的另一个作用是串联知识。有很多排版技巧和问题缺乏深度，不适合放在《教程》内。为了避免让章节冗长，这些知识会被单独列在《参考》或《专题》中，供《教程》引用。这样，擅于编程的同学也可以略读《教程》，重点阅读放在关联的章节上。

同时，本书也会不时总结在使用Typst时的疑难杂症。

== 为什么学习Typst？

在开始之前，让我们考虑Typst的名称解释和用途。Typst首先是一种用于排版文档的标记语言，它旨在易于学习、快速且用途广泛。Typst还同时指代编译器本身。Typst编译器读取并解释带有标记的文本文件，产生适合不同终端阅读的PDF文档。Typst也支持导出其他格式，例如SVG和PNG。

Typst的性能很好，是撰写长篇文本的极佳选择，例如书籍和报告。 并且，Typst 非常适合书写包含数学公式的文档，例如数学、物理和工程领域的论文。 由于其编程特性，它也适用于自动化生成一系列相同样式的文档（例如作业、丛书和发票）。

== 阅读本教程前，您需要了解的知识

你不需要了解任何前置知识，所需的仅仅是安装Typst，并跟着本教程的在线示例一步步学习。

== 其他参考资料

- #link("https://typst-doc-cn.github.io/docs/tutorial/")[官方文档翻译 - 入门教程]
- #link("https://typst-doc-cn.github.io/docs/chinese/")[非官方中文用户指南]
- #link("https://typst-doc-cn.github.io/docs/reference/")[官方文档翻译 - 参考]
- #link("https://sitandr.github.io/typst-examples-book/book/about.html")[Typst Example Books]

= 配置Typst运行环境

== 使用官方的webapp（推荐）

官方提供了*在线且免费*的多人协作编辑器。该编辑器会从远程下载WASM编译器，并在你的浏览器内运行编辑器，为你提供预览服务。你可以注册一个账户并开箱即用该编辑器。

#figure(image("/assets/files/editor-webapp.png"), caption: [本书作者在网页中打开webapp的瞬间])

该编辑器的速度相比许多LaTeX编辑器都有显著优势。这是因为：
- 编辑文档后，即时预览基本不会被网络请求阻塞。
- Typst脚本皆在本地浏览器中运行。
- Typst编译器本身性能极其优越。

*注意：如果遇到无法加载的问题，你需要检查你的网络环境，如有必要请使用科学上网工具。*

== 使用VSCode编辑（推荐）

打开扩展界面，搜索并安装 Tinymist 插件。它会为你提供语法高亮，代码补全，代码格式化，即时预览等功能。

#figure(image("/assets/files/editor-vscode.png"), caption: [本书作者在VSCode中预览并编辑本文的瞬间])

该编辑器的性能不如webapp。这是因为：
- 编译器与预览器是两个不同的进程，有通信开销。
- 用户事件和文件IO有可能增加E2E延时。

但是：
- 大部分时间下，你感受不到和webapp之间的性能差异。Typst真的非常快。
- 你可以离线编辑Typst文档，无需任何网络连接，例如本书的部分章节是在飞机上完成的。
- 你可以免费使用部分Typst Pro的功能。你可以在文件系统中管理你所有的源代码，实施包括但不限于使用git等源码管理软件等操作。

== 使用其他编辑器编辑

你可以在这些编辑器中手动安装Tinymist LSP服务或Typst相关插件。自2024年初，Neovim和Emacs已经可以与VSCode一样，已经可以有很好的Typst编辑体验。

== 使用typst-cli与PDF阅读器

Typst 的 CLI 可从不同的来源获得。你可以在#link("https://github.com/typst/typst/releases/")[发布页面]获得最新版本的 Typst 的源代码和预构建的二进制文件。下载适合你平台的存档并将其放在“PATH”中的目录中。及时了解未来发布后，你只需运行```bash typst update```即可。

你可以通过不同的包管理器安装Typst。请注意，包管理器中的版本可能落后于最新版本。
- Linux：查看#link("https://repology.org/project/typst/versions")[Typst on Repology。]
- macOS：使用brew：
  ```bash
  brew install typst
  ```
- Windows：使用winget：
  ```bash
  winget install --id Typst.Typst
  ```

你还可以使用#link("https://rustup.rs/")[Rust]、Nix或Docker安装Typst。更多信息请查看#link("https://github.com/typst/typst?tab=readme-ov-file#usage")[官方英文说明]。

安装好CLI之后，你就可以在命令行里运行Typst编译器了。以下命令将工作目录下的文件编译为`file.pdf`：

```bash
typst compile file.typ
```

为了增量编译和预览PDF，你需要让Typst编译器运行在监视模式（watch）下：

```bash
typst watch file.typ
```

当你启动Typst编译器后，你可以使用你喜欢的编辑器编辑Typst文档，并使用你喜欢的PDF阅读器打开编译好的PDF文件。PDF阅读器推荐使用：

- 在Windows下使用#link("https://www.sumatrapdfreader.org/free-pdf-reader")[Sumatra PDF]。

== 各Typst运行环境的比较

#{
  set align(center)
  table(
    columns: if get-page-width() < 500pt {
      (1fr, 1fr, 1fr, 1fr, 1fr, 1fr, 1fr)
    } else {
      (1fr, 1fr, 1fr, 5em, 5em, 5em, 10em)
    },
    align: horizon + center,
    [名称], [编辑器], [编译器环境], [预览方案], [是否支持即时编译], [语言服务], [备注],
    [WebAPP], [Code Mirror], [wasm], [渲染图片], [是], [良好], align(left)[开箱即用],
    [VSCode], [VSCode], [native], [webview], [是], [优秀], align(left)[简单上手，定制性好],
    [neovim], [neovim], [native], [webview], [是], [良好], align(left)[不易安装，定制性强],
    [Emacs], [Emacs], [native], [webview], [是], [良好], align(left)[难以安装],
    [typst-cli], [任意编辑器], [native], [任意PDF阅读器], [否], [无], align(left)[简单上手，灵活组合],
  )
}

= 如何阅读本书

本书主要分为三个部分：

+ 教程：介绍Typst的语法、原理和理念，以助你深度理解Typst。
+ 参考：完整介绍Typst中内置的函数和各种外部库，以助你广泛了解Typst的能力，用Typst实现各种排版需求。
+ 专题等：与参考等章节的区别是，每个专题都专注解决一类问题，而不会讲解函数的用法。

每个部分都包含大量例子，它们各有侧重：

- 教程中的例子希望切中要点，而避免冗长的全面的展示特性。
- 参考中的例子希望讲透元素和函数的使用，例子多选自过去的一年中大家常问的问题。
- 专题中的例子往往有连贯性，从前往后带你完成一系列专门的问题。专题中的例子假设你已经掌握了相关知识，只以最专业的代码解决该问题。

#pro-tip[
  本书会随时夹带一些“Pro Tip”。这些“Pro Tip”由蓝色框包裹。它们告诉你一些较难理解的知识点。

  你可以选择在初次阅读时*跳过*这些框，而不影响对正文的理解。但建议你在阅读完整本书后回头观看所不理解的那些“Pro Tip”。
]

以下是推荐的阅读方法：

+ 首先阅读《基础教程》排版Ⅰ的两篇文章，即《初识标记模式》和《初识脚本模式》。

  经过这一步，你应该可以像使用Markdown那样，编写一篇基本不设置样式的文档。同时，这一步的学习难度也与学习完整Markdown语法相当。

+ 接着，阅读《基础教程》脚本Ⅰ的三篇文章。

  经过这一步，你应该已经基本入门了Typst的标记和脚本。此时，你和进阶用户的唯一区别是，你还不太会使用高级的样式配置。推荐：
  - 如果你熟练阅读英语，推荐主要参考#link("https://typst.app/docs/")[官方文档]的内容。
  - 否则，推荐继续阅读本书剩下的内容，并参考#link("https://typst-doc-cn.github.io/docs/")[非官方中文文档]的内容。

  有什么问题？
  - 本书只有《基础教程》完成了校对和润色，后续部分还非常不完善。甚至《基础教程》部分还有待改进。
  - #link("https://typst-doc-cn.github.io/docs/")[非官方中文文档]是GPT机翻后润色的的结果，有可能错翻、漏翻，内容也可能有些许迟滞。

+ 接着，阅读《基础教程》脚本Ⅱ和排版Ⅲ的五篇文章。

  这两部分分别介绍了如何使用Typst的模块机制与状态机制。模块允许你将文档拆分为多个文件。状态则类似于其他编程语言中的全局变量的概念，可用于收集和维护数据。

+ 最后，同时阅读《基础参考》和《进阶教程》。你可以根据你的需求挑选《基础参考》的部分章节阅读。即便不阅读任何《基础参考》中的内容，你也可以继续阅读《进阶教程》。

  经过这一步，你应该已经完全学会了目前Typst的所有理念与内容。

= 许可证

*typst-tutorial-cn* 所有的源码和文档都在#link("https://www.apache.org/licenses/LICENSE-2.0")[Apache License v2.0]许可证下发布.


================================================
FILE: src/misc/code-syntax.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [自定义代码高亮规则])


================================================
FILE: src/misc/code-theme.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [自定义代码主题])


================================================
FILE: src/misc/font-setting.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [字体设置])

#let table-lnk(name, ref, it, scope: (:), res: none, ..args) = (
  align(center + horizon, link("todo", name)),
  it,
  align(
    horizon,
    {
      set heading(bookmarked: false, outlined: false)
      eval(it.text, mode: "markup", scope: scope)
    },
  ),
)


================================================
FILE: src/misc/mod.typ
================================================
#import "/src/book.typ"
#import "/typ/templates/page.typ"

#import "../mod.typ": code, exec-code


================================================
FILE: src/misc/text-processing.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [读取外部文件和文本处理])


================================================
FILE: src/mod.typ
================================================
#import "/src/book.typ"
#import "/typ/templates/page.typ"
#import "/typ/templates/term.typ": _term
#import "/typ/templates/side-notes.typ": side-note, side-attrs
#import "/typ/templates/page.typ": main-color, get-page-width, plain-text
#import "/typ/templates/template-link.typ": enable-heading-hash

#import "/typ/typst-meta/docs.typ": typst-v11

#let refs = {
  let cl = book.cross-link
  (
    writing-markup: cl.with("/basic/writing-markup.typ"),
    writing-scripting: cl.with("/basic/writing-scripting.typ"),
    scripting-base: cl.with("/basic/scripting-literal-and-variable.typ"),
    scripting-complex: cl.with("/basic/scripting-block-and-expression.typ"),
    scripting-modules: cl.with("/intermediate/scripting-modules.typ"),
    content-scope-style: cl.with("/intermediate/content-scope-and-style.typ"),
    content-stateful: cl.with("/intermediate/content-stateful.typ"),
    ref-typebase: cl.with("/basic/reference-typebase.typ"),
    ref-type-builtin: cl.with("/basic/reference-type-builtin.typ"),
    ref-color: cl.with("/basic/reference-color.typ"),
    ref-visualization: cl.with("/basic/reference-visualization.typ"),
    ref-bibliography: cl.with("/basic/reference-bibliography.typ"),
    ref-datetime: cl.with("/basic/reference-date.typ"),
    ref-math-mode: cl.with("/basic/reference-math-mode.typ"),
    ref-math-symbols: cl.with("/basic/reference-math-symbols.typ"),
    ref-data-process: cl.with("/basic/reference-data-process.typ"),
    ref-wasm-plugin: cl.with("/basic/reference-wasm-plugin.typ"),
    ref-grammar: cl.with("/basic/reference-grammar.typ"),
    ref-layout: cl.with("/intermediate/reference-layout.typ"),
    ref-length: cl.with("/intermediate/reference-length.typ"),
    misc-font-setting: cl.with("/misc/font-setting.typ"),
  )
}

#let term-list = (
  "array literal": "数组字面量",
  "blocky raw block": "块代码片段",
  "boolean literal": "布尔字面量",
  "code mode": "脚本模式",
  "codepoint": "码位",
  "codepoint width": "码位宽度",
  "character": "字符",
  "comment": "注释",
  "content": "内容",
  "consistency": "一致性",
  "content block": "内容块",
  "delimiter": "定界符",
  "dictionary literal": "字典字面量",
  "floating-point literal": "浮点数字面量",
  "function identifier": "函数名标识符",
  "emphasis semantics": "强调语义",
  "escape sequences": "转义序列",
  "exponential notation": "指数表示法",
  "expression": "表达式",
  "field": "域成员",
  "field access": "访问域成员",
  "function body expression": "函数体表达式",
  // https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/String
  "grapheme cluster": "字素簇",
  "grapheme cluster width": "字素簇宽度",
  "initialization expression": "初始值表达式",
  "integer literal": "整数字面量",
  "interpret": "解释",
  "interpreter": "解释器",
  "interpreting mode": "解释模式",
  "introspection function": "自省函数",
  "lexicographical order": "字典序",
  "line break": "换行符",
  "literal": "字面量",
  "markup mode": "标记模式",
  "math mode": "数学模式",
  "none literal": "空字面量",
  "nearest": "最近",
  "raw block": "代码片段",
  "representation": "表示法",
  "parameter identifier": "参数标识符",
  "parser": "解析器",
  "pattern": "模式串",
  "placeholder": "占位符",
  "shorthand": "速记符号",
  "scripting": "脚本",
  "string literal": "字符串字面量",
  "strong semantics": "着重语义",
  "syntactic predecessor": "语法前驱",
  "tilde diacritical marks": "波浪变音符号",
  "type": "类型",
  "utf-8 encoding": "UTF-8编码",
  "value": "值",
  "variable identifier": "变量名标识符",
  "whitespace": "空白字符",
)

#let mark-list = (
  "=": "等于号",
  "*": "星号",
  "#": "井号",
  "_": "下划线",
  "`": "反引号",
  "hyphen": "连字号",
  "-": "减号",
  "+": "加号",
  "\\": "反斜杠",
  "/": "斜杠",
  "~": "波浪号",
  ".": "点号",
  ";": "分号",
)

#let exec-code(cc, res: none, scope: (:), eval: eval) = {
  rect(
    width: 100%,
    inset: 10pt,
    context {
      // Don't corrupt normal headings
      set heading(outlined: false)

      let prev = enable-heading-hash.get()
      enable-heading-hash.update(false)

      if res != none {
        res
      } else {
        eval(cc.text, mode: "markup", scope: scope)
      }

      enable-heading-hash.update(prev)
    },
  )
}

#let _code-al = if get-page-width() >= 500pt {
  left
} else {
  top
}

// al: alignment
#let code(cc, code-as: none, res: none, scope: (:), eval: eval, exec-code: exec-code, al: _code-al) = {
  let code-as = if code-as == none {
    cc
  } else {
    code-as
  }

  let vv = exec-code(cc, res: res, scope: scope, eval: eval)
  if al == left {
    layout(lw => context {
      let width = lw.width * 0.5 - 0.5em
      let u = box(width: width, code-as)
      let v = box(width: width, vv)

      let u-box = measure(u)
      let v-box = measure(v)

      let height = calc.max(u-box.height, v-box.height)
      stack(
        dir: ltr,
        {
          set rect(height: height)
          u
        },
        1em,
        {
          rect(height: height, width: width, inset: 10pt, vv.body)
        },
      )
    })
  } else {
    code-as
    vv
  }
}

#let fg-blue = main-color.mix(rgb("#0074d9"))
#let pro-tip(content) = context {
  let attr = side-attrs.get()
  let ext = attr.width + attr.gutter
  move(
    dx: -ext,
    block(
      width: 100% + ext,
      breakable: false,
      inset: (x: 0.65em, y: 0.65em, left: 0.65em * 0.6),
      radius: 4pt,
      fill: rgb("#0074d920"),
      {
        set text(fill: fg-blue)
        stack(
          dir: ltr,
          move(dy: 0.1em, image("/assets/files/info-icon.svg", width: 1em)),
          0.2em,
          box(width: 100% - 1.2em, v(0.2em) + content),
        )
      },
    ),
  )
}

#let fg-red = main-color.mix(red)
#let todo-color = fg-red
#let todo-box(content) = context {
  let attr = side-attrs.get()
  let ext = attr.width + attr.gutter
  move(
    dx: -ext,
    block(
      width: 100% + ext,
      breakable: false,
      inset: (x: 0.65em, y: 0.65em, left: 0.65em * 0.6),
      radius: 4pt,
      fill: fg-red.transparentize(80%),
      {
        set text(fill: fg-red)
        stack(
          dir: ltr,
          move(dy: 0.4em, text(size: 0.5em)[todo]),
          0.2em,
          box(width: 100% - 1.2em, v(0.2em) + content),
        )
      },
    ),
  )
}

/// This function is to render a text string in monospace style and function
/// color in your defining themes.
///
/// ## Examples
///
/// ```typc
/// typst-func("list.item")
/// ```
///
/// Note: it doesn't check whether input is a valid function identifier or path.
#let typst-func(it) = [
  #raw(plain-text(it) + "()", lang: "typc") <typst-raw-func>
]

#let show-answer = false
// #let show-answer = true

/// Make an exercise item.
///
/// - question (content): The question to ask.
/// - answer (content): The answer to the question.
/// -> content
#let exercise(question, answer) = {
  enum.item(
    question
      + if show-answer {
        parbreak() + [答：] + answer
      },
  )
}

/// Make a term item.
///
/// - term (string): The name of the term.
/// - postfix (string): The postfix to conform typst bug.
/// - en (bool): Whether to show the English name.
/// -> content
#let term(term, en: none) = _term(term-list, term, en: en)

#let mark(mark) = _term(
  mark-list,
  mark,
  en: if mark == "hyphen" {
    raw("-")
  } else {
    raw(mark)
  },
)

#let ref-bookmark = side-note

#let highlighter(it, k) = {
  if k == "method" {
    set text(fill: rgb("4b69c6"))
    raw(it)
  } else if k == "keyword" {
    set text(fill: rgb("8b41b1"))
    raw(it)
  } else if k == "var" {
    set text(fill: blue.mix(main-color))
    raw(it)
  } else {
    raw(it)
  }
}

#let darkify(clr) = clr.mix(main-color.negate()).saturate(30%)

#let ref-ty-locs = (
  "int": refs.ref-typebase,
  "bool": refs.ref-typebase,
  "float": refs.ref-typebase,
  "str": refs.ref-typebase,
  "array": refs.ref-typebase,
  "dict": refs.ref-typebase,
  "none": refs.ref-typebase,
  "ratio": refs.ref-length,
  "alignment": refs.ref-layout,
  "version": refs.ref-type-builtin,
  "any": refs.ref-type-builtin,
  "bytes": refs.ref-type-builtin,
  "label": refs.ref-type-builtin,
  "type": refs.ref-type-builtin,
  "regex": refs.ref-type-builtin,
)

#let show-type(ty) = {
  h(3pt)
  ref-ty-locs.at(ty)(
    reference: label("reference-type-" + ty),
    box(fill: darkify(rgb("eff0f3")), outset: 2pt, radius: 2pt, raw(ty)),
  )
  h(3pt)
}

#let ref-signature(name, kind: "scope") = {
  let fn = if kind == "scope" {
    typst-v11.scoped-items.at(name)
  } else if kind == "cons" {
    let ty = typst-v11.types.at(name)
    ty.body.content.constructor
  } else {
    typst-v11.funcs.at(name)
  }

  context {
    let attr = side-attrs.get()
    let ext = attr.width + attr.gutter

    move(
      dx: -ext,
      block(
        fill: rgb("#add5a220"),
        radius: 2pt,
        width: 100% + ext,
        inset: (x: 1pt, y: 5pt),
        {
          set par(justify: false)
          set text(fill: main-color.mix(rgb("eff0f3").negate()))
          highlighter("fn", "keyword")
          raw(" ")
          highlighter(name, "method")
          raw("(")
          fn
            .params
            .map(param => {
              highlighter(param.name, "var")
              ": "
              param.types.map(show-type).join()
            })
            .join(raw(", "))
          raw(")")
          if fn.returns.len() > 0 {
            raw(" ")
            box(raw("->"))
            raw(" ")
            fn.returns.map(show-type).join()
          }
        },
      ),
    )
  }
}
#let ref-func-signature = ref-signature.with(kind: "func")
#let ref-cons-signature = ref-signature.with(kind: "cons")
#let ref-method-signature = ref-signature

#let f() = { }


================================================
FILE: src/prefaces/acknowledgement.typ
================================================

#import "mod.typ": *

#show: book.page.with(title: "致谢")

#let MyriadDreamin = link("https://github.com/Myriad-Dreamin")[Myriad Dreamin]
#let OrangeX4 = link("https://github.com/OrangeX4")[OrangeX4]
#let GiggleDing = link("https://github.com/GiggleDing")[GiggleDing]

本文档的主要部分由#MyriadDreamin 编写。

#OrangeX4 参与了基本教程部分的勘误。

#GiggleDing 编写了《参考：常用数学符号》。

在此表示感谢。


================================================
FILE: src/prefaces/license.typ
================================================

#import "mod.typ": *
#page({
  set text(size: 10.5pt)
  set block(spacing: 1.5em)

  show "TERMS AND CONDITIONS FOR USE": it => {
    v(0.5em)
    it
  }
  show "APPENDIX": it => {
    v(1fr)
    it
  }
  eval(read("/LICENSE"), mode: "markup")
  v(5em)
})


================================================
FILE: src/prefaces/mod.typ
================================================
#import "/src/book.typ"

#import "../mod.typ": code, exec-code


================================================
FILE: src/science/algorithm.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [伪算法])


================================================
FILE: src/science/chemical.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [化学方程式])


================================================
FILE: src/science/mod.typ
================================================
#import "/src/book.typ"
#import "/typ/templates/page.typ"

#import "../mod.typ": code, exec-code


================================================
FILE: src/science/theorem.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [定理环境])


================================================
FILE: src/template/book.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [书籍模板])


================================================
FILE: src/template/mod.typ
================================================
#import "/src/book.typ"
#import "/typ/templates/page.typ"

#import "../mod.typ": code, exec-code


================================================
FILE: src/template/paper.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [论文模板])


================================================
FILE: src/template/slides.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [演示文稿（PPT）])


================================================
FILE: src/topics/call-externals.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [在Typst内执行Js、Python、Typst等])


================================================
FILE: src/topics/mod.typ
================================================
#import "/src/book.typ"
#import "/typ/templates/page.typ"

#import "../mod.typ": code, exec-code, refs


================================================
FILE: src/topics/template-book.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [制作一个书籍模板])


================================================
FILE: src/topics/template-cv.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [制作一个CV模板])


================================================
FILE: src/topics/template-paper.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [制作一个IEEE模板])


================================================
FILE: src/topics/writing-component-lib.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [制作一个组件库])


================================================
FILE: src/topics/writing-math.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [编写一篇数学文档])


================================================
FILE: src/topics/writing-plugin-lib.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [制作一个外部插件])


================================================
FILE: src/tutorial/doc-modulize.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [模块化（多文件）])

我们接下来学习脚本剩余的所有知识。总结而言，每个源文件对应一个模块；每个模块导出多个「变量声明」和一个「文档（内容）树」。回忆编译流程，求值按照「控制流」顺序执行表达式。「排版」（typeset）时，按照「文档树」顺序更新状态和排版结果。迭代排版多次，直到布局不再发生变化。

本节首先来讲讲Typst中的模块。正如我们在《教程：脚本模式》中所说的，Typst提供了脚本语言方便排版。但事实上，写作时若能少写甚至不写脚本，这才算真正的便捷。我们总希望Typst能够允许我们以一种优雅的方式#strike[复制粘贴]引入已有代码。理想情况下，只需两行代码便可引入前辈写好的模板：

#```typ
#import "@preview/senpai-no-awesome-template.typ:0.x.x": *
#show: template.with(..)
```

模块便是为复制而生。


Typst的模块（module）机制非常简单：每个文件都是一个独立的模块。它允许你：
+ 将一份文档分作多个文件编写。
+ 使用本机器或网上的模板或库。

由于Typst的模块机制过于简单，本节主要伴随讲解一些日常使用模块机制时所遇到的问题，而不会涉及很多需要理解的地方。

== 根目录

根目录是一个重要的编译参数。Typst早在v0.1.0时就禁止访问*根目录以外的内容*，以保证安全执行代码。最坏情况下，*其他人编写的Typst脚本（来自互联网）*可以访问根目录下所有的文件。

你所使用的工具可能会为你自动配置*根目录*。

#pro-tip[
  + 当你使用`typst-cli`程序时，根目录默认为文档所在目录。你也可以通过`--root`命令行参数手动指定一个根目录。例如你可以指定当前工作目录的父文件夹作为编译程序的根目录：

    ```bash
    typst c --root ..
    ```
  + 当你使用VSCode的tinymist程序时，为了方便多文件的编写，根目录默认为你所打开的文件夹。如果你打开一个VSCode工作区，则根目录相对于离你所编辑文件最近的工作目录。
]

一个常见的错误做法是，为了共享本地代码或模板，在使用`typst-cli`的时候将根目录指定为系统的根目录。以下使用方法将有可能导致个人隐私泄露：

```bash
typst c --root "C:\\" # Windows
typst c --root / # Linux或macOS
```

并访问你系统中的某处文件。

```typ
#import "/Users/me/templates/book.typ": book-template
```

本节将介绍另外一种创建本地「库」（package）的方式以在Typst项目之间安全地共享代码和资源。

== 绝对路径与相对路径

我们已经讲解过`read`函数和`include`语法，其中都有路径的概念。

如果路径以字符`/`开头，则其为「绝对路径」。绝对路径相对于「根目录」解析。若设置了根目录为#text(red, `/OwO/`)，则路径`/src/chapter1.typ`对应文件系统中的#text(red, `/OwO/`)`src/chapter1.typ`。

#code(
  ```typ
  #include "/src/chapter1.typ"
  ```,
  res: [我是#text(red, `/OwO/`)`src/chapter1.typ`文件！],
)

否则，路径不以字符`/`开头，则其「相对路径」。相对路径相对于当前文件的父文件夹解析。若我们正在编辑#text(red, `/OwO/`)#text(blue, `src/`)`main.typ`文件，则路径`chapter2.typ`对应文件系统中的#text(red, `/OwO/`)#text(blue, `src/`)`chapter2.typ`。

#code(
  ```typ
  #include "chapter2.typ"
  ```,
  res: [我是#text(red, `/OwO/`)#text(blue, `src/`)`chapter2.typ`文件！],
)

== 「import」语法与「模块」

Typst中的模块概念相当简单。你只需记住：每个文件都是一个模块。

#let m1-code = raw(read("packages/m1.typ").trim().replace("\r", ""), lang: "typ", block: true)

假设有一个文件位于`packages/m1.typ`：

#m1-code

此时文件名就是所引入模块的名称，那么`packages/`#text(red, `m1`)`.typ`就对应#text(red, `m1`)模块。

你可以简单通过绝对路径或相对路径引入一个文件模块：

#code(```typ
#import "packages/m1.typ"
#repr(m1)
```)

你可以通过这个「模块」对象访问到文件顶层作用域的变量或函数。例如在`m1`文件中，你可以访问到其顶层作用域中的`add`或`sub`函数。

#code(```typ
#import "packages/m1.typ"
#m1.add \
#m1.sub
```)

你可以在引入模块名的同时将其更名为你想要的名称：

#code(```typ
#{
  import "packages/m1.typ" as m2
  repr(m2)
} \
// 等价于
#{
  import "packages/m1.typ"
  let m2 = m1
  repr(m2)
}
```)

你可以在冒号后添加一个星号表示直接引入模块中所有的函数：

#code(```typ
// 引入所有函数
#import "packages/m1.typ": *
#type(add), #type(sub)
```)

你也可以在冒号后追加一个逗号分隔的名称列表，部分引入来自其他文件的变量或函数：

#code(```typ
// 仅仅引入`sub`函数
#import "packages/m1.typ": sub
#type(sub) \
// 引入`add`和`sub`函数
#import "packages/m1.typ": add, sub
#type(add), #type(sub) \
```)

注意，本地的变量声明与`import`进来的变量声明都会覆盖Typst内置的变量声明。例如Typst内置的`sub`函数实际上为取下标函数。你可以在引入外部变量的同时更名以避免可能的名称冲突：

#code(```typ
1#sub[2]
#import "packages/m1.typ": sub as subtract
#repr(subtract(10, 1))#sub[3]
```)

== 「include」语法与「import」语法的关系

在Typst内部，当解析完一个文件时，文件将被分为顶层作用域中的「内容」和「变量声明」，共同组成一个文件模块。`include`取其「内容」，`import`则取其「变量声明」。

仍然以前文中的`packages/m1.typ`为例：

其「内容」是除了「变量声明」以外的文件内容，连接起来为：

```typ
XXX
// #let add(x, y) = x + y
YYY
// #let sub = ..
```

其导出所有在文件顶层作用域中的「变量声明」：

```typ
// XXX
#let add(x, y) = x + y
// YYY
#let sub(x, y) = x - y
```

因此`include`和`import`分别得到以下结果。

使用`include`得到：

#code(```typ
#repr(include "packages/m1.typ")
```)

使用`import`得到：

#code(```typ
#import "packages/m1.typ"
#repr(m1.add), #repr(m1.sub)
```)

你可以同时使用`include`和`import`获得同一个文件的内容和变量声明。

== 控制变量导出的三种方式

有的时候你不希望将一些变量暴露出去，这个时候你可以让这些变量的名称以「下划线」（`_`）开头：

```typ
#let _factor = 1;
#let add2(x, y) = _factor * (x + y)
```

这样`import`的时候就不会轻易访问到这些变量。

还有一种方法是在非顶层作用域中构造闭包，这样`import`中就不会包含`factor`，因为`factor`不在顶层：

```typ
#let add2 = {
  let factor = 1;
  (x, y) => factor * (x + y)
}
```

值得注意的是，`import`进来的变量也可以被重新导出，只要他们也在顶层作用域。这允许你以更优雅的第三种方式为使用者屏蔽内部变量，例如你可以在子文件夹中完成实现并重新导出：

```typ
// 仅从packages/m1/add.typ文件中重新导出`add`函数。
#import "m1/add.typ": add
// 重新导出packages/m1/sub.typ文件中所有的函数
#import "m1/sub.typ": *
```

== 使用外部库


除此之外，可以从特殊的路径从网络导入外部「模块」，即外部「库」（packages）。Typst的外部库机制可能不是世界上最精简的，但是我所见过当中最精简的。它可能更稍显简陋，但已经有上百个外部库通过官方渠道发布，并足以满足我们日常生活的使用。

你只需要`import`特定的路径就能访问其内部的变量声明。例如，导入一个用于绘画自动机的外部库：

#code(```typ
#import "@preview/fletcher:0.5.7" as fletcher: node, edge

#align(center, fletcher.diagram(
  node((0, 0), $S_1$),
  node((1, 0), $S_2$),

  edge((1, 0), (0, 0), $g$, "..}>", bend: 25deg),
  edge((0, 0), (1, 0), $f$, "..}>", bend: 25deg),
))
```)

其中，以下一行代码完成了导入外部库的所有工作。我们注意到其完全为`import`语法，唯一陌生的是其中的路径格式：

```typ
#import "@preview/fletcher:0.5.7" as fletcher: node, edge
```

解读路径#text(red, `@preview`)`/`#text(eastern, `fletcher`)`:`#text(orange, `0.5.7`)的格式，它由三部分组成。

=== 「命名空间」，#text(red, `@preview`)

以`@`字符开头。目前仅允许使用两个命名空间：
- #text(red, `@preview`)：Typst仅开放`beta`版本的包管理机制。所有`beta`版本的都在`preview`命名空间下。
- #text(red, `@local`)：Typst建议的本地库命名空间。

=== 「库名」，#text(eastern, `fletcher`)

必须符合变量命名规范：
+ 以ASCII英文字符（`a-z`或`A-Z`）开头；
+ 跟随任意多个ASCII英文或数字字符（`a-z`或`A-Z`或`0-9`）或下划线（`_`）或中划线（`-`）。

例如`OvO`、`O_O`、`O-O`都是合法的库名。但是`0v0`不是合法库名，因为其以数字零开头。

=== 「版本号」，#text(orange, `0.5.7`)

必须符合#link("https://semver.org/")[SemVer]规范。

如果你不能很好地阅读和理解#link("https://semver.org/")[SemVer]规范，仅记住合法的版本号由三个递增的数字组成，并用「点号」（`.`）分隔；版本号之间可以相互比较，且比较版本时按顺序比较数字。例如`0.0.0`、`0.10.0`、`1.5.11`、`1.24.1`是合法且递增的版本号。
+ #text(red, `1`)`.0.11`比#text(red, `0`)`.10.0`大，因为#text(red, `1`)大于#text(red, `0`)；
+ `1.`#text(red, `24`)`.1`比`1.`#text(red, `5`)`.11`大，因为#text(red, `24`)大于#text(red, `5`)；
+ `1.24.0`与`1.24.0`相等。

== 下载外部库

一般来说，使用外部库与导入本地模块一样简单。当你尝试导入一个外部库时，Typst会立即启动下载线程为你从网络下载外部库代码：

```typ
#import "@preview/fletcher:0.5.7" as fletcher: node, edge
```

一般情况下，从网络下载外部库的时间不会超过十秒钟，并且不需要任何额外配置。但由于不可描述的原因，你有可能需要为下载线程配置代理。当你希望通过网络代理下载外部库时，请检查全局环境变量`HTTP_PROXY`和`HTTPS_PROXY`是否成功设置。
+ 如果你的网络代理软件包含环境变量设置，请*优先*在你的网络代理环境中配置。
+ 否则如果你是Linux用户，请检查启动`typst-cli`或`vscode`的shell中，使用`echo $HTTP_PROXY`检查是否包含该环境变量。
+ 否则如果你是Windows用户，请使用`Win + R`快捷键呼出运行窗口，执行`system`#sym.zws`properties`#sym.zws`advanced`，调出「环境变量」窗口，并检查是否包含该环境变量。
  #figure(align(center, image("./systempropertiesadvanced.png", width: 50%)))

== 库文件夹

上一小节中的「命名空间」对应本地的一个或多个文件夹。

首先，Typst会感知你系统上的“数据文件夹”和“缓存文件夹”并在其中存储库代码。

Typst将会检查`{data-dir}/`#text(green, `typst/packages`)中是否包含相应的库，*随后*会在`{cache-dir}/`#text(green, `typst/packages`)中检查和缓存从网络下载的库代码。其中数据文件夹（`{data-dir}`）和缓存文件夹（`{cache-dir}`）在不同的操作系统上：

#{
  set align(center)
  table(
    columns: 3,
    [操作系统], [数据文件夹], [缓存文件夹],
    [Linux], [`$XDG_DATA_HOME`或`~/.local/share`], [`$XDG_CACHE_HOME`或`~/.cache`],
    [macOS], [`~/Library/Application Support`], [`~/Library/Caches`],
    [Windows], [`%APPDATA%`], [`%LOCALAPPDATA%`],
  )
}


#let breakable-path(..contents) = contents.pos().join([#sym.zws`/`#sym.zws])

例如，当引入外部库#breakable-path(
  text(red, `@preview`),
  [#text(eastern, `fletcher`)`:`#text(orange, `0.5.7`)],
)时，Typst会严格*按顺序*检查并解析路径：数据文件夹中的#breakable-path(
  `{data-dir}`,
  text(green, `typst/packages`),
  text(red, `preview`),
  text(eastern, `fletcher`),
  text(orange, `0.5.7`),
)和缓存文件夹中的#breakable-path(
  `{cache-dir}`,
  text(green, `typst/packages`),
  text(red, `preview`),
  text(eastern, `fletcher`),
  text(orange, `0.5.7`),
)。Typst会将库路径映射到你数据文件夹或缓存文件夹，优先按顺序使用已经存在的库代码，并按需从网络下载外部库。

这意味着你可以拥有以下几条特性。

- 若你已经下载了网络库到本地，再次访问将不会再产生网络请求和检查远程库代码的状态。
- 你可以将本地库存储到数据文件夹。特别地，你可以在数据文件夹中的`preview`文件夹中存储库，以*覆盖*缓存文件夹中已经下载的库。这有利于你调试或临时使用即将发布的外部库。
- 你可以在本地随意创建新的命名空间，对于#breakable-path(
    text(red, `@my-namespace`),
    [#text(eastern, `my-package`)`:`#text(orange, `version`)],
  )，Typst将检查并使用你位于#breakable-path(
    `{data-dir}`,
    text(green, `typst/packages`),
    text(red, `my-namespace`),
    text(eastern, `my-package`),
    text(orange, `version`),
  )的库代码。尽管Typst对命名空间没有限制，但建议你使用 #text(red, `@local`)作为所有本地库的命名空间。

== 构建和注册本地库

本小节教你如何构建和注册本地库。

=== 元数据文件

在库的*根目录*下必须有一个名称为`typst.toml`的元数据文件，这是对代码库的描述。内容示例如下：

```toml
[package]
name = "example"
version = "0.1.0"
entrypoint = "lib.typ"
```

最低限度你仅需要填入以上三个字段，分别对应其名字、版本号和入口文件的路径。

=== 入口文件

一般来说，该文件对应为库的根目录下的`lib.typ`文件。你可以使用本节提及的《变量导出的三种方式》编写该文件。当导入该库时，其中的「变量声明」将提供给文档使用。

=== 示例库的文件组织

假设你希望构建一个`@local/example:0.1.0`的外部库供本地使用。你应该将`example`库的文件夹*拷贝或链接*到#breakable-path(
  `{data-dir}`,
  text(green, `typst/packages`),
  text(red, `local`),
  text(eastern, `example`),
  text(orange, `0.1.0`),
)路径。

创建#breakable-path(
  `{data-dir}`,
  text(green, `typst/packages`),
  text(red, `local`),
  text(eastern, `example`),
  text(orange, `0.1.0`),
  `typst.toml`,
)文件，并包含前文所述内容。

创建#breakable-path(
  `{data-dir}`,
  text(green, `typst/packages`),
  text(red, `local`),
  text(eastern, `example`),
  text(orange, `0.1.0`),
  `lib.typ`,
)文件，并包含以下内容：

```typ
#import "add.typ": add
#import "sub.typ": sub
```

这样你就可以在本地的任意文档中使用库中的`add`或`sub`函数了：

```typ
#import "@local/example:0.1.0" as example: add
```

== 发布库到官方源

略

== 再谈「根目录」

出于安全考虑，每个库都*默认*只能访问其专属的「根目录」，即`typst.toml`文件所在的目录。这意味着，库中的绝对路径或相对路径依其专属的「根目录」解析。请回忆《绝对路径与相对路径》小节内容。例如在文件夹`@local/example:0.1.0`的内部，设使内部文件#breakable-path(
  `{data-dir}`,
  text(eastern, `{example-lib}`),
  `src/add-simd.typ`,
)中包含这样的代码。

```typ
#read("/typst.toml")
#read("../typst.toml")
```

则「根目录」被解析为#breakable-path(
  `{data-dir}`,
  text(eastern, `{example-lib}`),
)，绝对路径`/typst.toml`被解析为#breakable-path(
  `{data-dir}`,
  text(eastern, `{example-lib}`),
  `typst.toml`,
)，相对路径`../typst.toml`被解析为#breakable-path(
  `{data-dir}`,
  text(eastern, `{example-lib}`),
  `src`,
  `..`,
  `typst.toml`,
)

== 函数与闭包中的路径解析

这里有一个微妙的问题。在函数或闭包中请求解析一个绝对路径或相对路径，Typst会如何做？答案是，任何路径解析都依附于路径解析代码所在文件。这句话有些晦涩，但例子却容易懂。这里举两个例子。

假设函数在文档相对于根目录的#breakable-path(text(eastern, `{example-lib}`), `src`, `m1.typ`)中有这样一个函数：

```typ
#let parse-code(path) = parse-text(read(path))
```

那么无论我们在哪个文件引入了`parse-code`函数，其`read(path)`的路径解析都是固定的，其绝对路径相对于文档根目录，其相对路径相对于#breakable-path(
  text(eastern, `{example-lib}`),
  `src`,
  `m1.typ`,
)所在目录。例如调用`parse-code("../def.typ")`时，其始终读取#breakable-path(
  text(eastern, `{example-lib}`),
  `src/../def.typ`,
)文件。

我们上一小节说过，每个库都*默认*只能访问其专属的「根目录」。这种行为在有的时候不是你期望的，但你可以同样通过传递一个来自文档的闭包绕过该限制。例如，`parse-code`改写为：

```typ
#let parse-code(path, read-file: read) = parse-text(read-file(path))
```

并且在调用时传入一个读取文件的「回调函数」

```typ
#parse-code("../def.typ", read-file: (p) => read(p))
```

== 多文件文档


尽管本书提倡你尽可能将所有文档内容放在单个文件中，本书给出构建一个多文件文档的合理方案。
- 工作区中包含多个主文件
- 每个主文件可以`include`多个子文件

```
typ/packages
└── util.typ
typ/templates
└── book-template.typ
documents/
└── my-book/
    ├── main.typ
    ├── mod.typ
    ├── part1/
    │   ├── mod.typ
    │   └── chap1.typ
    └── part2/
        ├── mod.typ
        └── chapN.typ
```

=== 工作区内的模板与库

使用绝对路径方便引入工作区内的模板与库：

```typ
#import "/typ/templates/ebook.typ": project as ebook
```

=== 主文件和主库文件

`main.typ`文件中仅仅包含模板配置与`include`多个子文件。

```typ
// 在mod.typ文件中：
// #import "/typ/templates/ebook.typ": project as ebook
#import "mod.typ": *

#show: ebook.with(title: "My Book")

#include "part1/chap1.typ"
#include "part2/chap2.typ"
#include "part2/chap3.typ"
```

对于每个子文件，你可以都`import`一个主库文件`mod.typ`，以减少冗余。例如在`documents/my-book/part1/chap1.typ`中：

```typ
#import "mod.typ": *
```

=== 重导出文件

示例文件结构中的`mod.typ`与编写库时的`lib.typ`很类似，都重新导出了大量函数。例如当你希望同时在`chap2.typ`和`chap3.typ`中使用相似的函数时，你可以在`mod.typ`中原地实现该函数或者从外部库中重导出对应函数：

```typ
#import "@preview/example:0.1.0": add
// 或者原地实现`add`
#let add(x, y) = x + y
```

这时你可以同时在`chap2.typ`和`chap3.typ`中直接使用该`add`函数。

=== 依赖管理

你可以不在`main.typ`或者`chap{N}.typ`文件中直接引入外部库，而在`my-book/mod.typ`中引入外部库。由于级联的`mod.typ`，相关函数会传递给每个`main.typ`或者`chap{N}.typ`使用。


================================================
FILE: src/tutorial/doc-stateful.typ
================================================
#import "mod.typ": *

#import "/typ/embedded-typst/lib.typ": default-cjk-fonts, default-fonts, svg-doc

#show: book.page.with(title: [状态化])

#todo-box[本节处于校对阶段，所以可能存在不完整或错误。]

在上一节中我们理解了作用域，也知道如何简单把「`show`」规则应用于文档中的部分内容。

它看起来似乎已经足够强大。但还有一种可能，Typst可以给你更强大的原语。

我是说有一种可能，Typst对文档内容的理解至少是二维的。这二维，有一维可以比作空间，另一维可以比作时间。你可以从文档的任意位置，
+ 空间维度（From Space to Space）：查询文档任意部分的状态（这里的内容和那里的内容）。
+ 时间维度（From TimeLoc to TimeLoc）：查询脚本执行到文档任意位置的状态（过去的状态和未来的状态）。

这里有一个示意图，红色线段表示Typst脚本的执行方向。最后我们形成了一个由S1到S4的“时间线”。

你可以选择文档中的任意位置，例如你可以在文档的某个位置（蓝色弧线的起始位置），从该处开始查询文档过去某处或未来某处（蓝色弧线的终止位置）。

// I mean, Typst maintains states with at least two dimensions. The one resembles a space dimension, and the other one resembles a time dimension. You can create a state that spans:

// 1. From space to space: You can locate content at here and there by selectors.
// 2. From time to time: You can query a state in past or future by locations.

// The following figure shows how a state is arranged. First, Typst executes the document with scripting from S1 to S4, as #text(fill: red, "red lines") shown. Then, you can locate some content in the document (at the _start position_ of #text(fill: blue, "blue arcs")) and query the past state or future state (at the _end position_ of #text(fill: blue, "blue arcs")).

#import "../tutorial/figure-time-travel.typ": figure-time-travel
#align(center + horizon, figure-time-travel())

「状态」基本上是教程中最难的部分。它涉及教程之前所有的知识。具体而言，我们需要理解透排版Ⅱ中的「编译流程」。整个「编译流程」中，排版引擎会储存一个「上下文」（context）状态。首先，「解析器」（Parser）将源代码字符串解析为待求值的「抽象语法树」（AST），接着「表达式求值」（Evaluation）阶段将「抽象语法树」转换为「内容」,然后「排版」（typeset）阶段将「内容」转换为布局好的结果。

== 「`typeset`」阶段的迭代收敛

一个容易值得思考的问题是，如果我在文档的开始位置调用了#typst-func("state.final")方法，那么Typst要如何做才能把文档的最终状态返回给我呢？

容易推测出，原来Typst并不会只对内容执行一遍「`typeset`」。仅考虑我们使用#typst-func("state.final")方法的情况。初始情况下#typst-func("state.final")方法会返回状态默认值，并完成一次布局。接下来的迭代，#typst-func("state.final")方法会返回上一次迭代布局完成时的。直到布局的内容不再发生变化。#typst-func("state.at")会导致相似的布局迭代，只不过情况更为复杂，这里便不再展开细节。

所有对文档的查询都会导致布局的迭代：`query`函数可能会导致布局的迭代；`state.at`函数可能会导致布局的迭代；`state.final`函数一定会导致布局的迭代。

// 延迟执行

// This section mainly talks about `selector` and `state` step by step, to teach how to locate content, create and manipulate states.

// 本节教你使用选择器（selector）定位到文档的任意部分；也教你创建与查询二维文档状态（state）。

== 时间维度 -- 控制流

== 空间维度 -- 文档（内容）树

// == 回顾其一

// 针对特定的`feat`和`refactor`文本，我们使用`emph`修饰：

// #frames-cjk(
//   read("./stateful/s2.typ"),
//   code-as: ```typ
//   #show regex("feat|refactor"): emph
//   ```,
// )

// 对于三级标题，我们将中文文本用下划线标记，同时将特定文本替换成emoji：

// #frames-cjk(
//   read("./stateful/s3.typ"),
//   code-as: ```typ
//   #let set-heading(content) = {
//     show heading.where(level: 3): it => {
//       show regex("[\p{hani}\s]+"): underline
//       it
//     }
//     show heading: it => {
//       show regex("KiraKira"): box("★", baseline: -20%)
//       show regex("FuwaFuwa"): box(text("🪄", size: 0.5em), baseline: -50%)
//       it
//     }

//     content
//   }
//   #show: set-heading
//   ```,
// )

== 任务描述

为举例说明，本节讲解的程序是如何在Typst中设置标题样式。我们的目标是设置标题为内容的页眉：
+ 如果当前页眉有二级标题，则是当前页面的第一个二级标题。
+ 否则是之前所有页面的最后一个二级标题。

效果如下：

#frames-cjk(
  read("./stateful/s1.typ"),
  code-as: ```typ
  #show: set-heading

  == 雨滴书v0.1.2
  === KiraKira 样式改进
  feat: 改进了样式。
  === FuwaFuwa 脚本改进
  feat: 改进了脚本。

  == 雨滴书v0.1.1
  refactor: 移除了LaTeX。

  feat: 删除了一个多余的文件夹。

  == 雨滴书v0.1.0
  feat: 新建了两个文件夹。
  ```,
)

// == 制作页眉标题的两种方法

// 制作页眉标题至少有两种方法。一是直接查询文档内容；二是创建状态，利用布局迭代收敛的特性获得每个页面的首标题。

// 在接下来的两节中我们将分别介绍这两种方法。

// 本节我们讲解制作页眉标题的第一种方法，即通过查询文档状态直接估计当前页眉应当填入的内容。

// #locate(loc => query(heading, loc))
// #locate(loc => query(heading.where(level: 2), loc))

== 「here」<grammar-here>

#todo-box[
  修改以适配全面 context 化的 0.12+ 语法
]

有的时候我们会需要获取当前位置的「位置」信息。

在Typst中，获取当前「位置」的唯一方法是使用「#typst-func("here")」函数。

我们来`repr`一下试试看：

#code(```typ
当前位置的相关信息：#context repr(here())
```)

由于「位置」太过复杂了，`repr`放弃了思考并在这里为我们放了两个点。

我们来简单学习一下Typst为我们提供了哪些位置信息：

#code(```typ
当前位置的坐标：#context here().position()

当前位置的页码：#context here().page()
```)

一个常见的问题是：为什么Typst提供给我的页码信息是「内容」，我无法在内容上做条件判断和计算！<grammar-here-calc>

// #code(```typ
// #repr(context here().page()) \
// #type(context here().page())
// ```)

// 上面输出的内容告诉我们#typst-func("here")不仅是一个函数，而且更是一个元素的构造函数。#typst-func("here")构造出一个`locate`内容。

这其中的关系比较复杂。一个比较好理解的原因是：Typst会调用你的函数多次，因此你理应将所有使用「位置」信息的脚本放在一个上下文块中，这样Typst才能更好地合成内容。

#code(```typ
#context [ 当前位置的页码是偶数：#calc.even(here().page()) ]
//  根据位置信息  计算得到  我们想要的内容
```)

// #pro-tip[
//   这与Typst的缓存原理相关。由于#typst-func("locate")函数接收的闭包```typc loc => ..```是一个函数，且在Typst中它被认定为*纯函数*，Typst只会针对特定的参数执行一次函数。为了强制让用户书写的函数保持纯性，Typst规定用户必须在函数内部使用「位置」信息。

//   因此，例如我们希望在偶数页下让内容为“甲”，否则让内容为“乙”，应当这样书写：

//   #code(```typ
//   #context if calc.even(here().page()) [“甲”] else [“乙”]
//   ```)
// ]

== 「query」<grammar-query>

使用「#typst-func("query")」函数你可以获得当前文档状态。

#code(
  ```typ
  #context query(heading)
  ```,
  res: raw(
    ```typc
    (
      heading(body: [雨滴书 v0.1.2], level: 2, ..),
      ..,
    )
    ```.text,
    lang: "typc",
    block: false,
  ),
)

「#typst-func("query")」函数的唯一参数是「选择器」，很好理解。它接受一个选择器，并返回被选中的所有元素的列表。

#code(
  ```typ
  #context query(heading)
  ```,
  res: raw(
    ```typc
    (
      heading(body: [雨滴书 v0.1.2], level: 2, ..),
      heading(body: [KiraKira 样式改进], level: 3, ..),
      heading(body: [FuwaFuwa 脚本改进], level: 3, ..),
      heading(body: [雨滴书 v0.1.1], level: 2, ..),
      heading(body: [雨滴书 v0.1.0], level: 2, ..),
    )
    ```.text,
    lang: "typc",
    block: false,
  ),
)

我们记得，选择器允许继续指定`where`条件过滤内容：

#code(
  ```typ
  #context query(heading.where(level: 2))
  ```,
  res: raw(
    ```typc
    (
      heading(body: [雨滴书 v0.1.2], level: 2, ..),
      heading(body: [雨滴书 v0.1.1], level: 2, ..),
      heading(body: [雨滴书 v0.1.0], level: 2, ..),
    )
    ```.text,
    lang: "typc",
    block: false,
  ),
)

// 第二个参数是「位置」，就比较难以理解了。首先说明，`loc`并没有任何作用，即它是一个「哑参数」（Dummy Parameter）。

// 如果你学过C++，以下两个方法分别匹配到前缀自增操作函数和后缀自增操作函数。

// ```cpp
// class Integer {
//   Integer& operator++();   // 前缀自增操作函数
//   Integer operator++(int); // 后缀自增操作函数
// };
// ```

// ```cpp class Integer```类中的`int`就是一个所谓的哑参数。

// 「哑参数」在实际函数执行中并未被使用，而仅仅作为标记以区分函数调用。我们知道以下两点：其一，只有#typst-func("locate")函数会返回「位置」信息；其二，#typst-func("query")函数需要我们传入「位置」信息。

// 有了：那么Typst就是在告诉我们，#typst-func("query")函数只能在#typst-func("locate")函数内部调用。正如示例中的那样：

// ```typ
// #locate(loc => query(heading.where(level: 2), loc))
// ```

// 这个规则有些隐晦，并且Typst的设计者也已经注意到了这一点，所以他们正在计划改进这一点。当然在这之前，你只需要记住：#typst-func("query")函数的第二个「位置」参数用于限制该函数仅在#typst-func("locate")函数内部使用。

// #pro-tip[
//   这与Typst的缓存原理相关。为了加速#typst-func("query")函数，Typst需要对其缓存。Typst合理做出以下假设：在文档每处的查询（`loc`），都单独缓存对应选择器的查询结果。

//   更细致地描述如下：将```typc query(selector, loc)```的参数为「键」，执行结果为「值」构造一个哈希映射表。若使用`(selector, loc)`作为「键」，查询该表：
//   + 未对应结果，则执行查询，缓存并返回结果。
//   + 已经存在对应结果，则不会重新执行查询，而是使用表中的值作为结果。
// ]

== 通过查询内置状态制作页眉

页眉的设置方法是创建一条```typc set page(header)```规则：

#frames-cjk(
  read("./stateful/q0.typ"),
  code-as: ```typ
  #set page(header: [这是页眉])
  ```,
)

既然如此，只需要将`[这是页眉]`替换成一个`context`表达式，就能通过#typst-func("query")函数完成与「位置」相关的页眉设定：

```typ
#set page(header: context emph(get-heading-at-page()))
```

现在让我们来编写`get-heading-at-page`函数。

首先，通过`query`函数查询得到整个文档的*所有二级标题*：

```typc
let headings = query(heading).
  filter(it => it.level == 2)
```

如果你熟记`where`方法，你可以更高效地做到这件事。以下函数调用也可以得到整个文档的*所有二级标题*：

```typc
let headings = query(heading.where(level: 2))
```

很好，Typst文档可以很高效，但有些人写出的Typst代码天生更高效，而我们正在向他们靠近。

接着，考虑构建这样一个`fold-headings`函数，它返回一个数组，数组的内容是每个页面页眉应当显示的内容，即每页的第一个标题。

```typ
#let fold-headings(headings) = {
  ..
}
```

我们可以对其直接调用以测试：

#code(```typ
#let fold-headings(headings) = {
  (none, none)
}
#fold-headings((
  (body:"v2",page:1),(body:"v1",page:1),(body:"v0",page: 2),
))
```)

很好，这样我们就可以很方便地进行测试了。

该函数首先创建一个数组，数组的长度为页面的数量。

#code(```typ
#let fold-headings(headings) = {
  let max-page-num = calc.max(..headings.map(it => it.page))
  (none, ) * max-page-num
}
#fold-headings((
  (body:"v2",page:1),(body:"v1",page:1),(body:"v0",page: 2),
))
```)

这里，```typc headings.map(it => it.page)```意即对每个标题获取对应位置的页码；```typc calc.max(..numbers)```意即取页码的最大值。

由于示例中页码的最大值为`2`，`fold-headings`针对示例会返回一个长度为2的数组，数组的每一项都是`none`。

接着，该函数遍历给定的`headings`，对每个页码，都首先获取第一个标题元素：

#code(
  ```typc
  for h in headings {
    if first-headings.at(h.page - 1) == none {
      first-headings.at(h.page - 1) = h
    }
  }
  ```,
  res: eval(
    ```typ
    #let fold-headings(headings) = {
      let max-page-num = calc.max(..headings.map(it => it.page))
      let first-headings = (none, ) * max-page-num

      for h in headings {
        if first-headings.at(h.page - 1) == none {
          first-headings.at(h.page - 1) = h
        }
      }

      first-headings
    }
    #fold-headings((
      (body:"v2",page:1),(body:"v1",page:1),(body:"v0",page: 2),
    ))
    ```.text,
    mode: "markup",
  ),
)

这里，```typc first-headings.at(h.page - 1)```意即获取当前页码对应在数组中的元素；`if`语句，如果对应页码对应的元素仍是```typc none```，那么就将当前的标题元素填入对应的位置中。

同理，可以获得`last-headings`，存储每页的最后一个标题：

#code(
  ```typc
  let last-headings = (none, ) * max-page-num
  for h in headings {
    last-headings.at(h.page - 1) = h
  }
  ```,
  res: eval(
    ```typ
    #let fold-headings(headings) = {
      let max-page-num = calc.max(..headings.map(it => it.page))
      let last-headings = (none, ) * max-page-num

      for h in headings {
        last-headings.at(h.page - 1) = h
      }

      last-headings
    }
    #fold-headings((
      (body:"v2",page:1),(body:"v1",page:1),(body:"v0",page: 2),
    ))
    ```.text,
    mode: "markup",
  ),
)

这里`for`语句意即：无论如何，都将当前的标题元素存入数组中。那么每页的最后一个标题总是能被存入到数组中。

但是我们还没有考虑相邻情况。如果我们希望如果当前页面没有标题元素，则显示之前的标题。接下来我们来根据这个思路，组装正确的结果：

#code(
  ```typc
  let res-headings = (none, ) * max-page-num
  for i in range(res-headings.len()) {
    res-headings.at(i) = if first-headings.at(i) != none {
      first-headings.at(i)
    } else {
      last-headings.at(i) = last-headings.at(
        calc.max(0, i - 1), default: none)
      last-headings.at(i)
    }
  }
  ```,
  res: eval(
    ```typ
    #let fold-headings(headings) = {
      let max-page-num = calc.max(..headings.map(it => it.page))
      let first-headings = (none, ) * max-page-num
      let last-headings = (none, ) * max-page-num

      for h in headings {
        if first-headings.at(h.page - 1) == none {
          first-headings.at(h.page - 1) = h
        }
        last-headings.at(h.page - 1) = h
      }

      let res-headings = (none, ) * max-page-num
      for i in range(res-headings.len()) {
        res-headings.at(i) = if first-headings.at(i) != none {
          first-headings.at(i)
        } else {
          last-headings.at(i) = last-headings.at(
            calc.max(0, i - 1), default: none)
          last-headings.at(i)
        }
      }

      res-headings
    }
    #fold-headings((
      (body:"v2",page:1),(body:"v1",page:1),(body:"v0",page: 2),
    ))
    ```.text,
    mode: "markup",
  ),
)

`res-headings`就是我们想要得到的结果。

#let fold-headings(headings) = {
  let max-page-num = calc.max(..headings.map(it => it.page))
  let first-headings = (none,) * max-page-num
  let last-headings = (none,) * max-page-num

  for h in headings {
    if first-headings.at(h.page - 1) == none {
      first-headings.at(h.page - 1) = h
    }
    last-headings.at(h.page - 1) = h
  }

  let res-headings = (none,) * max-page-num
  for i in range(res-headings.len()) {
    res-headings.at(i) = if first-headings.at(i) != none {
      first-headings.at(i)
    } else {
      last-headings.at(i) = last-headings.at(
        calc.max(0, i - 1),
        default: none,
      )
      last-headings.at(i)
    }
  }

  res-headings
}

由于`res-headings`的计算比较复杂，我们先来一些测试用例来理解：

情形一：假设文档的前段没有标题，该函数会将对应下标的结果置空：

#code(
  ```typ
  情形一：#fold-headings((
    (body:"v2",page:3),(body:"v1",page:3),(body:"v0",page: 3),
  ))
  ```,
  scope: (fold-headings: fold-headings),
)

情形二：假设一页有多个标题，那么，对应下表的结果为该页面的首个标题：

#code(
  ```typ
  情形二：#fold-headings((
    (body:"v2",page:2),(body:"v1",page:2),(body:"v0",page: 3),
  ))
  ```,
  scope: (fold-headings: fold-headings),
)

情形三：假设中间有页空缺，则对应下表的结果为前页的最后一个标题。

#code(
  ```typ
  情形三：#fold-headings((
    (body:"v2",page:1),(body:"v1",page:1),(body:"v0",page: 3),
  ))
  ```,
  scope: (fold-headings: fold-headings),
)

其中，情形一其实是情形三的特例：假设某一页没有标题，则对应下表的结果为前页的最后一个标题。如果不存在前页包含标题，则对应下表的结果为```typc none```。

于是我们可以给代码加上注释：

```typc
let res-headings = (none, ) * max-page-num
// 对于每一页，我们迭代下标
for i in range(res-headings.len()) {
  // 让对应下标的结果等于：
  res-headings.at(i) = {
    // 如果该页包含标题，则其等于该页的第一个标题
    if first-headings.at(i) != none {
      first-headings.at(i)
    } else {
      // 否则，我们积累`last-headings`的结果
      last-headings.at(i) = last-headings.at(
        // 始终至少等于前一页的结果
        calc.max(0, i - 1),
        // 默认没有结果
        default: none)
      // 其等于前页的最后一个标题
      last-headings.at(i)
    }
  }
}
```

最后，我们将`query`与`fold-headings`结合起来，便得到了目标函数：

```typ
#let get-heading-at-page() = {
  let headings = fold-headings(query(
    heading.where(level: 2)))
  headings.at(here().page() - 1)
}
```

这里有一个问题，那便是`fold-headings`没有考虑标题的最后一页仍然存在内容的情况。例如第二页有最后一个标题，但是我们文档一共有三页。

重新改造一下：

#let calc-headings(headings) = {
  let max-page-num = calc.max(..headings.map(it => it.page))
  let first-headings = (none,) * max-page-num
  let last-headings = (none,) * max-page-num

  for h in headings {
    if first-headings.at(h.page - 1) == none {
      first-headings.at(h.page - 1) = h
    }
    last-headings.at(h.page - 1) = h
  }

  let res-headings = (none,) * max-page-num
  for i in range(res-headings.len()) {
    res-headings.at(i) = if first-headings.at(i) != none {
      first-headings.at(i)
    } else {
      last-headings.at(i) = last-headings.at(
        calc.max(0, i - 1),
        default: none,
      )
      last-headings.at(i)
    }
  }

  (
    res-headings,
    if max-page-num > 0 {
      last-headings.at(-1)
    },
  )
}

```typ
#let calc-headings(headings) = {
  // 计算res-headings和last-headings
  ..

  // 同时返回最后一个标题
  (res-headings, if max-page-num > 0 {
    last-headings.at(-1)
  })
}
```

我们来简单测试一下：

#code(
  ```typ
  情形一：#calc-headings((
    (body:"v2",page:3),(body:"v1",page:3),(body:"v0",page: 3),
  )).at(1) \
  情形二：#calc-headings((
    (body:"v2",page:2),(body:"v1",page:2),(body:"v0",page: 3),
  )).at(1) \
  情形三：#calc-headings((
    (body:"v2",page:1),(body:"v1",page:1),(body:"v0",page: 3),
  )).at(1)
  ```,
  scope: (calc-headings: calc-headings),
)

很好，这样，下面的实现就完全正确了：

```typ
#let get-heading-at-page() = {
  let (headings, last-heading) = calc-headings(
    query(heading.where(level: 2)))
  headings.at(here().page() - 1, default: last-heading)
}
```

#pro-tip[
  将`calc-headings`与`get-heading-at-page`分离可以改进脚本性能。这是因为Typst是以函数为粒度缓存你的计算。在最后的实现：

  + ```typc query(heading.where(level: 2))```会被缓存，如果二级标题的结果不变，则#typst-func("query")函数不会重新执行（不会重新查询文档状态）。
  + ```typc calc-headings(..)```会被缓存。如果查询的结果不变。则其不会重新执行。
]

最后，让我们适配`calc-headings`到真实场景，并应用到页眉规则：

#frames-cjk(
  read("./stateful/q1.typ"),
  code-as: ```typ
  // 这里有get-heading-at-page的实现..

  #set page(header: context emph(get-heading-at-page()))
  ```,
)

== 自定义「状态」（state）<grammar-state>

在法一中，我们仅靠「#typst-func("query")」函数就完成制作所要求页眉的功能。

思考下面函数：

```typ
#let get-heading-at-page(loc) = {
  let (headings, last-heading) = calc-headings(
    query(heading.where(level: 2), loc))
  headings.at(loc.page() - 1, default: last-heading)
}
```

对于每个页面，它都运行```typc query(heading.where(level: 2), loc)```。显然每页的「位置」信息，即`loc`对应不相同。因此：
1. 它会*每页*都重新执行一遍`heading.where(level: 2)`查询。
2. 同时，每次`query`都是对*全文档的线性扫描*。

夸张来讲，假设你有一千页文档，文档中包含上千个二级标题；那么他将会使得你的每次标题更新都触发上百万次迭代。虽然Typst很快，但这上百万次迭代将会使得包含这种页眉的文档难以*实时预览*。

那么有没有一种方法避免这种全文档扫描呢？

本节将介绍法二，它基于「#typst-func("state")」函数，持续维护页眉状态。

Typst文档可以很高效，但有些人写出的Typst代码更高效。本节所介绍的法二，让我们变得更接近这种人。

`state`接收一个名称，并创建该名称对应*全局*唯一的状态变量。

#code(```typ
#state("my-state", 1)
```)

你可以使用```typc context state.get()```函数展示其「内容」：

#code(```typ
#let s1 = state("my-state", 1)
s1: #context s1.get()
```)

你可以使用```typc state.update()```方法更新其状态。`update`函数接收一个「回调函数」，该回调函数接收`state`在某时刻的状态，并返回对应下一时刻的状态：

#let s = state("my-state", 1)

#code(```typ
#let s1 = state("my-state", 1)
s1: #context s1.get() \
#s1.update(it => it + 1)
s1: #context s1.get()
```)

#s.update(it => 1)

所有的相同名称的内容将会共享更新：

#code(```typ
#let s1 = state("my-state", 1)
s1: #context s1.get() \
#let s2 = state("my-state", 1)
s1: #context s1.get(), s2: #context s2.get() \
#s2.update(it => it + 1)
s1: #context s1.get(), s2: #context s2.get()
```)

同时，请注意状态的*全局*特性，即便处于不同文件、不同库的状态，只要字符串对应相同，那么其都会共享更新。

这提示我们需要在不同的文件之间维护全局状态的名称唯一性。

另一个需要注意的是，`state`允许指定一个默认值，但是一个良好的状态设置必须保持不同文件之间的默认值相同。如下所示：

#s.update(it => 1)

#code(```typ
#let s1 = state("my-state", 1)
s1: #context s1.get() \
#let s2 = state("my-state", 2)
s1: #context s1.get(), s2: #context s2.get() \
#s2.update(it => it + 1)
s1: #context s1.get(), s2: #context s2.get()
```)

尽管`s2`指定了状态的默认值为`2`，因为之前已经在文档中创建了该状态，默认值并不会应用。请注意：你不应该利用这个特性，该特性是Typst中的「未定义行为」。

== 「state.update」也是「内容」

#todo-box[
  不再有 `locate` 了, 此处需要修正
]
一个值得注意的地方是，似乎与#typst-func("locate")函数相似，#typst-func("state.update")也接收一个闭包。

事实上，与#typst-func("locate")函数相同，#typst-func("state.update")也具备延迟执行的特性。

让我们检查下列脚本的输出结果：

#s.update(it => 1)

#code(```typ
#let s1 = state("my-state", 1)
#((s1.update(it => it + 1), ) * 3).join()
s1: #context s1.get()
```)

这告诉我们下面一件事情，当`eval`阶段结束时，其对应产生下面的一段内容：

```typc
(
  state("my-state", 1),
  state("my-state").update(it => it + 1),
  state("my-state").update(it => it + 1),
  state("my-state").update(it => it + 1),
)
```

排版引擎会按照*深度优先的顺序*遍历你的内容，从文档的开始位置逐渐*积累*状态。

这将帮助我们在多文件之间协助完成状态的更新与计算。

假设我们有两个文件`s1.typ`和`s2.typ`，文件的内容分别是：
```typ
// s1.typ
#let s1 = state("my-state", (1, ))
#s1.update(it => it + (3, ))
// s2.typ
#let s1 = state("my-state", (2, ))
#s1.update(it => it + (4, ))
#s1.update(it => it + (5, ))
```

并且我们在`main.typ`中引入了上述两个文件：

```typc
#include "s1.typ"
#include "s2.typ"
```

那么根据我们的经验，主文件内容其实对应为：

```typ
// 省略部分内容
#({ state("my-state", (1, )), .. } + { state("my-state", (2, )), .. })
```

我们按照顺序执行状态更新，则状态依次变为：

```typ
#{ (1, ); (1, 3, ); }
#{ (1, 3, ); (1, 3, 4, ); (1, 3, 4, 5, ); }
```

== 查询特定时间点的「状态」


#todo-box[
  `state.final` 不再需要 `loc` 了
]

Typst提供两个方法查询特定时间点的「状态」：

一个方法是```typc state.at(loc)```方法，其接收一个「位置」，返回在该位置对应的状态「值」。

另一个方法是```typc state.final()```方法，返回在文档结束一切排版时对应的状态「值」。

熟悉的剧情再次发生了。让我们回想之前介绍#typst-func("query")时讲述的知识点。


这两个方法都只能在#typst-func("context")内部调用。对于#typst-func("state.at")方法，其「位置」参数是有用的/*；对于#typst-func("state.final")方法，其「位置」参数仅仅作为「哑参数」*/。

我们回想上一小节，由于文档的每个位置「状态」都会存有对应的值，而且当你使用状态的时候至少会指定一个默认值，我们可以知道在我们文档的任意位置使用文档的任意其他位置的状态的内容。

这就是允许我们进行时光回溯的基础。

== 通过自定义状态制作页眉

本节使用递归的方法完成状态的构建，其更为巧妙。

首先，我们声明两个与法一类似的状态，只不过这次我们将状态定义在全局。

```typ
#let first-heading = state("first-heading", ())
#let last-heading = state("last-heading", ())
```

然后，我们在每个二级标题后紧接着触发一个更新：

```typc
show heading.where(level: 2): curr-heading => {
  curr-heading
  context ..
}
```

对于`last-heading`状态，我们可以非常简单地如此更新内容：

```typc
context last-heading.update(headings => {
  headings.insert(str(here().page()), curr-heading.body)
  headings
})
```

每页的最后一个标题总能最后触发状态更新，所以`str(here().page())`总是能对应到每页的最后一个标题的内容。

对于`first-heading`状态，稍微复杂但也好理解：

```typc
context first-heading.update(headings => {
  let k = str(here().page())
  if k not in headings {
    headings.insert(k, curr-heading.body)
  }
  headings
})
```

对于每页靠后的一级标题，都不能使`if`条件成立。所以`str(here().page())`总是能对应到每页的第一个一级标题的内容。

接下来便是简单的查询了，我们回忆之前`get-heading-at-page`的逻辑，它首先判断是否存在本页的第一个标题，否则取前页的最后一个标题。以下函数完成了前半部分：

```typc
let get-heading-at-page() = {
  let page-num = here().page()
  let first-headings = first-heading.final(here())

  first-headings.at(str(page-num))
}
```

我们为`at`函数添加`default`函数，其取前页的最后一个标题。

```typc
let get-heading-at-page() = {
  ..
  let last-headings = last-heading.at(here())

  first-headings.at(str(page-num), default: find-headings(last-headings, page-num))
}
```

我们使用递归的方法实现`find-headings`：

```typc
let find-headings(headings, page-num) = if page-num > 0 {
  headings.at(str(page-num), default: find-headings(headings, page-num - 1))
}
```

递归有两个分支：递归的基是，若一直找到文档最前页都找不到相应的标题，则返回`none`。否则检查`headings`中是否有对应页的标题：若有则直接返回其内容，否则继续往前页迭代。

一个细节值得注意，我们对`first-heading`使用了`final`方法，但对`last-heading`使用了`at`方法。这是因为：
+ `first-heading`需要我们支持后向查找，因此需要直接获取文档最终的状态。
+ `last-heading`仅仅需要前向查找，因此使用`at`方法可以改进迭代效率。

这个递归函数是高性能的，因为Typst会对`find-headings`缓存，并且Typst对于后一页的内容，都总是能命中前一页的缓存。

与之相反，基于#typst-func("query")的实现没有那么好命。它没法很好利用递归完成标题信息的构建。这是因为#typst-func("query")的实现中，`calc-headings`的首次执行就被要求计算文档的所有标题。

最后让我们设置页眉：

#frames-cjk(
  read("./stateful/s1.typ"),
  code-as: ```typ
  // 这里有get-heading-at-page的实现..

  #set page(header: emph(get-heading-at-page()))
  ```,
)


================================================
FILE: src/tutorial/figure-time-travel.typ
================================================
#import "@preview/cetz:0.3.4"
#import "/typ/templates/page.typ": main-color, is-light-theme

#let std-scale = scale

#let figure-time-travel(
  stroke-color: main-color,
  light-theme: is-light-theme,
) = {
  import cetz.draw: *

  let stroke-factor = if light-theme {
    1
  } else {
    0.8
  }

  let line-width = 0.5pt * stroke-factor
  let rect = rect.with(stroke: line-width + stroke-color)
  let circle = circle.with(stroke: line-width + stroke-color)
  let line = line.with(stroke: line-width + stroke-color)
  let light-line = line.with(stroke: (0.3pt * stroke-factor) + stroke-color)
  let exlight-line = line.with(stroke: (0.2pt * stroke-factor) + stroke-color)

  let preview-img-fill = if light-theme {
    green.lighten(80%)
  } else {
    green.darken(20%)
  }

  let preview-img-fill2 = if light-theme {
    green.lighten(80%)
  } else {
    green.darken(20%)
  }

  let state-background-fill = rgb("#2983bb80")
  let preview-background-fill = rgb("#baccd980")

  let preview-content0 = {
    translate((0.05, 1 - 0.2))
    // title
    light-line((0.15, 0), (0.55, 0))
    translate((0, -0.08))
    exlight-line((0.05, 0), (0.7, 0))
    translate((0, -0.03))
    exlight-line((0.00, 0), (0.7, 0))
    translate((0, -0.03))
    exlight-line((0.00, 0), (0.7, 0))
    translate((0, -0.03))
    exlight-line((0.00, 0), (0.4, 0))
  }

  let preview-content1 = {
    translate((0, -0.06))
    rect((0.05, 0), (0.65, -0.24), stroke: 0pt, fill: preview-img-fill, name: "picture")
    content("picture", std-scale(20%)[$lambda x = integral.double x dif x$])
    translate((0, -0.24))
  }
  let doc-state(prev-name, name, checkpoint: 0) = {
    let arrow-line(pos) = {
      line((rel: (-0.01, 0.025), to: pos), pos)
      line((rel: (0.01, 0.025), to: pos), pos)
    }

    rect((0, 0), (0.2, 1), stroke: 0pt, fill: state-background-fill)

    if checkpoint == 0 {
      line(prev-name + "-S2", name + "-S1", stroke: line-width + red)
    }
    if checkpoint == 1 {
      line(prev-name + "-S3", name + "-S2", stroke: line-width + red)
    }
    if checkpoint == 2 {
      line(prev-name + "-S4", name + "-S3", stroke: line-width + red)
    }

    circle(name + "-S1", fill: blue, stroke: 0pt, radius: 0.01)
    content((rel: (-0.04, 0), to: name + "-S1"), std-scale(40%, [S1]))
    if checkpoint <= 0 {
      return
    }
    circle(name + "-S2", fill: blue, stroke: 0pt, radius: 0.01)
    content((rel: (-0.04, -0.03), to: name + "-S2"), std-scale(40%, [S2]))
    line(name + "-S1", name + "-S2")
    arrow-line(name + "-S2")
    if checkpoint <= 1 {
      return
    }
    circle(name + "-S3", fill: blue, stroke: 0pt, radius: 0.01)
    content((rel: (-0.04, -0.02), to: name + "-S3"), std-scale(40%, [S3]))
    line(name + "-S2", name + "-S3")
    arrow-line(name + "-S3")

    if checkpoint == 2 {
      circle(name + "-R1", fill: blue, stroke: 0pt, radius: 0.01)
      arc-through(name + "-R1", (rel: (0.02, -0.03), to: name + "-R1"), name + "-S3", stroke: line-width + blue)
      line((rel: (50deg, 0.02), to: name + "-S3"), name + "-S3", stroke: line-width + blue)
      line((rel: (10deg, 0.02), to: name + "-S3"), name + "-S3", stroke: line-width + blue)
    }

    if checkpoint <= 2 {
      return
    }


    circle(name + "-S4", fill: blue, stroke: 0pt, radius: 0.01)
    content((rel: (-0.04, -0.01), to: name + "-S4"), std-scale(40%, [S4]))
    line(name + "-S3", name + "-S4")
    if checkpoint == 3 {
      circle(name + "-R2", fill: blue, stroke: 0pt, radius: 0.01)
    }
    arrow-line(name + "-S4")


    if checkpoint == 3 {
      arc-through(name + "-R2", (rel: (0.05, 0.33, 0), to: name + "-R2"), name + "-S2", stroke: line-width + blue)
      line((rel: (-110deg, 0.02), to: name + "-S2"), name + "-S2", stroke: line-width + blue)
      line((rel: (-20deg, 0.02), to: name + "-S2"), name + "-S2", stroke: line-width + blue)
    }
  }
  let doc(name, checkpoint: 0) = {
    group(
      name: name,
      {
        // line((0, 0), (0.707, 0))
        // line((0.707, 0), (0.707, 1))
        // line((0.707, 1), (0, 1))
        // line((0, 0), (0, 1))
        rect((0, 0), (0.707, 1), stroke: 0pt, fill: preview-background-fill)

        let margin = 0.05

        translate((margin, 1 - 0.1))
        scale(x: (0.707 - margin * 2))
        let lm = (-margin) / (0.707 - margin * 2)

        anchor("title", (0.5, 0))
        content("title", std-scale(30%)[关于吃睡玩自动机的形式化研究])
        // content("title", std-scale(30%)[#align(center, [A formal study on eat-sleep-\ play automating cats])])

        translate((0, -0.07))
        light-line((0.1, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))

        translate((0, -0.025))
        if checkpoint <= 0 {
          light-line((0.05, 0), (0.45, 0))
          anchor("P", (0.45, 0))
          anchor("Q", (lm, 0))
          return
        }

        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.75, 0))

        translate((0, -0.03))
        anchor("P", (0.59, -0.072))
        anchor("Q", (lm, -0.072))
        rect((0.1, 0), (0.9, -0.10), stroke: 0pt, fill: preview-img-fill, name: "picture")
        content("picture", std-scale(30%)[$lambda x = integral.double x dif x$])
        if checkpoint <= 1 {
          return
        }

        translate((0, -0.03 - 0.10))

        light-line((0.1, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.85, 0))

        translate((0, -0.03))

        light-line((0.1, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        if checkpoint == 2 {
          anchor("R", (0.75, 0))
          anchor("R2", (lm, 0))
        }
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        anchor("P", (0.85, 0))
        anchor("Q", (lm, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.35, 0))

        if checkpoint <= 2 {
          return
        }

        translate((0, -0.03))

        light-line((0.1, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.35, 0))

        translate((0, -0.03))

        light-line((0.1, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        if checkpoint == 3 {
          anchor("R", (0.75, 0))
          anchor("R2", (lm, 0))
        }
        translate((0, -0.025))
        light-line((0.05, 0), (0.95, 0))
        anchor("P", (0.6, 0))
        anchor("Q", (lm, 0))
        translate((0, -0.025))
        light-line((0.05, 0), (0.35, 0))
      },
    )
  }

  cetz.canvas({
    // 导入cetz的draw方言
    import cetz.draw: *
    set-viewport((0, 0, 0), (4, 4, -4), bounds: (1, 1, 1))

    group(
      name: "doc",
      {
        let x = 0.25
        let z = 0.22
        translate((x, 0, -z))
        translate((x, 0, -z))
        translate((x, 0, -z))
        doc("D1", checkpoint: 3)
        circle("D1.P", fill: red, stroke: 0pt, radius: 0.01)
        translate((-x, 0, z))
        doc("D2", checkpoint: 2)
        circle("D2.P", fill: red, stroke: 0pt, radius: 0.01)
        translate((-x, 0, z))
        doc("D3", checkpoint: 1)
        circle("D3.P", fill: red, stroke: 0pt, radius: 0.01)
        translate((-x, 0, z))
        doc("D4", checkpoint: 0)
        circle("D4.P", fill: red, stroke: 0pt, radius: 0.01)

        circle("D2.R", fill: blue, stroke: 0pt, radius: 0.01)
        circle("D1.R", fill: blue, stroke: 0pt, radius: 0.01)

        let blue-light-line = line.with(stroke: (0.3pt * stroke-factor) + blue)
        let red-light-line = line.with(stroke: (0.3pt * stroke-factor) + red)
        red-light-line("D4.P", "D3.P")
        red-light-line("D3.P", "D2.P")
        red-light-line("D2.P", "D1.P")

        blue-light-line("D2.R", "D2.P")
        blue-light-line("D1.R", "D3.P")

        let round-z-axis = ((x, y, z)) => (x, y, calc.round(z, digits: 10))
        anchor("S1", (round-z-axis, (rel: (-x * 0, 0, z * 0), to: "D4.Q")))
        anchor("S2", (round-z-axis, (rel: (-x * 1, 0, z * 1), to: "D3.Q")))
        anchor("S3", (round-z-axis, (rel: (-x * 2, 0, z * 2), to: "D2.Q")))
        anchor("S4", (round-z-axis, (rel: (-x * 3, 0, z * 3), to: "D1.Q")))
        anchor("R1", (round-z-axis, (rel: (-x * 2, 0, z * 2), to: "D2.R2")))
        anchor("R2", (round-z-axis, (rel: (-x * 3, 0, z * 3), to: "D1.R2")))
      },
    )

    let anchor-s(prefix, p) = {
      anchor(prefix + "-S1", (rel: p, to: "doc.S1"))
      anchor(prefix + "-S2", (rel: p, to: "doc.S2"))
      anchor(prefix + "-S3", (rel: p, to: "doc.S3"))
      anchor(prefix + "-S4", (rel: p, to: "doc.S4"))
      anchor(prefix + "-R1", (rel: p, to: "doc.R1"))
      anchor(prefix + "-R2", (rel: p, to: "doc.R2"))
    }

    translate((-1, 0, 0))

    group({
      let x = 0.12
      let z = 0.22
      translate((x, 0, -z))
      translate((x, 0, -z))
      translate((x, 0, -z))
      anchor-s("T1", (-1 + 0.2 / 2 + x * 3, 0, -z * 3))
      doc-state("T0", "T1", checkpoint: 3)
      translate((-x, 0, z))
      anchor-s("T2", (-1 + 0.2 / 2 + x * 2, 0, -z * 2))
      doc-state("T1", "T2", checkpoint: 2)
      translate((-x, 0, z))
      anchor-s("T3", (-1 + 0.2 / 2 + x * 1, 0, -z * 1))
      doc-state("T2", "T3", checkpoint: 1)
      translate((-x, 0, z))
      anchor-s("T4", (-1 + 0.2 / 2 + x * 0, 0, -z * 0))
      doc-state("T3", "T4", checkpoint: 0)
    })

    translate((-0.7, 0, 0))
    line((0, 0), (0, 1), stroke: 0pt, fill: none)
  })
}


================================================
FILE: src/tutorial/latex-look.typ
================================================
#let latex-look(content) = {
  // #set page(margin: 1.75in)
  set par(
    leading: 0.55em,
    first-line-indent: 0em,
    justify: true,
  )
  set text(font: "New Computer Modern")
  show raw: set text(font: "New Computer Modern Mono")
  show par: set par(spacing: 0.55em)
  show heading: set block(
    above: 1.4em,
    below: 1em,
  )

  content
}


================================================
FILE: src/tutorial/mod.typ
================================================
#import "/src/book.typ"
#import "/typ/templates/page.typ": is-web-target, main-color
#import "/typ/embedded-typst/lib.typ": default-cjk-fonts, default-fonts, svg-doc
#import "../mod.typ": (
  code as _code, exec-code as _exec-code, exercise, mark, pro-tip, ref-bookmark, ref-cons-signature, ref-func-signature,
  ref-method-signature, refs, term, todo-box, todo-color, typst-func,
)

#let eval-local(it, scope, res) = if res != none {
  res
} else {
  eval(it.text, mode: "markup", scope: scope)
}
#let exec-code(it, scope: (:), res: none, ..args) = _exec-code(it, res: eval-local(it, scope, res), ..args)
/// - it (content): the body of code.
#let code(it, scope: (:), res: none, ..args) = _code(it, res: eval-local(it, scope, res), ..args)

#let frames(code, cjk-fonts: false, code-as: none, prelude: none) = {
  if code-as != none {
    code-as
  } else {
    code
  }

  if prelude != none {
    code-as = if code-as == none {
      code
    }
    code = prelude.text + "\n" + code.text
  }

  let fonts = if cjk-fonts {
    (..default-cjk-fonts(), ..default-fonts())
  }

  grid(columns: (1fr, 1fr), ..svg-doc(code, fonts: fonts).pages.map(data => image(bytes(data))).map(rect))
}
#let frames-cjk = frames.with(cjk-fonts: true)


================================================
FILE: src/tutorial/other-file.typ
================================================

一段文本
#set text(fill: red)
另一段文本


================================================
FILE: src/tutorial/packages/m1.typ
================================================

XXX
#let add(x, y) = x + y
YYY
#let sub(x, y) = x - y


================================================
FILE: src/tutorial/reference-bibliography.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：导入和使用参考文献])


================================================
FILE: src/tutorial/reference-calculation.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：数值计算])

#let table-lnk(name, ref, it, scope: (:), res: none, ..args) = (
  align(center + horizon, link("todo", name)),
  it,
  align(
    horizon,
    {
      set heading(
        bookmarked: false,
        outlined: false,
      )
      eval(it.text, mode: "markup", scope: scope)
    },
  ),
)

// calc.*

#todo-box[不再需要等待了]
等待#link("https://github.com/typst/typst/pull/3489")[PR: Begin migration of calc functions to methods]


================================================
FILE: src/tutorial/reference-color.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：颜色、色彩渐变与模式])

== RGB

Create an RGB(A) color. #ref-bookmark[`color.rgb`]

The color is specified in the sRGB color space.

An RGB(A) color is represented internally by an array of four components:

#code(```typ
#square(fill: rgb("#b1f2eb"))
#square(fill: rgb(87, 127, 230))
#square(fill: rgb(25%, 13%, 65%))
```)

== HSL

Create an HSL color. #ref-bookmark[`color.hsl`]

This color space is useful for specifying colors by hue, saturation and lightness. It is also useful for color manipulation, such as saturating while keeping perceived hue.

An HSL color is represented internally by an array of four components:
- hue (angle)
- saturation (ratio)
- lightness (ratio)
- alpha (ratio)

These components are also available using the components method.

#code(```typ
#square(
  fill: color.hsl(30deg, 50%, 60%)
)
```)

== CMYK

Create a CMYK color. #ref-bookmark[`color.cmyk`]

This is useful if you want to target a specific printer. The conversion to RGB for display preview might differ from how your printer reproduces the color.

// todo: typo in reference
An CMYK color is represented internally by an array of four components:
- cyan (ratio)
- magenta (ratio)
- yellow (ratio)
- key (ratio)

These components are also available using the components method.

#code(```typ
#square(
  fill: cmyk(27%, 0%, 3%, 5%)
)
```)

== Luma

== Oklab

== Oklch

== Linear RGB

== HSV

== 色彩空间

Returns the constructor function for this color's space. #ref-bookmark[`color.space`]

== 十六进制表示（RGB）

Returns the color's RGB(A) hex representation. #ref-bookmark[`color.to-hex`]

Hex such as `#ffaa32` or `#020304fe`. The alpha component (last two digits in `#020304fe`) is omitted if it is equal to ff (255 / 100%).

== 颜色计算

=== lighten

Lightens a color by a given factor. #ref-bookmark[`color.lighten`]

=== darken

Darkens a color by a given factor. #ref-bookmark[`color.darken`]

=== saturate

Increases the saturation of a color by a given factor. #ref-bookmark[`color.saturate`]

=== negate

Produces the negative of the color. #ref-bookmark[`color.negate`]

=== rotate

Rotates the hue of the color by a given angle. #ref-bookmark[`color.rotate`]

=== mix

Create a color by mixing two or more colors. #ref-bookmark[`color.mix`]

== 色彩渐变

A color gradient. #ref-bookmark[`gradient`]

Typst supports linear gradients through the gradient.linear function, radial gradients through the gradient.radial function, and conic gradients through the gradient.conic function.

A gradient can be used for the following purposes:

- As a fill to paint the interior of a shape: ```typc rect(fill: gradient.linear(..))```
- As a stroke to paint the outline of a shape: ```typc rect(stroke: 1pt + gradient.linear(..))```
- As the fill of text: ```typc set text(fill: gradient.linear(..))```
- As a color map you can sample from: ```typc gradient.linear(..).sample(0.5)```

#code(```typ
#stack(
  dir: ltr,
  spacing: 1fr,
  square(fill: gradient.linear(
    ..color.map.rainbow)),
  square(fill: gradient.radial(
    ..color.map.rainbow)),
  square(fill: gradient.conic(
    ..color.map.rainbow)),
)
```)

== 填充模式

A repeating pattern fill. #ref-bookmark[`tiling`]

Typst supports the most common pattern type of tiled patterns, where a pattern is repeated in a grid-like fashion, covering the entire area of an element that is filled or stroked. The pattern is defined by a tile size and a body defining the content of each cell. You can also add horizontal or vertical spacing between the cells of the patterng.

#code(```typ
#let pat = tiling(size: (30pt, 30pt))[
  #place(line(start: (0%, 0%), end: (100%, 100%)))
  #place(line(start: (0%, 100%), end: (100%, 0%)))
]

#rect(fill: pat, width: 100%, height: 60pt, stroke: 1pt)
```)


================================================
FILE: src/tutorial/reference-counter-state.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：计数器和状态])


================================================
FILE: src/tutorial/reference-data-process.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：数据读写与数据处理])

#let table-lnk(name, ref, it, scope: (:), res: none, ..args) = (
  align(center + horizon, link("todo", name)),
  it,
  align(
    horizon,
    {
      set heading(bookmarked: false, outlined: false)
      eval(it.text, mode: "markup", scope: scope)
    },
  ),
)

== read

== 数据格式

== 字节数组

== image.decode

== 字符串Unicode

== 正则匹配

== wasm插件

== metadata

== typst query


================================================
FILE: src/tutorial/reference-date.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：时间类型])

#let table-lnk(name, ref, it, scope: (:), res: none, ..args) = (
  align(center + horizon, link("todo", name)),
  it,
  align(
    horizon,
    {
      set heading(bookmarked: false, outlined: false)
      eval(it.text, mode: "markup", scope: scope)
    },
  ),
)

== 日期

日期表示时间长河中的一个具体的时间戳。#ref-bookmark[`datetime`]

#code(```typ
一个值 #datetime(year: 2023, month: 4, day: 19).display() 偷偷混入了我们内容之中。
```)

== 时间间隔

时间间隔表示两个时间戳之间的时间差。#ref-bookmark[`duration`]

#code(```typ
一个值 #duration(days: 3, hours: 10).seconds()s 偷偷混入了我们内容之中。
```)

== typst-pdf时间戳

```typ
set document(date: auto)
```


================================================
FILE: src/tutorial/reference-grammar.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [参考：语法示例检索表])

#let table-lnk(name, ref, it, scope: (:), res: none, ..args) = (
  align(center + horizon, ref(name)),
  it,
  align(
    horizon,
    {
      set heading(
        bookmarked: false,
        outlined: false,
      )
      eval(it.text, mode: "markup", scope: scope)
    },
  ),
)

#let ref-table(items) = table(
  columns: (120pt, 6fr, 5fr),
  align(center)[「名称/术语」],
  align(center)[语法],
  align(center)[渲染结果],
  ..items.map(args => table-lnk(..args)).flatten(),
)

点击下面每行名称都可以跳转到对应章节的对应小节。

== 分类：基本元素 <grammar-table:base-elements>

#ref-table((
  (
    [段落],
    refs.writing-markup.with(reference: <grammar-paragraph>),
    ```typ
    writing-markup
    ```,
  ),
  (
    [标题],
    refs.writing-markup.with(reference: <grammar-heading>),
    ```typ
    = Heading
    ```,
  ),
  (
    [二级标题],
    refs.writing-markup.with(reference: <grammar-heading>),
    ```typ
    == Heading
    ```,
  ),
  (
    [着重标记],
    refs.writing-markup.with(reference: <grammar-strong>),
    ```typ
    *Strong*
    ```,
  ),
  (
    [强调标记],
    refs.writing-markup.with(reference: <grammar-emph>),
    ```typ
    _emphasis_
    ```,
  ),
  (
    [着重且强调标记],
    refs.writing-markup.with(reference: <grammar-emph>),
    ```typ
    *_emphasis_*
    ```,
  ),
  (
    [有序列表],
    refs.writing-markup.with(reference: <grammar-list>),
    ```typ
    + List 1
    + List 2
    ```,
  ),
  (
    [有序列表（重新开始标号）],
    refs.writing-markup.with(reference: <grammar-continue-list>),
    ```typ
    4. List 1
    + List 2
    ```,
  ),
  (
    [无序列表],
    refs.writing-markup.with(reference: <grammar-emum>),
    ```typ
    - Enum 1
    - Enum 2
    ```,
  ),
  (
    [交替有序与无序列表],
    refs.writing-markup.with(reference: <grammar-mix-list-emum>),
    ```typ
    - Enum 1
      + Item 1
    - Enum 2
    ```,
  ),
  (
    [短代码片段],
    refs.writing-markup.with(reference: <grammar-raw>),
    ````typ
    `code`
    ````,
  ),
  (
    [长代码片段],
    refs.writing-markup.with(reference: <grammar-long-raw>),
    ````typ
    ``` code```
    ````,
  ),
  (
    [语法高亮],
    refs.writing-markup.with(reference: <grammar-lang-raw>),
    ````typ
    ```rs  trait World```
    ````,
  ),
  (
    [块代码片段],
    refs.writing-markup.with(reference: <grammar-blocky-raw>),
    ````typ
    ```typ
    = Heading
    ```
    ````,
  ),
  (
    [图像],
    refs.writing-markup.with(reference: <grammar-image>),
    ````typ
    #image("/assets/files/香風とうふ店.jpg", width: 50pt)
    ````,
  ),
  (
    [拉伸图像],
    refs.writing-markup.with(reference: <grammar-image-stretch>),
    ````typ
    #image("/assets/files/香風とうふ店.jpg", width: 50pt, height: 50pt, fit: "stretch")
    ````,
  ),
  (
    [内联图像（盒子法）],
    refs.writing-markup.with(reference: <grammar-image-inline>),
    ````typ
    在一段话中插入一个#box(baseline: 0.15em, image("/assets/files/info-icon.svg", width: 1em))图片。
    ````,
  ),
  (
    [图像标题],
    refs.writing-markup.with(reference: <grammar-figure>),
    ````typ
    #figure(```typ
    #image("/assets/files/香風とうふ店.jpg")
    ```, caption: [用于加载香風とうふ店送外卖的宝贵影像的代码])
    ````,
  ),
  (
    [链接],
    refs.writing-markup.with(reference: <grammar-link>),
    ````typ
    #link("https://zh.wikipedia.org")[维基百科]
    ````,
  ),
  (
    [HTTP(S)链接],
    refs.writing-markup.with(reference: <grammar-http-link>),
    ````typ
    https://zh.wikipedia.org
    ````,
  ),
  (
    [内部链接],
    refs.writing-markup.with(reference: <grammar-internal-link>),
    ````typ
    == 某个标题 <ref-internal-link>
    #link(<ref-internal-link>)[链接到某个标题]
    ````,
  ),
  (
    [表格],
    refs.writing-markup.with(reference: <grammar-table>),
    ````typ
    #table(columns: 2, [111], [2], [3])
    ````,
  ),
  (
    [对齐表格],
    refs.writing-markup.with(reference: <grammar-table-align>),
    ````typ
    #table(columns: 2, align: center, [111], [2], [3])
    ````,
  ),
  (
    [行内数学公式],
    refs.writing-markup.with(reference: <grammar-inline-math>),
    ````typ
    $sum_x$
    ````,
  ),
  (
    [行间数学公式],
    refs.writing-markup.with(reference: <grammar-display-math>),
    ````typ
    $ sum_x $
    ````,
  ),
  (
    [标记转义序列],
    refs.writing-markup.with(reference: <grammar-escape-sequences>),
    ````typ
    >\_<
    ````,
  ),
  (
    [标记的Unicode转义序列],
    refs.writing-markup.with(reference: <grammar-unicode-escape-sequences>),
    ````typ
    \u{9999}
    ````,
  ),
  (
    [换行符（转义序列）],
    refs.writing-markup.with(reference: <grammar-newline-by-space>),
    ````typ
    A \ B
    ````,
  ),
  (
    [换行符情形二],
    refs.writing-markup.with(reference: <grammar-newline>),
    ````typ
    A \
    B
    ````,
  ),
  (
    [速记符],
    refs.writing-markup.with(reference: <grammar-shorthand>),
    ````typ
    北京--上海
    ````,
  ),
  (
    [空格（速记符）],
    refs.writing-markup.with(reference: <grammar-shorthand-space>),
    ````typ
    A~B
    ````,
  ),
  (
    [行内注释],
    refs.writing-markup.with(reference: <grammar-inline-comment>),
    ````typ
    // 行内注释
    ````,
  ),
  (
    [行间注释],
    refs.writing-markup.with(reference: <grammar-cross-line-comment>),
    ````typ
    /* 行间注释
      */
    ````,
  ),
  (
    [行内盒子],
    refs.writing-markup.with(reference: <grammar-box>),
    ````typ
    在一段话中插入一个#box(baseline: 0.15em, image("/assets/files/info-icon.svg", width: 1em))图片。
    ````,
  ),
))

== 分类：修饰文本 <grammar-table:text>

#ref-table((
  (
    [背景高亮],
    refs.writing-markup.with(reference: <grammar-highlight>),
    ````typ
    #highlight[高亮一段内容]
    ````,
  ),
  (
    [下划线],
    refs.writing-markup.with(reference: <grammar-underline>),
    ````typ
    #underline[Language]
    ````,
  ),
  (
    [无驱逐效果的下划线],
    refs.writing-markup.with(reference: <grammar-underline-evade>),
    ````typ
    #underline(
      evade: false)[ጿኈቼዽ]
    ````,
  ),
  (
    [上划线],
    refs.writing-markup.with(reference: <grammar-overline>),
    ````typ
    #overline[ጿኈቼዽ]
    ````,
  ),
  (
    [中划线（删除线）],
    refs.writing-markup.with(reference: <grammar-strike>),
    ````typ
    #strike[ጿኈቼዽ]
    ````,
  ),
  (
    [下标],
    refs.writing-markup.with(reference: <grammar-subscript>),
    ````typ
    威严满满#sub[抱头蹲防]
    ````,
  ),
  (
    [上标],
    refs.writing-markup.with(reference: <grammar-superscript>),
    ````typ
    香風とうふ店#super[TM]
    ````,
  ),
  (
    [设置文本大小],
    refs.writing-markup.with(reference: <grammar-text-size>),
    ````typ
    #text(size: 24pt)[一斤鸭梨]
    ````,
  ),
  (
    [设置文本颜色],
    refs.writing-markup.with(reference: <grammar-text-fill>),
    ````typ
    #text(fill: blue)[蓝色鸭梨]
    ````,
  ),
  (
    [设置字体],
    refs.writing-markup.with(reference: <grammar-text-font>),
    ````typ
    #text(font: "Microsoft YaHei")[板正鸭梨]
    ````,
  ),
))

== 分类：脚本声明 <grammar-table:decl>

#ref-table((
  (
    [进入脚本模式],
    refs.writing-markup.with(reference: <grammar-enter-script>),
    ````typ
    #1
    ````,
  ),
  (
    [代码块],
    refs.writing-markup.with(reference: <grammar-code-block>),
    ````typ
    #{"a"; "b"}
    ````,
  ),
  (
    [内容块],
    refs.writing-markup.with(reference: <grammar-content-block>),
    ````typ
    #[内容块]
    ````,
  ),
  (
    [空字面量],
    refs.content-scope-style.with(reference: <grammar-none-literal>),
    ````typ
    #none
    ````,
  ),
  (
    [假（布尔值）],
    refs.content-scope-style.with(reference: <grammar-false-literal>),
    ````typ
    #false
    ````,
  ),
  (
    [真（布尔值）],
    refs.content-scope-style.with(reference: <grammar-true-literal>),
    ````typ
    #true
    ````,
  ),
  (
    [整数字面量],
    refs.content-scope-style.with(reference: <grammar-integer-literal>),
    ````typ
    #(-1), #(0), #(1)
    ````,
  ),
  (
    [进制数字面量],
    refs.content-scope-style.with(reference: <grammar-n-adecimal-literal>),
    ````typ
    #(-0xdeadbeef), #(-0o644), #(-0b1001)
    ````,
  ),
  (
    [浮点数字面量],
    refs.content-scope-style.with(reference: <grammar-float-literal>),
    ````typ
    #(0.001), #(.1), #(2.)
    ````,
  ),
  (
    [指数表示法],
    refs.content-scope-style.with(reference: <grammar-exp-repr-float>),
    ````typ
    #(1e2), #(1.926e3), #(-1e-3)
    ````,
  ),
  (
    [字符串字面量],
    refs.content-scope-style.with(reference: <grammar-string-literal>),
    ````typ
    #"Hello world!!"
    ````,
  ),
  (
    [字符串转义序列],
    refs.scripting-base.with(reference: <grammar-str-escape-sequences>),
    ````typ
    #"\""
    ````,
  ),
  (
    [字符串的Unicode转义序列],
    refs.scripting-base.with(reference: <grammar-str-unicode-escape-sequences>),
    ````typ
    #"\u{9999}"
    ````,
  ),
  (
    [数组字面量],
    refs.content-scope-style.with(reference: <grammar-array-literal>),
    ````typ
    #(1, "OvO", [一段内容])
    ````,
  ),
  (
    [字典字面量],
    refs.content-scope-style.with(reference: <grammar-dict-literal>),
    ````typ
    #(neko-mimi: 2, "utterance": "喵喵喵")
    ````,
  ),
  (
    [空数组],
    refs.content-scope-style.with(reference: <grammar-empty-array>),
    ````typ
    #()
    ````,
  ),
  (
    [空字典],
    refs.content-scope-style.with(reference: <grammar-empty-dict>),
    ````typ
    #(:)
    ````,
  ),
  (
    [被括号包裹的空数组],
    refs.content-scope-style.with(reference: <grammar-paren-empty-array>),
    ````typ
    #(())
    ````,
  ),
  (
    [含有一个元素的数组],
    refs.content-scope-style.with(reference: <grammar-single-member-array>),
    ````typ
    #(1,)
    ````,
  ),
  (
    [变量声明],
    refs.content-scope-style.with(reference: <grammar-var-decl>),
    ````typ
    #let x = 1
    ````,
  ),
  (
    [函数声明],
    refs.content-scope-style.with(reference: <grammar-func-decl>),
    ````typ
    #let f(x) = x * 2
    ````,
  ),
  (
    [函数闭包],
    refs.content-scope-style.with(reference: <grammar-closure>),
    ````typ
    #let f = (x, y) => x + y
    ````,
  ),
  (
    [具名参数声明],
    refs.content-scope-style.with(reference: <grammar-named-param>),
    ````typ
    #let g(named: none) = named
    ````,
  ),
  (
    [含变参函数],
    refs.content-scope-style.with(reference: <grammar-variadic-param>),
    ````typ
    #let g(..args) = args.pos().join([、])
    ````,
  ),
  (
    [数组解构赋值],
    refs.content-scope-style.with(reference: <grammar-destruct-array>),
    ````typ
    #let (one, hello-world) = (1, "Hello, World")
    ````,
  ),
  (
    [数组解构赋值情形二],
    refs.content-scope-style.with(reference: <grammar-destruct-array-eliminate>),
    ````typ
    #let (_, second, ..) = (1, "Hello, World", []); #second
    ````,
  ),
  (
    [字典解构赋值],
    refs.content-scope-style.with(reference: <grammar-destruct-dict>),
    ````typ
    #let (neko-mimi: mimi) = (neko-mimi: 2); #mimi
    ````,
  ),
  (
    [数组内容重映射],
    refs.content-scope-style.with(reference: <grammar-array-remapping>),
    ````typ
    #let (a, b, c) = (1, 2, 3)
    #let (b, c, a) = (a, b, c)
    #a, #b, #c
    ````,
  ),
  (
    [数组内容交换],
    refs.content-scope-style.with(reference: <grammar-array-swap>),
    ````typ
    #let (a, b) = (1, 2)
    #((a, b) = (b, a))
    #a, #b
    ````,
  ),
  (
    [占位符（`let _ = ..`）],
    refs.content-scope-style.with(reference: <grammar-placeholder>),
    ````typ
    #let last-two(t) = {
      let _ = t.pop()
      t.pop()
    }
    #last-two((1, 2, 3, 4))
    ````,
  ),
))

== 分类：脚本语句

#ref-table((
  (
    [`if`语句],
    refs.content-scope-style.with(reference: <grammar-if>),
    ````typ
    #if true { 1 },
    #if false { 1 } else { 0 }
    ````,
  ),
  (
    [串联`if`语句],
    refs.content-scope-style.with(reference: <grammar-if-if>),
    ````typ
    #if false { 0 } else if true { 1 },
    #if false { 2 } else if false { 1 } else { 0 }
    ````,
  ),
  (
    [`while`语句],
    refs.content-scope-style.with(reference: <grammar-while>),
    ````typ
    #{
      let i = 0;
      while i < 10 {
        (i * 2, )
        i += 1;
      }
    }
    ````,
  ),
  (
    [`for`语句],
    refs.content-scope-style.with(reference: <grammar-for>),
    ````typ
    #for i in range(10) {
      (i * 2, )
    }
    ````,
  ),
  (
    [`for`语句解构赋值],
    refs.content-scope-style.with(reference: <grammar-for-destruct>),
    ````typ
    #for (特色, 这个) in (neko-mimi: 2) [猫猫的 #特色 是 #这个\ ]
    ````,
  ),
  (
    [`break`语句],
    refs.content-scope-style.with(reference: <grammar-break>),
    ````typ
    #for i in range(10) { (i, ); (i + 1926, ); break }
    ````,
  ),
  (
    [`continue`语句],
    refs.content-scope-style.with(reference: <grammar-continue>),
    ````typ
    #for i in range(10) {
      if calc.even(i) { continue }
      (i, )
    }
    ````,
  ),
  (
    [`return`语句],
    refs.content-scope-style.with(reference: <grammar-return>),
    ````typ
    #let never(..args) = return
    #type(never(1, 2))
    ````,
  ),
  (
    [`include`语句],
    refs.content-scope-style.with(reference: <grammar-include>),
    ````typ
    #include "other-file.typ"
    ````,
  ),
))

== 分类：脚本样式

#ref-table((
  (
    [`set`语句],
    refs.content-scope-style.with(reference: <grammar-set>),
    ````typ
    #set text(size: 24pt)
    四斤鸭梨
    ````,
  ),
  (
    [作用域],
    refs.content-scope-style.with(reference: <grammar-scope>),
    ````typ
    两只#[兔#set text(fill: rgb("#ffd1dc").darken(15%))
      #[兔白#set text(fill: orange)
      又白]，真可爱
    ]
    ````,
  ),
  (
    [`set if`语句],
    refs.content-scope-style.with(reference: <grammar-set-if>),
    ````typ
    #let is-dark-theme = true
    #set rect(fill: black) if is-dark-theme
    #set text(fill: white) if is-dark-theme
    #rect([wink!])
    ````,
  ),
  (
    [`show set`语句],
    refs.content-scope-style.with(reference: <grammar-show-set>),
    ````typ
    #show: set text(fill: blue)
    wink!
    ````,
  ),
  (
    [`show`语句],
    refs.content-scope-style.with(reference: <grammar-show>),
    ````typ
    #show raw: it => it.lines.at(1)
    获取代码片段第二行内容：```typ
    #{
    set text(fill: true)
    }
    ```
    ````,
  ),
  (
    [文本选择器],
    refs.content-scope-style.with(reference: <grammar-text-selector>),
    ````typ
    #show "cpp": strong(emph(box("C++")))
    在古代，cpp是一门常用语言。
    ````,
  ),
  (
    [正则文本选择器],
    refs.content-scope-style.with(reference: <grammar-regex-selector>),
    ````typ
    #show regex("[”。]+"): it => {
      set text(font: "KaiTi")
      highlight(it, fill: yellow)
    }
    “无名，万物之始也；有名，万物之母也。”
    ````,
  ),
  (
    [标签选择器],
    refs.content-scope-style.with(reference: <grammar-label-selector>),
    ````typ
    #show <一整段话>: set text(fill: blue)
    #[$lambda$语言是世界上最好的语言。] <一整段话>

    另一段话。
    ````,
  ),
  (
    [选择器表达式],
    refs.content-scope-style.with(reference: <grammar-selector-exp>),
    ````typ
    #show heading.where(level: 2): set text(fill: blue)
    = 一级标题
    == 二级标题
    ````,
  ),
  (
    [获取位置],
    refs.content-scope-style.with(reference: <grammar-here>),
    ````typ
    #context here().position()
    ````,
  ),
  (
    [检测当前页面是否为偶数页（位置相关计算）],
    refs.content-scope-style.with(reference: <grammar-here-calc>),
    ````typ
    #context [ 页码是偶数：#calc.even(here().page()) ]
    ````,
  ),
  (
    [查询文档内容],
    refs.content-scope-style.with(reference: <grammar-query>),
    ````typ
    #context query(<ref-internal-link>).at(0).body
    ````,
  ),
  (
    [声明全局状态],
    refs.content-scope-style.with(reference: <grammar-state>),
    ````typ
    #state("my-state", 1)
    ````,
  ),
))

== 分类：脚本表达式

#ref-table((
  (
    [函数调用],
    refs.writing-markup.with(reference: <grammar-func-call>),
    ````typ
    #calc.pow(4, 3)
    ````,
  ),
  (
    [函数调用传递内容参数],
    refs.writing-markup.with(reference: <grammar-content-param>),
    ````typ
    #emph[emphasis]
    ````,
  ),
  (
    [成员访问],
    refs.content-scope-style.with(reference: <grammar-member-exp>),
    ````typ
    #`OvO`.text
    ````,
  ),
  (
    [方法调用],
    refs.content-scope-style.with(reference: <grammar-method-exp>),
    ````typ
    #"Hello World".split(" ")
    ````,
  ),
  (
    [字典成员访问],
    refs.content-scope-style.with(reference: <grammar-dict-member-exp>),
    ````typ
    #let cat = (neko-mimi: 2)
    #cat.neko-mimi
    ````,
  ),
  (
    [内容成员访问],
    refs.content-scope-style.with(reference: <grammar-content-member-exp>),
    ````typ
    #`OvO`.text
    ````,
  ),
  (
    [代码表示的自省函数],
    refs.content-scope-style.with(reference: <grammar-repr>),
    ````typ
    #repr[ 一段文本 ]
    ````,
  ),
  (
    [类型的自省函数],
    refs.content-scope-style.with(reference: <grammar-type>),
    ````typ
    #type[一段文本]
    ````,
  ),
  (
    [求值函数],
    refs.content-scope-style.with(reference: <grammar-eval>),
    ````typ
    #type(eval("1"))
    ````,
  ),
  (
    [求值函数（标记模式）],
    refs.content-scope-style.with(reference: <grammar-eval-markup-mode>),
    ````typ
    #eval("== 一个标题", mode: "markup")
    ````,
  ),
  (
    [判断数组内容],
    refs.content-scope-style.with(reference: <grammar-array-in>),
    ````typ
    #let pol = (1, "OvO", [])
    #(1 in pol)
    ````,
  ),
  (
    [判断数组内容不在],
    refs.content-scope-style.with(reference: <grammar-array-not-in>),
    ````typ
    #let pol = (1, "OvO", [])
    #([另一段内容] not in pol)
    ````,
  ),
  (
    [判断字典内容],
    refs.content-scope-style.with(reference: <grammar-dict-in>),
    ````typ
    #let cat = (neko-mimi: 2)
    #("neko-mimi" in cat)
    ````,
  ),
  (
    [逻辑比较表达式],
    refs.content-scope-style.with(reference: <grammar-logical-cmp-exp>),
    ````typ
    #(1 < 0), #(1 >= 2),
    #(1 == 2), #(1 != 2)
    ````,
  ),
  (
    [逻辑运算表达式],
    refs.content-scope-style.with(reference: <grammar-logical-calc-exp>),
    ````typ
    #(not false), #(false or true), #(true and false)
    ````,
  ),
  (
    [取正运算],
    refs.content-scope-style.with(reference: <grammar-plus-exp>),
    ````typ
    #(+1), #(+0), #(1), #(++1)
    ````,
  ),
  (
    [取负运算],
    refs.content-scope-style.with(reference: <grammar-minus-exp>),
    ````typ
    #(-1), #(-0), #(--1),
    #(-+-1)
    ````,
  ),
  (
    [算术运算表达式],
    refs.content-scope-style.with(reference: <grammar-arith-exp>),
    ````typ
    #(1 + 1), #(1 + -1),
    #(1 - 1), #(1 - -1)
    ````,
  ),
  (
    [赋值表达式],
    refs.content-scope-style.with(reference: <grammar-assign-exp>),
    ````typ
    #let a = 1; #repr(a = 10), #a, #repr(a += 2), #a
    ````,
  ),
  (
    [字符串连接],
    refs.content-scope-style.with(reference: <grammar-string-concat-exp>),
    ````typ
    #("a" + "b")
    ````,
  ),
  (
    [重复连接字符串],
    refs.content-scope-style.with(reference: <grammar-string-mul-exp>),
    ````typ
    #("a" * 4), #(4 * "ab")
    ````,
  ),
  (
    [字符串比较],
    refs.content-scope-style.with(reference: <grammar-string-cmp-exp>),
    ````typ
    #("a" == "b"), #("a" != "b"), #("a" < "ab"), #("a" >= "a")
    ````,
  ),
  (
    [整数转浮点数],
    refs.content-scope-style.with(reference: <grammar-int-to-float>),
    ````typ
    #float(1), #(type(float(1)))
    ````,
  ),
  (
    [布尔值转整数],
    refs.content-scope-style.with(reference: <grammar-bool-to-int>),
    ````typ
    #int(true), #(type(int(true)))
    ````,
  ),
  (
    [浮点数转整数],
    refs.content-scope-style.with(reference: <grammar-float-to-int>),
    ````typ
    #int(1), #(type(int(1)))
    ````,
  ),
  (
    [十进制字符串转整数],
    refs.content-scope-style.with(reference: <grammar-dec-str-to-int>),
    ````typ
    #int("1"), #(type(int("1")))
    ````,
  ),
  (
    [十六进制/八进制/二进制字符串转整数],
    refs.content-scope-style.with(reference: <grammar-nadec-str-to-int>),
    ````typ
    #let safe-to-int(x) = {
      let res = eval(x)
      assert(type(res) == int, message: "should be integer")
      res
    }
    #safe-to-int("0xf"), #(type(safe-to-int("0xf"))) \
    #safe-to-int("0o755"), #(type(safe-to-int("0o755"))) \
    #safe-to-int("0b1011"), #(type(safe-to-int("0b1011"))) \
    ````,
  ),
  (
    [数字转字符串],
    refs.content-scope-style.with(reference: <grammar-num-to-str>),
    ````typ
    #repr(str(1)),
    #repr(str(.5))
    ````,
  ),
  (
    [整数转十六进制字符串],
    refs.content-scope-style.with(reference: <grammar-int-to-nadec-str>),
    ````typ
    #str(501, base:16), #str(0xdeadbeef, base:36)
    ````,
  ),
  (
    [布尔值转字符串],
    refs.content-scope-style.with(reference: <grammar-bool-to-str>),
    ````typ
    #repr(false)
    ````,
  ),
  (
    [数字转布尔值],
    refs.content-scope-style.with(reference: <grammar-int-to-bool>),
    ````typ
    #let to-bool(x) = x != 0
    #repr(to-bool(0)),
    #repr(to-bool(1))
    ````,
  ),
))


================================================
FILE: src/tutorial/reference-layout.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：布局函数])

已经移至《度量与布局》。


================================================
FILE: src/tutorial/reference-length.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：长度单位])

已经移至《度量与布局》。


================================================
FILE: src/tutorial/reference-math-mode.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：数学模式])


================================================
FILE: src/tutorial/reference-math-symbols.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [参考：常用数学符号])

#set table(
  stroke: none,
  align: horizon + left,
  row-gutter: 0.45em,
)

推荐阅读：
+ #link("https://github.com/johanvx/typst-undergradmath/releases/download/v1.4.0/undergradmath.pdf")[本科生Typst数学英文版，适用于Typst 0.11.1]
+ #link("https://github.com/brynne8/typst-undergradmath-zh/blob/6a1028bc13c525f29f6445e92fc6af3246b3c3cb/undergradmath.pdf")[本科生Typst数学中文版，适用于Typst 0.9.0]

以下表格列出了*数学模式*中的常用符号。

#figure(
  table(
    columns: 8,
    [$hat(a)$], [`hat(a)`], [$caron(a)$], [`caron(a)`], [$tilde(a)$], [`tilde(a)`], [$grave(a)$], [`grave(a)`],
    [$dot(a)$],
    [`dot(a)`],
    [$dot.double(a)$],
    [dot.double(a)],
    [$macron(a)$],
    [`macron(a)`],
    [$arrow(a)$],
    [`arrow(a)`],

    [$acute(a)$], [`acute(a)`], [$breve(a)$], [`breve(a)`],
  ),
  caption: [数学模式重音符号],
)

#figure(
  table(
    columns: 8,
    [$alpha$], [`alpha`], [$theta$], [`theta`], [$o$], [`o`], [$upsilon$], [`upsilon`],
    [$beta$], [`beta`], [$theta.alt$], [`theta.alt`], [$pi$], [`pi`], [$phi$], [`phi`],
    [$gamma$], [`gamma`], [$iota$], [`iota`], [$pi.alt$], [`pi.alt`], [$phi$], [`phi`],
    [$delta$], [`delta`], [$kappa$], [`kappa`], [$rho$], [`rho`], [$chi$], [`chi`],
    [$epsilon.alt$], [`epsilon.alt`], [$lambda$], [`lambda`], [$rho.alt$], [`rho.alt`], [$psi$], [`psi`],
    [$epsilon$], [`epsilon`], [$mu$], [`mu`], [$sigma$], [`sigma`], [$omega$], [`omega`],
    [$zeta$], [`zeta`], [$nu$], [`nu`], [$sigma.alt$], [`sigma.alt`], [$$], [``],
    [$eta$], [`eta`], [$xi$], [`xi`], [$tau$], [`tau`], [$$], [``],
    [$Gamma$], [`Gamma`], [$Lambda$], [`Lambda`], [$Sigma$], [`Sigma`], [$Psi$], [`Psi`],
    [$Delta$], [`Delta`], [$Xi$], [`Xi`], [$Upsilon$], [`Upsilon`], [$Omega$], [`Omega`],
    [$Theta$], [`Theta`], [$Pi$], [`Pi`], [$Phi$], [`Phi`],
  ),
  caption: [希腊字母],
)

#figure(
  table(
    columns: 6,
    [$<$], [`<, lt`], [$>$], [`>, gt`], [$=$], [`=`],
    [$<=$], [`<=, lt.eq`], [$>=$], [`>=, gt.eq`], [$equiv$], [`equiv`],
    [$<<$], [`<<, lt.double`], [$>>$], [`>>, gt.double`], [$$], [``],
    [$prec$], [`prec`], [$succ$], [`succ`], [$tilde$], [`tilde`],
    [$prec.eq$], [`prec.eq`], [$succ.eq$], [`succ.eq`], [$tilde.eq$], [`tilde.eq`],
    [$subset$], [`subset`], [$supset$], [`supset`], [$approx$], [`approx`],
    [$subset.eq$], [`subset.eq`], [$supset.eq$], [`supset.eq`], [$tilde.equiv$], [`tilde.equiv`],
    [$subset.sq$], [`subset.sq`], [$supset.sq$], [`supset.sq`], [$join$], [`join`],
    [$subset.eq.sq$], [`subset.eq.sq`], [$supset.eq.sq$], [`supset.eq.sq`], [$$], [``],
    [$in$], [`in`], [$in.rev$], [`in.rev`], [$prop$], [`prop`],
    [$tack.r$], [`tack.r`], [$tack.l$], [`tack.l`], [$tack.r.double$], [`tack.r.double`],
    [$divides$], [`divides`], [$parallel$], [`parallel`], [$tack.t$], [`tack.t`],
    [$:$], [`:`], [$in.not$], [`in.not`], [$!=$], [`!=, eq.not`],
  ),
  caption: [二元关系],
)

#figure(
  table(
    columns: 6,
    [$+$], [`+, plus`], [$-$], [`-, minus`], [$$], [``],
    [$plus.minus$], [`plus.minus`], [$minus.plus$], [`minus.plus`], [$lt.tri$], [`lt.tri`],
    [$dot$], [`dot`], [$div$], [`div`], [$gt.tri$], [`gt.tri`],
    [$times$], [`times`], [$without$], [`without`], [$star$], [`star`],
    [$union$], [`union`], [$inter$], [`inter`], [$*$], [`*`],
    [$union.sq$], [`union.sq`], [$inter.sq$], [`inter.sq`], [$circle.stroked.tiny$], [`circle.stroked.tiny`],
    [$or$], [`or`], [$and$], [`and`], [$bullet$], [`bullet`],
    [$xor$], [`xor`], [$minus.circle$], [`minus.circle`], [$dot.circle$], [`dot.circle`],
    [$union.plus$], [`union.plus`], [$times.circle$], [`times.circle`], [$circle.big$], [`circle.big`],
    [$product.co$],
    [`product.co`],
    [$triangle.stroked.t$],
    [`triangle.stroked.t`],
    [$triangle.stroked.b$],
    [`triangle.stroked.b`],

    [$dagger$], [`dagger`], [$lt.tri$], [`lt.tri`], [$gt.tri$], [`gt.tri`],
    [$dagger.double$], [`dagger.double`], [$lt.tri.eq$], [`lt.tri.eq`], [$gt.tri.eq$], [`gt.tri.eq`],
    [$wreath$], [`wreath`],
  ),
  caption: [二元运算符],
)

#figure(
  table(
    columns: 6,
    [$sum$], [`sum`], [$union.big$], [`union.big`], [$or.big$], [`or.big`],
    [$product$], [`product`], [$inter.big$], [`inter.big`], [$and.big$], [`and.big`],
    [$product.co$], [`product.co`], [$union.sq.big$], [`union.sq.big`], [$union.plus.big$], [`union.plus.big`],
    [$integral$], [`integral`], [$integral.cont$], [`integral.cont`], [$dot.circle.big$], [`dot.circle.big`],
    [$plus.circle.big$], [`plus.circle.big`], [$times.circle.big$], [`times.circle.big`],
  ),
  caption: [「大」运算符],
)

#figure(
  table(
    columns: 4,
    [$arrow.l$], [`arrow.l`], [$arrow.l.long$], [`arrow.l.long`],
    [$arrow.r$], [`arrow.r`], [$arrow.r.long$], [`arrow.r.long`],
    [$arrow.l.r$], [`arrow.l.r`], [$arrow.l.r.long$], [`arrow.l.r.long`],
    [$arrow.l.double$], [`arrow.l.double`], [$arrow.l.double.long$], [`arrow.l.double.long`],
    [$arrow.r.double$], [`arrow.r.double`], [$arrow.r.double.long$], [`arrow.r.double.long`],
    [$arrow.l.r.double$], [`arrow.l.r.double`], [$arrow.l.r.double.long$], [`arrow.l.r.double.long`],
    [$arrow.r.bar$], [`arrow.r.bar`], [$arrow.r.long.bar$], [`arrow.r.long.bar`],
    [$arrow.l.hook$], [`arrow.l.hook`], [$arrow.r.hook$], [`arrow.r.hook`],
    [$harpoon.lt$], [`harpoon.lt`], [$harpoon.rt$], [`harpoon.rt`],
    [$harpoon.lb$], [`harpoon.lb`], [$harpoon.rb$], [`harpoon.rb`],
    [$harpoons.ltrb$], [`harpoons.ltrb`], [$arrow.t$], [`arrow.t`],
    [$arrow.b$], [`arrow.b`], [$arrow.t.b$], [`arrow.t.b`],
    [$arrow.t.double$], [`arrow.t.double`], [$arrow.b.double$], [`arrow.b.double`],
    [$arrow.t.b.double$], [`arrow.t.b.double`], [$arrow.tr$], [`arrow.tr`],
    [$arrow.br$], [`arrow.br`], [$arrow.bl$], [`arrow.bl`],
    [$arrow.tl$], [`arrow.tl`], [$arrow.r.squiggly$], [`arrow.r.squiggly`],
  ),
  caption: [箭头],
)

#figure(
  table(
    columns: 6,
    [$dots$], [`dots`], [$dots.c$], [`dots.c`], [$dots.v$], [`dots.v`],
    [$dots.down$], [`dots.down`], [$planck.reduce$], [`planck.reduce`], [$dotless.i$], [`dotless.i`],
    [$dotless.j$], [`dotless.j`], [$ell$], [`ell`], [$Re$], [`Re`],
    [$Im$], [`Im`], [$aleph$], [`aleph`], [$forall$], [`forall`],
    [$exists$], [`exists`], [$Omega.inv$], [`Omega.inv`], [$partial$], [`partial`],
    [$prime$], [`', prime`], [$emptyset$], [`emptyset`], [$infinity$], [`infinity`],
    [$nabla$], [`nabla`], [$triangle.stroked.t$], [`triangle.stroked.t`], [$square.stroked$], [`square.stroked`],
    [$diamond.stroked$], [`diamond.stroked`], [$bot$], [`bot`], [$top$], [`top`],
    [$angle$], [`angle`], [$suit.club$], [`suit.club`], [$suit.spade$], [`suit.spade`],
    [$not$], [`not`],
  ),
  caption: [其他符号],
)


================================================
FILE: src/tutorial/reference-outline.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：文档大纲])


================================================
FILE: src/tutorial/reference-syntax-analysis.typ
================================================

== variable identifier

// `let`关键字后紧接着跟随一个#term("variable identifier")。标识符是变量的“名称”。「变量声明」后续的位置都可以通过标识符引用该变量。

// + 标识符以Unicode字母、Unicode数字和#mark("_")开头。以下是示例的合法变量名：
//   ```typ
//   // 以英文字母开头，是Unicode字母
//   #let a; #let z; #let A; #let Z;
//   // 以汉字开头，是Unicode字母
//   #let 这;
//   // 以下划线开头
//   #let _;
//   ```
// + 标识符后接有限个Unicode字母、Unicode数字、#mark("hyphen")和#mark("_")。以下是示例的合法变量名：
//   ```typ
//   // 纯英文变量名，带连字号
//   #let alpha-test; #let alpha--test;
//   // 纯中文变量名
//   #let 这个变量; #let 这个_变量; #let 这个-变量;
//   // 连字号、下划线在多种位置
//   #let alpha-; // 连字号不能在变量名开头位置
//   #let _alpha; #let alpha_;
//   ```
// + 特殊规则：标识符仅为#mark("_")时，不允许在后续位置继续使用。
//   #code(```typ
//   #let _ = 1;
//   // 不能编译：#_
//   ```)
//   该标识符被称为#term("placeholder")。
// + 特殊规则：标识符不允许为`let`、`set`、`show`等关键字。
//   #code(```typ
//   // 不能编译：
//   // #let let = 1;
//   ```)

// 建议标识符简短且具有描述性。同时建议标识符中仅含英文与#mark("hyphen")。

== let statement

// 「变量声明」可以没有初始值表达式：

// #code(```typ
// #let x
// #repr(x)
// ```)

// 事实上，它等价于将`x`初始化为`none`。

// #code(```typ
// #let x = none
// #repr(x)
// ```)

// 尽管Typst允许你不写初始值表达式，本书还是建议你让所有的「变量声明」都具有初始值表达式。因为初始值表达式还告诉阅读你代码的人这个变量可能具有什么样的类型。

== expression

// === 逻辑比较表达式 <grammar-logical-cmp-exp>

// 数字之间可以相互（算术逻辑）比较，并产生布尔类型的表达式：

// - 小于：
//   #code(```typ
//   #(1 < 0), #(1 < 1), #(1 < 2)
//   ```)
// - 小于等于：
//   #code(```typ
//   #(1 <= 0), #(1 <= 1), #(1 <= 2)
//   ```)
// - 大于：
//   #code(```typ
//   #(1 > 0), #(1 > 1), #(1 > 2)
//   ```)
// - 大于等于：
//   #code(```typ
//   #(1 >= 0), #(1 >= 1), #(1 >= 2)
//   ```)
// - 等于：
//   #code(```typ
//   #(1 == 0), #(1 == 1), #(1 == 2)
//   ```)
// - 不等于：
//   #code(```typ
//   #(1 != 0), #(1 != 1), #(1 != 2)
//   ```)

// 不仅整数与整数之间、浮点数与浮点数之间可以做比较，而且整数与浮点数之间也可以做比较。当整数与浮点数相互比较时，整数会转换为浮点数再参与比较。
// #code(```typ
// #(1 != 0.), #(1 != 1.), #(1 != 2.)
// ```)

// === 算术运算表达式 <grammar-arith-exp>

// 数字之间可以做算术运算，并产生数字结果的表达式：

// - 取正运算：<grammar-plus-exp>
//   #code(```typ
//   #(+1), #(+0), #(++1)
//   ```)
// - 取负运算：<grammar-minus-exp>
//   #code(```typ
//   #(-1), #(-0), #(--1), #(-+-1)
//   ```)
// - 加运算：
//   #code(```typ
//   #(1 + 2), #(1 + 1), #(1 + -1), #(1 + -2)
//   ```)
// - 减运算：
//   #code(```typ
//   #(1 - 2), #(1 - 1), #(1 - -1), #(1 - -2)
//   ```)
// - 乘运算：
//   #code(```typ
//   #(1 * 2), #(2 * 2), #(2 * -2)
//   ```)
// - 除运算：
//   #code(```typ
//   #(1 / 2), #(2 / 2), #(2 / -2)
//   ```)

// 值得注意的是$-2^63$在Typst中是浮点数，这可能是Typst的bug：

// #code(```typ
// #type(-9223372036854775808)
// ```)

// 为了正常使用该整数值你需要强制转换：

// #code(```typ
// #int(-9223372036854775808), #type(int(-9223372036854775808))
// ```)

// 在日常生活中，我们还常用整除，如下方法实现了整除：

// #code(```typ
// #let fdiv(x, y) = int(x / y)
// #fdiv(3, 2), #fdiv(-12, 2), #fdiv(-12, 5) \
// // 或
// #int(3 / 2), #int(-12 / 2), #int(-12 / 5)
// ```)

// #pro-tip[
//   `calc.rem`函数帮你求解整除的余数：
//   #code(```typ
//   #let fdiv(x, y) = int(x / y)
//   $ 3 div & 2 = & #fdiv(  3, 2) & ...... & #calc.rem(  3, 2). \
//   -12 div & 2 = & #fdiv(-12, 2) & ...... & #calc.rem(-12, 2). \
//   -12 div & 5 = & #fdiv(-12, 5) & ...... & #calc.rem(-12, 5). $
//   ```)
// ]

// === 赋值表达式 <grammar-assign-exp>

// 变量可以被赋予一个表达式的值，所有的赋值表达式都产生`none`值而非返回变量的值。

// - 赋值及先加（减、乘或除）后赋值：
//   #code(```typ
//   #let a = 1
//   #repr(a = 10), #a, #repr(a += 2), #a, #repr(a -= 2), #a, #repr(a *= 2), #a, #repr(a /= 2), #a
//   ```)

// === 字符串相关的表达式

// 字符串相加表示字符串的连接：<grammar-string-concat-exp>

// #code(```typ
// #("a" + "b")
// ```)

// 字符串与数字相乘表示将该字符串重复$n$次后再连接：<grammar-string-mul-exp>

// #code(```typ
// #("a" * 4), #(4 * "ab")
// ```)

// 字符串之间的比较遵从#link("https://en.wikipedia.org/wiki/Lexicographic_order")[#term("lexicographical order")]。<grammar-string-cmp-exp>

// 等于和不等于的比较，比较每个字符是否相等：

// #code(```typ
// #("a" == "a"), #("a" != "a") \
// #("a" == "b"), #("a" != "b") \
// ```)

// 大于和小于的比较，从第一个字符开始依次比较，比较每个字符是否相等。直到第一个不相等的字符时作以下判断，字符的Unicode值较小的字符串则x相应更“小”：

// #code(```typ
// #("a" < "b"), #("a" > "a"),  \
// #("a" < "ba"), #("ac" < "ba"), #("aac" < "aba")
// ```)

// 若一直比到了其中一个字符串的尽头，则较短的字符串更“小”：

// #code(```typ
// #("a" < "ab")
// ```)

// 大于等于和小于等于的比较则将「相等性」纳入考虑：

// #code(```typ
// #("a" >= "a"), #("a" <= "a") \
// ```)


================================================
FILE: src/tutorial/reference-table.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：表格])


================================================
FILE: src/tutorial/reference-type-builtin.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：内置类型])

== 空类型 <reference-type-none>

== type <reference-type-type>

== content <reference-type-content>

== function <reference-type-function>

== arguments <reference-type-arguments>

== module <reference-type-module>

== plugin <reference-type-plugin>

== regex <reference-type-regex>

== label <reference-type-label>

== reference <reference-type-reference>

== selector <reference-type-selector>

== version <reference-type-version>


================================================
FILE: src/tutorial/reference-typebase.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：基本类型])

#let glue-block = block.with(breakable: false)

// === 空字面量 <grammar-none-literal>

// 空字面量是纯粹抽象的概念，这意味着你在现实中很难找到对应的实体。就像是数学中的零与负数，空字面量自然产生于运算过程中。

// #code(```typ
// #repr((0, 1).find((_) => false)),
// #repr(if false [啊？])
// ```)

// 上例第一行，当在「数组」中查找一个不存在的元素时，“没有”就是```typc none```。

// 上例第二行，当条件不满足，且没有`false`分支时，“没有内容”就是```typc none```。

// 这些例子都蕴含较复杂的脚本逻辑，会在下一节详细介绍。

// #pro-tip[
//   空字面量自然产生于运算过程中。以下是所有会产生```typc none```的自然场景：
//   - 当变量未初始化时。
//   #code(```typ
//   #let x; #type(x)
//   ```)
//   - 当`if`语句条件不满足，且没有`false`（`else`）分支时，`if`语句的值为```typc none```。
//   #code(```typ
//   #type(if false {})
//   ```)
//   - 当`for`语句、`while`语句、函数没有产生任何值时，函数返回值为```typc none```。
//   #code(```typ
//   #let f() = {}; #type(f())
//   ```)
//   - 当函数显式`return`且未写明返回值时，函数返回值为```typc none```。
//   #code(```typ
//   #let f() = return; #type(f())
//   ```)
// ]

// `none`不产生任何内容：

// #code(```typ
// #none
// ```)

// `none`的类型是`none`类型：

// #code(```typ
// #type(none)
// ```)

// `none`值不等于`none`类型，因为一个是值而另一个是类型：

// #code(```typ
// #(type(none) == none), #type(none), #type(type(none))
// ```)

// // 使用以下方法将`none`转化为布尔类型：

// // #code(```typ
// // #let some-x = none
// // #(some-x == none)
// // #((some-x != none) and (1 < 2))
// // ```)

// === 布尔字面量

// 一个布尔字面量表示逻辑的确否。它要么为`false`（真）<grammar-true-literal>要么为`true`（假）<grammar-false-literal>。

// #code(```typ
// 两个值 #false 和 #true 偷偷混入了我们内容之中。
// ```)

// 一般来说，我们不直接使用布尔值。当代码做逻辑判断的时候，会自然产生布尔值。

// #code(```typ
// $1 < 2$的结果为：#(1 < 2) \
// $1 > 2$的结果为：#(1 > 2)
// ```)

// 布尔值的类型是布尔类型：

// #code(```typ
// #type(false), #type(true)
// ```)

// === 整数字面量 <grammar-integer-literal>

// 一个整数字面量代表一个整数。相信你一定知道整数的含义。Typst中的整数默认为十进制：

// #code(```typ
// 三个值 #(-1)、#0 和 #1 偷偷混入了我们内容之中。
// ```)

// #pro-tip[
//   有的时候Typst不支持在#mark("#")后直接跟一个值。这个时候无论值有多么复杂，都可以将值用一对圆括号包裹起来，从而允许Typst轻松解析该值。例如，Typst无法处理#mark("#")后直接跟随一个#mark("hyphen")的情况：

//   #code(```typ
//   #(-1), #(0), #(1)
//   ```)
// ]

// Typst允许十进制数存在前导零：

// #code(```typ
// #009009
// ```)

// 有些数字使用其他进制表示更为方便。你可以分别使用`0x`、`0o`和`0b`前缀加上进制内容表示十六进制数、八进制数和二进制数：<grammar-n-adecimal-literal>

// #code(```typ
// 十六进制数：#(0xdeadbeef)、#(-0xdeadbeef) \
// 八进制数：#(0o755)、#(-0o644) \
// 二进制数：#(0b1001)、#(-0b1001)
// ```)

// 上例中，当数字被输出到文档时，Typst将数字都转换成了十进制表示。

// 以十六进制数为例介绍其与十进制数之间的关系。将一个十六进制数转换成一个十进制数，计算方式是：从十六进制数的低位（右边）开始，逐步向高位（左边），取每位的字符对应十进制数值，与 $16$ 的 $n$ 次幂相乘（这里的 $n$ 不是固定的，它等于该字符所在的位序 $-1$ ，位序指从低位到高位的排序），最后将每位的计算结果相加，即可获得对应十进制的值。

// 十六进制数字与十进制数字对应关系如下：

// #{
//   set align(center)
//   table(
//     columns: 10,
//     [十六进制],[...],[8],[9],[a/A],[b/B],[c/C],[d/D],[e/E],[f/F],
//     [十进制],[...],[8],[9],[10],[11],[12],[13],[14],[15]
//   )
// }

// 举个例子：十进制的1324相当于十六进制的0x52C。

// + 计算“C”：
//   因为“C”对应的十进制值是12，它所在的位序是1，即它是右边第1位，所以它的值为：$12 dot (16^(1-1)) = 12$
// + 计算“2”：
//   因为“2”对应的十进制值是2，它所在的位序是2，即它是右边第2位，所以它的值为：$2 dot (16^(2-1)) = 32$
// + 计算“5”：
//   因为“5”对应的十进制值是5，它所在的位序是3，即它是右边第3位，所以它的值为：$5 dot (16^(3-1)) = 1280$
// + 将每位结果相加：
//   $ 12 + 32 + 1280 = 1324 $

// 检验：
// #code(```typ
// #1324, #0x52c, #(0x52c == 1324)
// ```)

// 整数的类型是整数类型：

// #code(```typ
// #type(0), #type(0x0), #type(0o0), #type(0b0)
// ```)

// 整数的有效取值范围是$[-2^63,2^63)$，其中$2^63=9223372036854775808$。

// === 浮点数字面量 <grammar-float-literal>

// 浮点数与整数非常类似。最常见的浮点数由至少一个整数部分或小数部分组成：

// #code(```typ
// 三个值 #(0.001)、#(.1) 和 #(2.) 偷偷混入了我们内容之中。
// ```)

// 浮点数的类型是浮点数类型：

// #code(```typ
// #type(2.)
// ```)

// 可见```typc 2.```与```typc 2```类型并不相同。

// 当数字过大时，其会被隐式转换为浮点数存储：

// #code(```typ
// #type(9000000000000000000000000000000)
// ```)

// 整数相除时会被转换为浮点数：

// #code(```typ
// #(10 / 4), #type(10 / 4) \
// #(12 / 4), #type(12 / 4) \
// ```)

// 为了转换类型，可以使用`int`，但有可能产生精度损失（就近取整）：

// #code(```typ
// #int(10 / 4),
// #int(12 / 4),
// #int(9000000000000000000000000000000)
// ```)

// 有些数字使用#term("exponential notation")更为方便。你可以使用标准的#term("exponential notation")创建浮点数：<grammar-exp-repr-float>

// #code(```typ
// #(1e2)、#(1.926e3)、#(-1e-3)
// ```)

// Typst还为你内置了一些特殊的数值，它们都是浮点数：

// #code(```typ
// $pi$=#calc.pi \
// $tau$=#calc.tau \
// $inf$=#calc.inf \
// NaN=#calc.nan \
// ```)

// === 字符串字面量 <grammar-string-literal>

// Typst中所有字符串都是`utf-8`编码的，因此使用时不存在编码问题。字符串由一对「英文双引号」定界：

// #code(```typ
// #"Hello world!!"
// ```)

// 字符串的类型是字符串类型：

// #code(```typ
// #type("Hello world!!")
// ```)

// 有些字符无法置于双引号之内，例如双引号本身。这时候你需要嵌入字符的转义序列：

// #code(```typ
// #"Hello \"world\"!!"
// ```)

// 字符串中的转义序列与「标记模式」中的转义序列语法相同，但内容不同。Typst允许的字符串中的转义序列如下：

// #{
//   set align(center)
//   table(
//     columns: 7,
//     [代码], [`\\`],[`\"`],[`\n`],[`\r`],[`\t`],[`\u{2665}`],
//     [效果], "\\", "\"", [(换行)], [(回车)], [(制表)], "\u{2665}",
//   )
// }

// 与《基础文档》中的转义序列相同，你可以使用`\u{unicode}`格式直接嵌入Unicode字符。

// #code(```typ
// #"香辣牛肉粉好吃\u{2665}"
// ```)

// 除了使用简单字面量构造，可以使用以下方法从代码块获得字符串：

// #code(```typ
// #repr(`包含换行符和双引号的

// "内容"`.text)
// ```)

== 类型转换

整数转浮点数：<grammar-int-to-float>

#code(```typ
#float(1), #(type(float(1)))
```)

布尔值转整数：<grammar-bool-to-int>

#code(```typ
#int(false), #(type(int(false))) \
#int(true), #(type(int(true)))
```)

浮点数转整数：<grammar-float-to-int>

#code(```typ
#int(1), #(type(int(1)))
```)

该方法是就近取整，并有精度损失（根据规范，超出精度范围时，如何选择较近的值舍入是「与实现相关」）：

#code(```typ
#int(1.5), #int(1.99),
// 超出浮点精度范围会就近舍入再转换成整数
#int(1.9999999999999999)
```)

为了向下或向上取整，你可以同时使用`calc.floor`或`calc.ceil`函数（有精度损失）：

#code(```typ
#int(calc.floor(1.9)), #int(calc.ceil(1.9))
```)

十进制字符串转整数：<grammar-dec-str-to-int>

#code(```typ
#int("1"), #(type(int("1")))
```)

十六进制/八进制/二进制字符串转整数：<grammar-nadec-str-to-int>

#code(```typ
#let safe-to-int(x) = {
  let res = eval(x)
  assert(type(res) == int, message: "should be integer")
  res
}
#safe-to-int("0xf"), #(type(safe-to-int("0xf"))) \
#safe-to-int("0o755"), #(type(safe-to-int("0o755"))) \
#safe-to-int("0b1011"), #(type(safe-to-int("0b1011"))) \
```)

注意：`assert(type(res) == int)`是必须的，否则是不安全的。

数字转字符串：<grammar-num-to-str>

#code(```typ
#repr(str(1)), #(type(str(1)))
#repr(str(.5)), #(type(str(.5)))
```)

整数转 $N$ 进制字符串：<grammar-int-to-nadec-str>

#code(```typ
#str(501, base:16), #str(0xdeadbeef, base:36)
```)

布尔值转字符串：<grammar-bool-to-str>

#code(```typ
#repr(false), #(type(repr(false)))
```)

数字转布尔值：<grammar-int-to-bool>

#code(```typ
#let to-bool(x) = x != 0
#repr(to-bool(0)), #(type(to-bool(0))) \
#repr(to-bool(1)), #(type(to-bool(1)))
```)

Typst的基本类型设计大量参考Python和Rust。Typst基本类型的特点是半纯的API设计。其基本类型的方法倾向于保持纯度，但如果影响到了使用的方便性，Typst会适当牺牲纯度。

如下所示，`array.push`就是带有副作用的：

#code(```typ
#let t = (1, 2)
#t.push(3)
#t
```)

== 布尔类型 <reference-type-bool>

Typst的布尔值是只有两个实例的类型。#ref-bookmark[`type:bool`]

#code(```
#false, #true
```)

布尔值一般用来表示逻辑的确否。

#code(```
#(1 < 2), #(1 > 2)
```)

== 整数 <reference-type-int>

Typst的整数是64位宽度的有符号整数。#ref-bookmark[`type:int`]

*有符号*整数的意思是，你可以使用正整数、负整数或零作为整数对象的内容。

#code(```typ
正数：#1；负数：#(-1)；零：#0。
```)

*64位宽度*整数的意思是，Typst允许你使用的整数是有限大的。正数、负数与整数均分$2^64$个数字。因此：
- 最大的正整数是$2^63-1$。

  #code(```typ
  #int(9223372036854775807)
  ```)
- 最小的负整数是$-2^63$。（todo: typst v0.12.0这里有一个bug）

  #code(```typ
  #int(-9223372036854775807-1)
  ```)

Typst还允许你使用其他#term("representation")表示整数。借鉴了其他编程语言，使用`0x`、`0o`和`0b`分别可以指定十六进制、八进制和二进制整数：

#code(```typ
#0xffff, #0o755, #0b101010
```)

#ref-cons-signature("int")

除了#term("literal")构造整数，#ref-bookmark[`func:int`]你还能使用构造器#typst-func("int")将其他值转换为整数。

- 将布尔值转换为$0$或$1$：
  #code(```typ
  #int(false), #int(true)
  ```)
- 将浮点数向零取整为整数：
  #code(```typ
  #int(-1.1), #int(1.1), #int(-0.1), #int(-1.9)
  ```)
- 将字符串依照十进制表示转换为整数：
  #code(```typ
  #int("42"), #int("0"), #int("-17")
  ```)

你可以使用各种操作符进行整数运算：

#code(```typ
#(1 + 2) \
#(2 - 5) \
#(3 + 4 < 8)
```)

详见#(refs.scripting-base)[《基本字面量、变量和简单函数》]中的表达式类型。

整数类型上没有任何方法，但是Typst正计划将`calc`上的方法移动到整数类型和浮点数类型上。

== 浮点数 <reference-type-float>

Typst的浮点数是64位宽度的有符号浮点数。#ref-bookmark[`type:float`]

*有符号*浮点数的意思是，你可以使用正数、负数或零作为浮点数数对象的内容。*64位宽度*浮点数的意思是，Typst允许你使用的浮点数是有限大的。正数、负数与浮点数均分$2^64$个浮点数。

Typst的浮点数遵守#link("https://standards.ieee.org/ieee/754/6210/")[IEEE-754浮点数标准]。因此：
- 最大的正数为 $f_max = 2^1023 dot (2 - 2^(-52))$。
- 最小的正数为 $f_min = 2^(-1022) dot 2^(-52)$。
- 最大的负数为 $-f_min$。
- 最小的负数为 $-f_max$。

Typst还允许你使用#term("exponential notation")表示浮点数。Typst允许你使用`{x}e{y}`格式表示$x dot 10^y$的浮点数：

#code(```typ
#1e1, #1e-1, #(-1e1), #(-1e-1), #(1.1e1)
```)

#ref-cons-signature("float")

除了#term("literal")构造浮点数，#ref-bookmark[`func:float`]你还能使用构造器#typst-func("float")将其他值转换为浮点数。

- 将布尔值转换为$0.0$或$1.0$：
  #code(```typ
  #float(false), #float(true)
  ```)
- 将整数转换成#term("nearest")的浮点数：
  #code(```typ
  #float(0), #float(-0), #float(10000000000)
  ```)
- 将百分比数字转换成#term("nearest")的浮点数：
  #code(```typ
  #float(100%), #float(1150%), #float(1%)
  ```)
- 将字符串依照十进制或#term("exponential notation")表示转换为浮点数：
  #code(```typ
  #float("42.2"), #float("0"), #float("-17"), #float("1e5")
  ```)

你可以使用各种操作符进行浮点数运算，且浮点数允许与整数混合运算：

#code(```typ
#(10 / 4) \
#(3.5 + 4.6 < 8)
```)

详见#(refs.scripting-base)[《基本字面量、变量和简单函数》]中的表达式类型。

浮点数类型上没有任何方法，但是Typst正计划将`calc`上的方法移动到整数类型和浮点数类型上。

== 字符串 <reference-type-str>

Typst的字符串是#term("utf-8 encoding")的字节序列。#ref-bookmark[`type:str`]

#link("https://en.wikipedia.org/wiki/UTF-8", "UTF-8编码")是一个广泛使用的变长编码规范。这意味着当你使用“abc123”字符串时，实际存储了这样的字节数据：

#code(```typ
#let f(x) = range(x.len()).map(
  i => x.at(i))
#f(bytes("abc123"))
```)

这意味着当你使用“ふ店”字符串时，实际存储了这样的字节数据：

#code(```typ
#let f(x) = range(x.len()).map(
  i => x.at(i))
#f(bytes("ふ店"))
```)

在绝大部分情况下，你不需要关心字符串的编码问题，因为在Typst脚本中只有#term("utf-8 encoding")的字符串。

但是这不意味着你不需要了解#term("utf-8 encoding")。Typst的字符串API与底层编码息息相关，因此你需要尽可能多地掌握与#term("utf-8 encoding")有关的知识。

在编码体系中，与Typst相关的主要有三层，它们在原始字节数据视角下的边界并不一样：

+ 字节表示：按字节寻址时，每个偏移量都索引到一个字节。
+ #term("codepoint")表示：#term("utf-8 encoding")是变长编码。在#term("utf-8 encoding")中，很多#term("codepoint")都由多个字节组成。UTF-8字符串中#term("codepoint")数据按照顺序存放，自然有些字节偏移量在#term("codepoint")寻址中不是合法的。
+ #term("grapheme cluster")表示：#term("grapheme cluster")就是人类视觉效果上的“最小字符单位”。在码位之上，Unicode规范还规定了多个码位组成一个#term("grapheme cluster")的情况。在这种情况下，自然有些码位（字节）偏移量在#term("grapheme cluster")寻址中不是合法的。

下表说明了\u{0061}\u{0303}在字节表示下的合法偏移量。

#let to-bytes-array(x) = range(x.len()).map(i => x.at(i))

#{
  set align(center)
  let i = text(red, [非法])
  table(
    columns: (50pt, 95pt, 130pt, 80pt),
    ..(
      [数据],
      ..to-bytes-array(bytes("\u{0061}\u{0303}")).map(it => [0x#str(it, base: 16)]),
      [字节],
      [第1个字节],
      [第2个字节],
      [第3个字节],
    ).map(it => align(center, it)),
    [码位],
    [英文字母a],
    [#term("tilde diacritical marks")],
    i,
    [字素簇],
    [波浪变音的英文字母a],
    i,
    i,
  )
}

#pro-tip[
  关于#term("grapheme cluster")的定义，请参考#link("https://unicode.org/reports/tr29/")[《Unicode规范：文本分段》]。
]

字符串的字面量由双引号包裹。你可以在字符串字面量中使用与字符串相关的转义序列。

#code(```typ
#"hello world!" \
#"\"hello\n  world\"!" \
```)

详见#(refs.scripting-base)[《基本字面量、变量和简单函数》]中关于字符串类型的描述。

你可以使用`in`关键字检查一个字符串是否是另一个字符串的子串：#ref-bookmark[`operator:in`\ of  `str`]

#code(```typ
#("fox" in "lazy fox"),
#(" fox" in "lazy fox"),
#("fox " in "lazy fox"),
#("dog" in "lazy fox")
```)

`in`关键字左侧值还可以是一个正则表达式类型，以检查#term("pattern")是否匹配字符串：

#code(```typ
#(regex("\d+") in "ten euros") \
#(regex("\d+") in "10 euros")
```)

`in`关键字是以#term("codepoint")为粒度检查文本的：

#code(```typ
#("\u{0303}" in "ã")
```)

#ref-cons-signature("str")

除了#term("literal")构造字符串，#ref-bookmark[`func:str`]你还能使用构造器#typst-func("str")将其他值转换为字符串。

- 将整数和浮点数转换为十进制格式字符串：
  #code(```typ
  #str(0), #str(199),
  #str(0.1), #str(9.1)
  ```)
- 将标签转换为其名称：
  #code(```typ
  #str(<owo:this-label>)
  ```)
- 将字节数组依照#term("utf-8 encoding")编码：
  #code(```typ
  #str(bytes((72, 0x69, 33)))
  ```)

特别地，你可以使用`base`参数，#ref-bookmark[`param:base`\ of `str`]将整数依照$N (2 lt.slant N lt.slant 36)$进制格式转换为字符串：

#code(```typ
#str(15, base: 16),
#str(14, base: 14),
#str(0xdeadbeef, base: 36)
```)

借鉴Python和JavaScript，Typst不提供字符类型。相应的，仅具备单个#term("codepoint")的字符串就被视作一个#term("character")。也就是说，Typst认定#term("character")与#term("codepoint")等同。这是符合主流观念的。

- “a”、“我”是字符。

- “ã”不是字符。

#glue-block[
  #ref-method-signature("str.to-unicode")

  你可以使用#typst-func("str.to-unicode")#ref-bookmark[`method:to-unicode`\ `of str`]函数获得一个字符的#term("codepoint")表示：

  #code(```typ
  #"a".to-unicode(),
  #"我".to-unicode()
  ```)

  #pro-tip[
    显然，不是所有的“字符”都可以应用`to-unicode`方法。

    #```typ
    #"ã".to-unicode() /* 不能编译 */
    ```

    这是因为视觉上为单个字符的ã是一个#term("grapheme cluster")，包含多个码位。
  ]
]

#ref-method-signature("str.from-unicode")

你可以使用#typst-func("str.from-unicode")#ref-bookmark[`method:from-unicode`\ `of str`]函数将一个数字的#term("codepoint")表示转换成字符（串）：

#code(```typ
#str.from-unicode(97),
#str.from-unicode(25105)
```)

#ref-method-signature("str.len")

你可以使用#typst-func("str.len")#ref-bookmark[`method:len`\ `of str`]函数获得一个字符串的*字节表示的长度*：

#code(```typ
#"abc".len(),
#"香風とうふ店".len(),
#"ã".len()
```)

你可能希望得到一个字符串的#term("codepoint width")，这时你可以组合以下方法：
#code(```typ
#"abc".codepoints().len(),
#"香風とうふ店".codepoints().len(),
#"ã".codepoints().len()
```)

你可能希望得到一个字符串的#term("grapheme cluster width")，这时你可以组合以下方法：
#code(```typ
#"abc".clusters().len(),
#"香風とうふ店".clusters().len(),
#"ã".clusters().len()
```)

#glue-block[
  #ref-method-signature("str.first")

  你可以使用#typst-func("str.first")#ref-bookmark[`method:first`\ `of str`]函数获得一个字符串的第一个#term("grapheme cluster")：

  #code(```typ
  #"Wee".first(),
  #"我 们 俩".first(),
  #"\u{0061}\u{0303}\u{0061}".first()
  ```)
]
#ref-method-signature("str.last")

你可以使用#typst-func("str.last")#ref-bookmark[`method:last`\ `of str`]函数获得一个字符串的最后一个#term("grapheme cluster")：

#code(```typ
#"Wee".last(),
#"我 们 俩".last(),
#"\u{0061}\u{0303}\u{0061}".last(),
#"\u{0061}\u{0061}\u{0303}".last()
```)

#ref-method-signature("str.at")

你可以使用#typst-func("str.at")#ref-bookmark[`method:at`\ `of str`]函数获得一个字符串位于*字节偏移量*为`offset`的#term("grapheme cluster")：

#code(```typ
#"我 们 俩".at(0),
#"我 们 俩".at(3),
#"我 们 俩".at(4),
#"我 们 俩".at(8)
```)

上例中，第一个空格的字节偏移量为 $3$，“俩”的字节偏移量为 $8$ 。

#ref-method-signature("str.slice")

你可以使用#typst-func("str.slice")#ref-bookmark[`method:slice`\ `of str`]函数截取字节偏移量从`start`到`end`的子串：

#code(```typ
#repr("我 们 俩".slice(0, 11)),
#repr("我 们 俩".slice(4, 8)),
```)

`end`参数可以省略：#ref-bookmark[`param:end`\ of `str.slice`]

#code(```typ
#repr("我 们 俩".slice(0)),
#repr("我 们 俩".slice(4)),
```)

#ref-method-signature("str.trim")

你可以使用#typst-func("str.trim")#ref-bookmark[`method:trim`\ `of str`]去除字符串的首尾空白字符：

#code(```typ
#repr("  A  ".trim())
```)

#typst-func("str.trim")可以指定`pattern`参数。#ref-bookmark[`param:pattern`\ of `str.trim`]

#code(```typ
#repr("wwAww".trim("w"))
```)

`pattern`可以是`none`、字符串或正则表达式。当不指定`pattern`时，Typst会指定一个模式*贪婪地*去除首尾空格。

#code(```typ
#repr("  A  ".trim()),
#repr("  A  ".trim(none)),
#repr("wwAww".trim("w")),
#repr("abAde".trim(regex("[a-z]+"))),
```)

#pro-tip[
  当`pattern`参数为`none`时，Typst直接调用Rust的`trim_start`或`trim_end`方法，以默认获得更高的性能。
]

`at`参数可以为`start`或`end`，#ref-bookmark[`param:at`\ of `str.trim`]分别指定则只清除起始位置或结束位置的字符。

#code(```typ
#repr("  A  ".trim(" ", at: start)),
#repr("  A  ".trim(" ", at: end))
```)

`repeat`参数为false时，#ref-bookmark[`param:repeat`\ of `str.trim`]不会重复运行`pattern`；否则会重复运行。默认`repeat`为`true`。

#code(```typ
#repr("  A  ".trim(" ")),
#repr("  A  ".trim(" ", repeat: false))
```)

`pattern`会在起始位置或结束位置执行至少一次。

#code(```typ
#repr("  A  ".trim(" ", at: start, repeat: false)),
#repr("abAde".trim(
  regex("[a-z]"), repeat: false)),
#repr("abAde".trim(
  regex("[a-z]+"), repeat: false))
```)

#ref-method-signature("str.split")

你可以使用#typst-func("str.split")#ref-bookmark[`method:split`\ `of str`]函数将一个字符串依照空白字符拆分：

#code(```typ
#"我 们仨".split(),
```)

#glue-block[
  #ref-method-signature("str.rev")

  你可以使用#typst-func("str.rev")#ref-bookmark[`method:rev`\ `of str`]函数将一个字符串逆转：

  #code(```typ
  #"abcdedfg".rev()
  ```)

  逆转时Typst会为你考虑#term("grapheme cluster")。

  #code(```typ
  #"ãb".rev()
  ```)
]

str.clusters, str.codepoints

str.contains, str.starts-with, str.ends-with

str.find, str.position, str.match, str.matches, str.replace

== 字典

#code(```typ
#let dict = (
  name: "Typst",
  born: 2019,
)

#dict.name \
#(dict.launch = 20)
#dict.len() \
#dict.keys() \
#dict.values() \
#dict.at("born") \
#dict.insert("city", "Berlin ")
#("name" in dict)
```)

dict.len, dict.at

dict.insert, dict.remove

dict.keys, dict.values, dict.pairs

== 数组

#code(```typ
#let values = (1, 7, 4, -3, 2)

#values.at(0) \
#(values.at(0) = 3)
#values.at(-1) \
#values.find(calc.even) \
#values.filter(calc.odd) \
#values.map(calc.abs) \
#values.rev() \
#(1, (2, 3)).flatten() \
#(("A", "B", "C")
    .join(", ", last: " and "))
```)

array.range

array.len

array.first, array.last, array.slice

array.push, array.pop, array.insert, array.remove

array.contains, array.find, array.position, array.filter

array.map, array.enumerate, array.zip, array.fold, array.sum, array.product, array.any, array.all, array.flatten, array.rev, array.split, array.join, array.intersperse, array.sorted, array.dedup


================================================
FILE: src/tutorial/reference-utils.typ
================================================
#import "mod.typ": *
#import "/typ/typst-meta/docs.typ": typst-v11
#import "@preview/cmarker:0.1.0": render as md

#show: book.page.with(title: [参考：函数表（字典序）])

#let table-lnk(name, ref, it, scope: (:), res: none, ..args) = (
  align(center + horizon, link("todo", name)),
  it,
  align(
    horizon,
    {
      set heading(bookmarked: false, outlined: false)
      eval(it.text, mode: "markup", scope: scope)
    },
  ),
)

#let table-item(c, mp, featured) = {
  let item = mp.at(c)

  (typst-func(c), item.title, ..featured(item))
}

#let table-items(mp, featured) = mp.keys().sorted().map(it => table-item(it, mp, featured)).flatten()

#let featured-func(item) = {
  return (md(item.body.content.oneliner),)
}

#let featured-scope-item(item) = {
  return (md(item.oneliner),)
}

== 分类：函数

#table(
  columns: (1fr, 1fr, 2fr),
  [函数], [名称], [描述],
  ..table-items(typst-v11.funcs, featured-func),
)

== 分类：方法

#table(
  columns: (1fr, 1fr, 2fr),
  [方法], [名称], [描述],
  ..table-items(typst-v11.scoped-items, featured-scope-item),
)

#if false [
  == `plain-text`，以及递归函数

  如果我们想要实现一个函数`plain-text`，它将一段文本转换为字符串。它便可以在树上递归遍历：

  ```typ
  #let plain-text(it) = if it.has("text") {
    it.text
  } else if it.has("children") {
    ("", ..it.children.map(plain-text)).join()
  } else if it.has("child") {
    plain-text(it.child)
  } else { ... }
  ```

  所谓递归是一种特殊的函数实现技巧：
  - 递归总有一个不调用其自身的分支，称其为递归基。这里递归基就是返回`it.text`的分支。
  - 函数体中包含它自身的函数调用。例如，`plain-text(it.child)`便再度调用了自身。

  这个函数充分利用了内容类型的特性实现了遍历。首先它使用了`has`函数检查内容的成员。

  如果一个内容有孩子，那么对其每个孩子都继续调用`plain-text`函数并组合在一起：

  ```typ
  #if it.has("children") { ("", ..it.children.map(plain-text)).join() }
  #if it.has("child") { plain-text(it.child) }
  ```

  限于篇幅，我们没有提供`plain-text`的完整实现，你可以试着在课后完成。

  == 鸭子类型

  这里值得注意的是，`it.text`具有多态行为。即便没有继承，这里通过一定动态特性，允许我们同时访问「代码片段」的`text`和「文本」的text。例如：

  #code(```typ
  #let plain-mini(it) = if it.has("text") { it.text }
  #repr(plain-mini(`代码片段中的text`)) \
  #repr(plain-mini([文本中的text]))
  ```)

  这也便是我们在「内容类型」小节所述的鸭子类型特性。如果「内容」长得像文本（鸭子），那么它就是文本。
]


================================================
FILE: src/tutorial/reference-visualization.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：图形与几何元素])

== 直线

A line from one point to another. #ref-bookmark[`line`]

#code(```typ
#line(length: 100%)
#line(end: (50%, 50%))
#line(
  length: 4cm,
  stroke: 2pt + maroon,
)
```)

== 线条样式

Defines how to draw a line. #ref-bookmark[`stroke`]

A stroke has a paint (a solid color or gradient), a thickness, a line cap, a line join, a miter limit, and a dash pattern. All of these values are optional and have sensible defaults.

#code(```typ
#set line(length: 100%)
#let rainbow = gradient.linear(
  ..color.map.rainbow)
#stack(
  spacing: 1em,
  line(stroke: 2pt + red),
  line(stroke: (paint: blue, thickness: 4pt, cap: "round")),
  line(stroke: (paint: blue, thickness: 1pt, dash: "dashed")),
  line(stroke: 2pt + rainbow),
)
```)

== 贝塞尔路径（曲线）

A path through a list of points, connected by Bezier curves. #ref-bookmark[`path`]

#code(```typ
#path(
  fill: blue.lighten(80%),
  stroke: blue,
  closed: true,
  (0pt, 50pt),
  (100%, 50pt),
  ((50%, 0pt), (40pt, 0pt)),
)
```)

== 圆形

A circle with optional content. #ref-bookmark[`circle`]

#code(```typ
// Without content.
#circle(radius: 25pt)

// With content.
#circle[
  #set align(center + horizon)
  Automatically \
  sized to fit.
]
```)

== 椭圆

An ellipse with optional content. #ref-bookmark[`ellipse`]

#code(```typ
// Without content.
#ellipse(width: 35%, height: 30pt)

// With content.
#ellipse[
  #set align(center)
  Automatically sized \
  to fit the content.
]
```)

== 正方形

A square with optional content. #ref-bookmark[`square`]

#code(```typ
// Without content.
#square(size: 40pt)

// With content.
#square[
  Automatically \
  sized to fit.
]
```)

== 矩形

A rectangle with optional content. #ref-bookmark[`rect`]

#code(```typ
// Without content.
#rect(width: 35%, height: 30pt)

// With content.
#rect[
  Automatically sized \
  to fit the content.
]
```)

== 多边形

A closed polygon. #ref-bookmark[`ellipse`]

The polygon is defined by its corner points and is closed automatically.

#code(```typ
#polygon(
  fill: blue.lighten(80%),
  stroke: blue,
  (20%, 0pt),
  (60%, 0pt),
  (80%, 2cm),
  (0%,  2cm),
)
```)

== 图形库

+ typst-fletcher
+ typst-syntree
+ cetz


================================================
FILE: src/tutorial/reference-wasm-plugin.typ
================================================
#import "mod.typ": *

#show: book.ref-page.with(title: [参考：WASM插件])


================================================
FILE: src/tutorial/scripting-block-and-expression.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "表达式")

Typst中绝大部分语法结构都可作表达式，可以说学习完了所有表达式，则学会了Typst所有语法。当然，其吸取了一定历史经验，仅有少量的语句不是表达式。

#pro-tip[
  Typst借鉴了Rust，遵从「面向表达式编程」（expression-oriented programming）的哲学。它将所有的语句都根据可折叠规则（见后文）设计为表达式。
  + 如果一个语句能产生值，那么该语句的结果是按*控制流*顺序所产生所有值的折叠。
  + 否则，如果一个语句不能产生值，那么该语句的结果是```typc none```。
  + 特别地，任意类型 $T$ 的值 $v$ 与```typc none```折叠仍然是值本身。
]

#pro-tip[
  `show`语句和`set`语句不是表达式。
]

根据大的分类，可用的表达式可以分为5类（它们并非严格术语，而是为了方便教学而分类），他们是：
+ 代数运算表达式。
+ 逻辑比较表达式。
+ 逻辑运算表达式。
+ 赋值表达式。
+ 项。

== 代数运算表达式 <grammar-arith-exp>

Typst支持对数字的算数运算，其中浮点运算遵守IEEE-754标准。整数和浮点数之间可以混合运算：

#code(```typ
//加     减        乘      除
#(1 + 2, 1.0 - 2, 1 * 2, 1 / 2 + 1)
```)

从上可以看出，整数和整数运算尽可能*保持*整数，但是整数和浮点数运算则结果变为浮点数。除法运算的结果是浮点数。算数之间遵守四则运算规则。

#pro-tip[
  更高级的运算，例如数字的位运算和数值计算隐藏在类型的方法和`calc`标准库中：

  #code(```typ
  #(0o755.bit-and(0o644)), // 8进制位运算
  #(calc.pow(9, 4)) // 9的4次方
  ```)

  请参考《》。
]

除了数字运算，字符串、数组等还支持加法和乘法运算。它们的加法实际上是连接操作，它们的乘法则是重复元素的累加。

#code(```typ
//乘         加
#("1"  * 2, "4"  + "5", ) \
#((1,) * 2, (4,) + (5,),)
```)

字典只支持加法操作。若有重复键值对，则右侧列表的键值对会覆盖左侧列表的键值对。

#code(```typ
#((a: 1) + (b: 2),
  (a: 1) + (b: 3, a: 2) + (a: 4 , c: 5))
```)


== 浮点数陷阱

浮点数陷阱是指由于浮点转换或浮点精度问题导致的一系列逻辑问题。

// todo: 把基本字面量的运算和表达式挪过来

+ 类型比较陷阱。在运行期切记同时考虑到`float`和`int`两种类型：

  #code(```typ
  #type(2), #type(2.), #(type(2.) == int)
  ```)

  可见```typc 2.```与```typc 2```类型并不相同。```typc 2.```在数学上是整数，但以浮点数存储。

+ 大数类型陷阱。当数字过大时，其会被隐式转换为浮点数存储：

  #code(```typ
  #type(9000000000000000000000000000000)
  ```)

+ 整数运算陷阱。整数相除时会被转换为浮点数：

  #code(```typ
  #(10 / 4), #type(10 / 4) \
  #(12 / 4), #type(12 / 4) \
  ```)

+ 浮点误差陷阱。哪怕你的运算在数学上理论是可逆的，由于浮点数精度有限，也会误判结果：

  #code(```typ
  #(1000000 / 9e21 * 9e21), #((1000000 / 9e21 * 9e21) == 1000000)
  ```)

  这提示我们，正确的浮点比较需要考虑误差。例如以上两数在允许`1e-6`误差前提下是相等的：

  #code(```typ
  #(calc.abs((1000000 / 9e21 * 9e21) - 1000000) < 1e-6)
  ```)

+ 整数转换陷阱。为了转换类型，可以使用`int`，但有可能产生精度损失（就近取整）：

  #code(```typ
  #int(10 / 4),
  #int(12 / 4)
  ```)

  或有可能产生「截断」。（todo: typst v0.12.0已经不适用）

// #code(```typ
// #int(9000000000000000000000000000000)
// ```)

这些都是编程语言中的共通问题。凡是令数字保持有效精度，都会产生如上问题。

== 逻辑比较表达式 <grammar-logical-cmp-exp>

有三大简单比较关系：

#code(```typ
//大于    小于   等于
#(1 > 2, 1 < 2, 1 == 2)
```)

基于此，可以延申出三个方便脚本编辑的比较关系。

#code(```typ
//大于或等于 小于或等于 不等于
#(1 >= 2.0, 1 <= 1,  1 != 2)
```)

从数学角度，真正基本的关系另有其系，其中“小于或等于”是数学中的偏序关系，“等于”是数学中的等价关系。这两个关系可以衍生出其他四种关系，但是不太好理解。举例来讲，大于其实就是“小于等于”的否定；而小于则是“小于等于”但是不能“等于”。

注意：不推荐将整数与浮点数相互比较。具体请参考上一节所提及的浮点数陷阱。

字符串、数组和字典之间也是可以比较的，理解他们则必须从偏序关系和等价关系入手。

三种项的等价关系比较容易理解，说两字符串/数组/字典相等，则是在说二者有一样多的子项，且每个子项都一一相等。

#code(```typ
#((1, 1) == (1, 1)),
#((a: 1, c: (1, )) == (a: 1, c: (1, )))
```)

字典之间没有偏序关系，便只剩字符串和数组。偏序关系则需要指定一种排序规则。如果两字符串/数组不相等，则首先考虑它们的长度关系，长度小的一方是更小的：

#code(```typ
#("1"   <= "23"),
#((1, ) <= (2, 3, ))
```)

否则从前往后依次比较每一个子项，直到找到*第一个*不相等的子项，进而确定顺序。见下三例：

#code(```typ
#("1" <= "2", "113" <= "121", "2" <= "12")
```)

对于单个字符，我们依照字典序比较，其中容易理解地是数字字符顺序按字面递增。对于前两者，我们可以看到`"1"`比`"2"`小；进由此，故"113"比"121"小；尽管如此，优先判断长度关系，故"2"比"12"小。

从两种基础比较关系，其他四种比较关系也能被良好地定义，并在脚本中使用：

#code(```typ
#("1" > "2", "1" != "2",
  "1" < "2", "1" >= "2")
```)

== 逻辑运算表达式 <grammar-logical-calc-exp>

布尔值之间可以做“且”、“或”和“非”三种逻辑运算，并产生布尔类型的表达式：

#code(```typ
#(not false), #(false or false), #(true and false)
```)

真值表如下：

#{
  set align(center)
  table(
    columns: (33pt * 0.6,) * 2 + (33pt,) * 3,
    stroke: 0.5pt,
    $p$, $q$, $not p$, $p or q$, $p and q$,
    $0$, $0$, $1$, $0$, $0$,
    $0$, $1$, $1$, $1$, $0$,
    $1$, $0$, $0$, $1$, $0$,
    $1$, $1$, $0$, $1$, $1$,
  )
}

逻辑运算使用起来很简单，建议入门的同学找一些专题阅读，例如#link("https://zhuanlan.zhihu.com/p/82986019")[数理逻辑（1）——命题逻辑的基本概念]。但一旦涉及到对复杂事物的逻辑讨论，你就可能陷入了知识的海洋。关于逻辑运算已经形成一门学科，如有兴趣建议后续找一些书籍阅读，例如#link("https://www.xuetangx.com/course/THU12011001060/19316572")[逻辑学概论]。

本书自然不负责教你逻辑学。

== 赋值表达式 <grammar-assign-exp>

变量可以被赋予一个表达式的值。事实上，`let`表达式后的语法结构就是赋值表达式。

#code(```typ
#let a = 1; #a,
#(a = 10); #a
```)

除此之外，还有先加（减、乘或除）后赋值的变形。所有这些赋值语句都产生`none`值而非返回变量的值。

#code(```typ
#let a = 1; #a,
#repr(a += 2), #a, #repr(a -= 2), #a, #repr(a *= 2), #a, #repr(a /= 2), #a
```)

== 代码块 <grammar-code-block>

除了字面量，由于「面向表达式编程」，「代码块」也可以作为表达式的「项」。在Typst中，代码块和内容块是等同的。将「内容块」与「代码块」作比较：

- 代码块：按顺序包含一系列语句，内部为#term("code mode")。
- 内容块：按顺序包含一系列内容，内部为#term("markup mode")。

内容块（标记模式）内部没有语句的概念，一个个内容或元素按顺序排列。相比，代码块内部则有语句概念。每个语句可以是换行分隔，也可以是#mark(";")分隔。

#code(```typ
#{
  "a"
  "b"
} \ // 与下表达式等同：
#{ "a"; "b" }
```)

#pro-tip[
  公式块只是一种特殊的内容块，只不过其内容处于「数学模式」。对比：
  #code(```typ
  文本优先：#[ab] v.s. $#[a]#[b]$ \
  数学优先：#[$lambda$$(x)$] v.s. $lambda(x)$
  ```)
]

「代码块」和值（表达式）的关系与「控制流」息息相关。我们将会在下一节（todo：添加链接）详细介绍「控制流」。

// 整数转浮点数：<grammar-int-to-float>

// #code(```typ
// #float(1), #(type(float(1)))
// ```)

// 布尔值转整数：<grammar-bool-to-int>

// #code(```typ
// #int(false), #(type(int(false))) \
// #int(true), #(type(int(true)))
// ```)

// 浮点数转整数：<grammar-float-to-int>

// #code(```typ
// #int(1), #(type(int(1)))
// ```)

// 数字转字符串：<grammar-num-to-str>

// #code(```typ
// #repr(str(1)), #(type(str(1)))
// #repr(str(.5)), #(type(str(.5)))
// ```)

// 布尔值转字符串：<grammar-bool-to-str>

// #code(```typ
// #repr(false), #(type(repr(false)))
// ```)

// 数字转布尔值：<grammar-int-to-bool>

// #code(```typ
// #let to-bool(x) = x != 0
// #repr(to-bool(0)), #(type(to-bool(0))) \
// #repr(to-bool(1)), #(type(to-bool(1)))
// ```)

// 表达式从感性地理解上就是检验执行一段代码是否对应产生一个值。精确来说，表达式是以下对象的集合：
// + 前述的各种「字面量」是表达式：
//   #code(```typ
//   // 这些是表达式
//   #none, #true, #1, #.2, #"s"
//   ```)
// + 「变量」是表达式：
//   #code(```typ
//   #let a = 1;
//   // 这是表达式
//   #a
//   ```)
// + 「括号表达式」（parenthesized expression）是表达式：
//   #code(```typ
//   // 这些是表达式
//   #(0), #(1+2), #((((((((1))))))))
//   ```)
// + 「函数调用」是表达式：
//   #code(```typ
//   #let add(a, b) = a + b
//   #let a = 1;
//   // 这是表达式
//   #add(a, 2)
//   ```)
// + 特别地，Typst中的「代码块」和「内容块」是表达式：
//   #code(```typ
//   // 这些是表达式
//   #repr({ 1 }), #repr([ 1 ]),
//   ```)
// + 特别地，Typst中的「if语句」、「for语句」和「while语句」等都是表达式：
//   #code(```typ
//   // 这些是表达式
//   #repr(if false [啊？]),
//   #repr(for _ in range(0) {}),
//   #repr(while false {}),
//   #repr(let _ = 1),
//   ```)
//   这些将在后文中介绍。
// + 情形1至情形7的所有对象作为项，任意项之间的「运算」也是表达式。

// 其中，情形1至情形3被称为「初始表达式」（primary expression），它们就像是表达式的种子，由其他操作继续组合生成更多表达式。

// 情形4至情形6本身都是经典意义上的「语句」（statement），它们由一个或多个子表达式组成，形成一个有新含义的表达式。在Typst中它们都被赋予了「值」的语义，因此它们也都是表达式。我们将会在后续文章中继续学习。

// 本节主要讲解情形7。由于情形1至情形6都可以作为情形7的项，不失一般性，我们仍然可以仅以「字面量」作为项讲解所有情形7的情况。


================================================
FILE: src/tutorial/scripting-color.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "颜色类型")


================================================
FILE: src/tutorial/scripting-composite.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "复合类型")

学会了数组和字典，我们就解锁了各种新技能。

== 数组字面量 <grammar-array-literal>

脚本模式中有两类核心复合字面量。一曰「数组」，一曰「字典」。

「数组」是按照顺序存储的一些「值」，你可以在「数组」中存放*任意内容*而不拘泥于类型。你可以使用圆括号与一个逗号分隔的列表创建一个*数组字面量*：

#code(```typ
#(1, "OvO", [一段内容])
```)

== 字典字面量 <grammar-dict-literal>

所谓「字典」即是「键值对」的集合，其每一项是由冒号分隔的「键值对」。如下例所示，冒号左侧，“neco-mimi”等「标识符」或「字符串」是字典的「键」，而冒号右侧分别是对应的「值」。

#code(```typ
#(neko-mimi: 2, "utterance": "喵喵喵")
```)

== 数组和字典的典型构造

特别讲解一些关于数组与字典相关的典型构造：

#code(```typ
#() \ // 是空的数组
#(:) \ // 是空的字典
#(1) \ // 被括号包裹的整数1
#(()) \ // 被括号包裹的空数组
#((())) \ // 被括号包裹的被括号包裹的空数组
#(1,) \ // 是含有一个元素的数组
```)

`()`是空的数组<grammar-empty-array>，不含任何值。`(:)`是空的字典<grammar-empty-dict>，不含任何键值对。

如果括号内含了一个值，例如`(1)`，那么它仅仅是被括号包裹的整数1，仍然是整数1本身。

类似的，`(())`是被括号包裹的空数组<grammar-paren-empty-array>，`((()))`是被括号包裹的被括号包裹的空数组。

为了构建含有一个元素的数组，需要在列表末尾额外放置一个逗号以示区分，例如`(1,)`。<grammar-single-member-array>

// https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Trailing_commas
这种逗号被称为尾后逗号。

// todo: 改进
构造数组字面量时，允许尾随一个多余的逗号而不造成影响。

#code(```typ
#let x = (1, "OvO", [一段内容] , ); #x
//          这里有一个多余的逗号^^^
```)

构造字典字面量时，允许尾随一个多余的逗号。

#code(```typ
#let cat = (attribute: [kawaii\~], ); #cat
//             这里有一个尾随的小逗号^^
```)

== 数组和字典的「解构赋值」

这是本节最难的内容，非程序员朋友想要灵活运用可能有点困难。

除了使用字面量「构造」元素，Typst还支持「构造」的反向操作：「解构赋值」。顾名思义，你可以在左侧用相似的语法从数组<grammar-destruct-array>或字典中获取值并赋值到*对应*的变量上。<grammar-destruct-dict>

#code(```typ
#let (attr: a) = (attr: [kawaii\~])
#a
```)

「解构赋值」必须一一对应，但你也可以使用「占位符」（`_`）或「延展符」（`..`）以作*部分*解构：<grammar-destruct-array-eliminate>

#code(```typ
#let (first, ..) = (1, 2, 3)
#let (.., second-last, _) = (7, 8, 9, 10)
#first, #second-last
```)

数组的「解构赋值」有一个妙用，那就是重映射内容。<grammar-array-remapping>

#code(```typ
#let (a, b, c) = (1, 2, 3)
#let (b, c, a) = (a, b, c); #a, #b, #c
```)

特别地，如果两个变量相互重映射，这种操作被称为「交换」：<grammar-array-swap>

#code(```typ
#let (a, b) = (1, 2)
#((a, b) = (b, a)); #a, #b
```)

== 数组和字典的成员访问

为了访问数组，你可以使用`at`方法。“at”在中文里是“在”的意思，它表示对「数组」使用「索引」操作。`at(0)`索引到第1个值，`at(n)`索引到第 $n + 1$ 个值，以此类推。如下所示：

#code(```typ
#let x = (1, "OvO", [一段内容])
#x.at(0), #x.at(1), #x.at(2)
```)

至于「索引」从零开始的原因，这只是约定俗成。等你习惯了，你也会变成计数从零开始的好程序员。

为了访问字典，你可以使用`at`方法。但由于「键」都是字符串，你需要使用字符串作为字典的「索引」。

#code(```typ
#let cat = (attribute: [kawaii\~])
#cat.at("attribute")
```)

为了方便，Typst允许你直接通过成员方法访问字典对应「键」的值： <grammar-dict-member-exp>

#code(```typ
#let cat = ("attribute": [kawaii\~])
#cat.attribute
```)

== 数组和字典的「存在谓词」

为了访问数组，你可以使用`contains`方法。“contain”在中文里是“包含”的意思，如下所示：

#code(```typ
#let x = (1, "OvO", [一段内容])
#x.contains[一段内容]
```)

因为这太常用了，typst专门提供了`in`语法，表示判断`x`是否*存在于*某个数组中：<grammar-array-in>

#code(```typ
#([一段内容] in (1, "OvO", [一段内容])) \
#([另一段内容] in (1, "OvO", [一段内容]))
```)

字典也可以使用此语法，表示判断`x`是否是字典的一个「键」。特别地，你还可以前置一个`not`判断`x`是否*不在*某个数组或字典中：<grammar-dict-in>

#code(```typ
#let cat = (neko-mimi: 2)
#("neko-kiki" not in cat)
```)

注意：`x in (...)`与`"x" in (...)`是不同的。例如`neko-mimi in cat`将检查`neko-mimi`变量的内容是否是字典变量`cat`的一个「键」，而`"neko-mimi"`检查对应字符串是否在其中。

// field access
// - dictionary
// - symbol
// - module
// - content

== 位置参数声明 <grammar-positional-param>

typst通过数组和字典在执行时向函数传递参数。上一节我们学会了基本的函数声明，若进一步理解了数组和字典，可以定义更复杂的函数。接下来我们讲透Typst中如何声明复杂函数，以及如何调用函数。

其中最简单的是位置参数声明，我们在上节已经学过。

#code(```typ
#let f(a, b) = [两个值#(a)和#(b)偷偷混入了我们内容之中。]
#f(1, 2)
```)

在函数调用的时候，位置参数必须按照声明的顺序传递。例子中，向`f`函数传递了两个位置参数`1`和`2`，于是`a`和`b`作为变量被赋值为了`1`和`2`，接着这个函数返回一个「内容块」，其中用到了`a`和`b`变量。

== 具名参数声明 <grammar-named-param>

函数可以包含「具名参数」，其看起来就像字典的一项，冒号右侧则是参数的*默认值*：

#code(```typ
#let g(name: "？") = [你是#name]
#g(/* 不传就是问号 */); #g(name: "OwO。")
```)

== 变长参数 <grammar-variadic-param>

函数可以包含「变长参数」。

#code(```typ
#let g(..args) = [很多个值，#args.pos().join([、])，偷偷混入了我们内容之中。]
#g([一个俩个], [仨个四个], [五六七八个])
```)

```typc args```的类型是`arguments`。
+ 使用`args.pos()`得到传入的位置参数数组；使用`args.named()`得到传入的具名参数字典。
+ 使用`args.at(i)`访问索引为整数`i`的位置参数；使用`args.at(name)`访问名称为字符串`name`的具名参数。

== 参数类型 <grammar-param-literal>

什么是「参数类型」（argument type）？在typst中，你完全可以先把函数参数准备好，然后直接调用函数：

#code(```typ
#let sum(..args, init: 0) = init + args.pos().sum()
#let args = arguments(1, 2)
#sum(..args) // 3
```)

`arguments`是一个类型，`arguments(1, 2)`是一个表达式，它返回一个`arguments`类型的值。

也可以预先传递参数，然后直接调用函数：

#code(```typ
#let sum(..args, init: 0) = init + args.pos().sum()
#let args = arguments((1,), (2,), init: ())
#sum(..args) // (1, 2)
```)

=== 参数解构 <grammar-destructing-param>

#todo-box[写完]
todo参数解构。

#todo-box[引言]


================================================
FILE: src/tutorial/scripting-content.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "文档树")

#todo-box[本节处于校对阶段，所以可能存在不完整或错误。]

== 「可折叠」的值（Foldable）

先来看代码块。代码块其实就是一个脚本。既然是脚本，Typst就可以按照语句顺序依次执行「语句」。

#pro-tip[
  准确地来说，按照控制流顺序。
]

Typst按控制流顺序执行代码，将所有结果*折叠*成一个值。所谓折叠，就是将所有数值“连接”在一起。这样讲还是太抽象了，来看一些具体的例子。

=== 字符串折叠

Typst实际上不限制代码块的每个语句将会产生什么结果，只要是结果之间可以*折叠*即可。

我们说字符串是可以折叠的：

#code(```typ
#{"Hello"; " "; "World"}
```)

实际上折叠操作基本就是#mark("+")操作。那么字符串的折叠就是在做字符串连接操作：

#code(```typ
#("Hello" + " " + "World")
```)

再看一个例子：

#code(```typ
#{
  let hello = "Hello";
  let space = " ";
  let world = "World";
  hello; space; world;
  let destroy = ", Destroy"
  destroy; space; world; "."
}
```)

如何理解将「变量声明」与表达式混写？

回忆前文。对了，「变量声明」表达式的结果为```typc none```。
#code(```typ
#type(let hello = "Hello")
```)

并且还有一个重点是，字符串与`none`相加是字符串本身，`none`加`none`还是`none`：

#code(```typ
#("Hello" + none), #(none + "Hello"), #repr(none + none)
```)

现在可以重新体会这句话了：Typst按控制流顺序执行代码，将所有结果*折叠*成一个值。对于上例，每句话的执行结果分别是：

```typc
#{
  none; // let hello = "Hello";
  none; // let space = " ";
  none; // let world = "World";
  "Hello"; " "; "World"; // hello; space; world;
  none; // let destroy = ", Destroy"
  ", Destroy"; " "; "World"; "." // destroy; space; world; "."
}
```

将结果收集并“折叠”，得到结果：

#code(```typc
#(none + none + none + "Hello" + " " + "World" + none + ", Destroy" + " " + "World" + ".")
```)

#pro-tip[
  还有其他可以折叠的值，例如，数组与字典也是可以折叠的：

  #code(```typ
  #for i in range(1, 5) { (i, i * 10) }
  ```)

  #code(```typ
  #for i in range(1, 5) { let d = (:); d.insert(str(i), i * 10); d }
  ```)
]

=== 其他基本类型的情况

那么为什么说折叠操作基本就是#mark("+")操作。那么就是说有的“#mark("+")操作”并非是折叠操作。

布尔值、整数和浮点数都不能相互折叠：

```typ
// 不能编译
#{ false; true }; #{ 1; 2 }; #{ 1.; 2. }
```

那么是否说布尔值、整数和浮点数都不能折叠呢。答案又是否认的，它们都可以与```typc none```折叠（把下面的加号看成折叠操作）：

#code(```typ
#(1 + none)
```)

所以你可以保证一个代码块中只有一个「语句」产生布尔值、整数或浮点数结果，这样的代码块就又是能编译的了。让我们利用`let _ = `来实现这一点：

#code(```typ
#{ let _ = 1; true },
#{ let _ = false; 2. }
```)

回忆之前所讲的特殊规则：#term("placeholder")用作标识符的作用是“忽略不必要的语句结果”。

=== 内容折叠

Typst脚本的核心重点就在本段。

内容也可以作为代码块的语句结果，这时候内容块的结果是每个语句内容的“折叠”。

#code(```typ
#{
  [= 生活在Content树上]
  [现代社会以海德格尔的一句“一切实践传统都已经瓦解完了”为嚆矢。]
  [滥觞于家庭与社会传统的期望正失去它们的借鉴意义。]
  [但面对看似无垠的未来天空，我想循卡尔维诺“树上的男爵”的生活好过过早地振翮。]
}
```)

是不是感觉很熟悉？实际上内容块就是上述代码块的“糖”。所谓糖就是同一事物更方便书写的语法。上述代码块与下述内容块等价：

```typ
#[
  = 生活在Content树上
  现代社会以海德格尔的一句“一切实践传统都已经瓦解完了”为嚆矢。滥觞于家庭与社会传统的期望正失去它们的借鉴意义。但面对看似无垠的未来天空，我想循卡尔维诺“树上的男爵”的生活好过过早地振翮。
]
```

由于Typst默认以「标记模式」开始解释你的文档，这又与省略`#[]`的写法等价：

```typ
= 生活在Content树上
现代社会以海德格尔的一句“一切实践传统都已经瓦解完了”为嚆矢。滥觞于家庭与社会传统的期望正失去它们的借鉴意义。但面对看似无垠的未来天空，我想循卡尔维诺“树上的男爵”的生活好过过早地振翮。
```

#pro-tip[
  实际上有区别，由于多两个换行和缩进，前后各多一个Space Element。
]

// == Hello World程序

// 有的时候，我们想要访问字面量、变量与函数中存储的“信息”。例如，给定一个字符串```typc "Hello World"```，我们想要截取其中的第二个单词。

// 单词`World`就在那里，但仅凭我们有限的脚本知识，却没有方法得到它。这是因为字符串本身是一个整体，虽然它具备单词信息，我们却缺乏了*访问*信息的方法。

// Typst为我们提供了「成员」和「方法」两种概念访问这些信息。使用「方法」，可以使用以下脚本完成目标：

// #code(```typ
// #"Hello World".split(" ").at(1)
// ```)

// 为了方便讲解，我们改写出6行脚本。除了第二行，每一行都输出一段内容：

// #code(```typ
// #let x = "Hello World"; #x \
// #let split = str.split
// #split(x, " ") \
// #str.split(x, " ") \
// #x.split(" ") \
// #x.split(" ").at(1)
// ```)

// 从```typ #x.split(" ").at(1)```的输出可以看出，这一行帮助我们实现了“截取其中的第二个单词”的目标。我们虽然隐隐约约能揣测出其中的意思：

// ```typ
// #(       x .split(" ")           .at(1)          )
// // 将字符串 根据字符串拆分  取出其中的第2个单词（字符串）
// ```

// 但至少我们对#mark(".")仍是一无所知。

// 本节我们就来讲解Typst中较为高级的脚本语法。这些脚本语法与大部分编程语言的语法相同，但是我们假设你并不知道这些语法。

== 「内容」是一棵树（Cont.）

#pro-tip[
  利用「内容」与「树」的特性，我们可以在Typst中设计出更多优雅的脚本功能。
]

=== CeTZ的「树」

CeTZ利用内容树制作“内嵌的DSL”。CeTZ的`canvas`函数接收的不完全是内容，而是内容与其IR的混合。

例如它的`line`函数的返回值，就完全不是一个内容，而是一个无法窥视的函数。

#code(```typ
#import "@preview/cetz:0.3.4"
#repr(cetz.draw.line((0, 0), (1, 1), fill: blue))
```)

当你产生一个“混合”的内容并将其传递给`cetz.canvas`，CeTZ就会像`plain-text`一样遍历你的混合内容，并加以区分和处理。如果遇到了他自己特定的IR，例如`cetz.draw.line`，便将其以特殊的方式转换为真正的「内容」。

使用混合语言，在Typst中可以很优雅地画多面体：

#code.with(al: top)(```typ
#import "@preview/cetz:0.3.4"
#align(center, cetz.canvas({
  // 导入cetz的draw方言
  import cetz.draw: *; import cetz.vector: add
  let neg(u) = if u == 0 { 1 } else { -1 }
  for (p, c) in (
    ((0, 0, 0), black), ((1, 1, 0), red), ((1, 0, 1), blue), ((0, 1, 1), green),
  ) {
    line(add(p, (0, 0, neg(p.at(2)))), p, stroke: c)
    line(add(p, (0, neg(p.at(1)), 0)), p, stroke: c)
    line(add(p, (neg(p.at(0)), 0, 0)), p, stroke: c)
  }
}))
```)

=== curryst的「树」

我们知道「内容块」与「代码块」没有什么本质区别。

如果我们可以基于「代码块」描述一棵「内容」的树，那么逻辑推理的过程也可以被描述为条件、规则、结论的树。

#link("https://typst.app/universe/package/curryst/")[curryst]包提供了接收条件、规则、结论参数的`rule`函数，其返回一个包含传入信息的`dict`，并且允许把`rule`函数返回的`dict`作为`rule`的部分参数。于是我们可以通过嵌套`rule`函数建立描述推理过程的树，并通过该包提供的`prooftree`函数把包含推理过程的`dict`树画出来：

#code(```typ
#import "@preview/curryst:0.5.0": rule, prooftree
#let tree-dict = rule(
  name: $R$,
  $C_1 or C_2 or C_3$,
  rule(
    name: $A$,
    $C_1 or C_2 or L$,
    rule(
      $C_1 or L$,
      $Pi_1$,
    ),
  ),
  rule(
    $C_2 or overline(L)$,
    $Pi_2$,
  ),
)
`tree-dict`的类型：#type(tree-dict) \
`tree-dict`代表的树：#prooftree(tree-dict)
```)

== 内容类型 <content-type-feature>

我们已经学过很多元素：段落、标题、代码片段等。这些元素在被创建后都会被包装成为一种被称为「内容」的值。这些值所具有的类型便被称为「内容类型」。同时「内容类型」提供了一组公共方法访问元素本身。

乍一听，内容就像是一个“容器”将元素包裹。但内容又不太像是之前所学过的数组或字典那样的复合字面量，或者说这样不方便理解。事实上，每个元素都有各自的特点，但仅仅为了保持动态性，所有的元素都被硬凑在一起，共享一种类型。有两种理解这种类型的视角：从表象论，「内容类型」是一种鸭子类型；从原理论，「内容类型」提供了操控内容的公共方法，即它是一种接口，或称特征（Trait）。

=== 特性一：元素包装于「内容」

我们知道所有的元素语法都可以等价使用相应的函数构造。例如标题：

#code(```typ
#repr([= 123]) \ // 语法构造
#repr(heading(depth: 1)[123]) // 函数构造

```)

一个常见的误区是误认为元素继承自「内容类型」，进而使用以下方法判断一个内容是否为标题元素：

#code(```typ
标题是heading类型（伪）？#(type([= 123]) == heading)
```)

但两者类型并不一样。事实上，元素是「函数类型」，元素函数的返回值为「内容类型」。

#code(```typ
标题函数的类型：#(type(heading)) \
标题的类型：#type([= 123])
```)

这引出了一个重要的理念，Typst中一切皆组合。Typst中目前没有继承概念，一切功能都是组合出来的，这类似于Rust语言的概念。你可能没有学过Rust语言，但这里有一个冷知识：

#align(center, [Typst $<=>$ Typ(setting Ru)st $<=>$ Typesetting Rust])

即Typst是以Rust语言特性为基础设计出的一个排版（Typesetting）语言。

当各式各样的元素函数接受参数时，它们会构造出「元素」，然后将元素包装成一个共同的类型：「内容类型」。`heading`是函数而不是类型。与其他语言不同，没有一个`heading`类型继承`content`。因此不能使用`type([= 123]) == heading`判断一个内容是否为标题元素。

=== 特性二：内容类型的`func`方法

所有内容都允许使用`func`得到构造这个内容所使用的函数。因此，可以使用以下方法判断一个内容是否为标题元素：

#code(```typ
标题所使用的构造函数：#([= 123]).func()

标题的构造函数是`heading`？#(([= 123]).func() == heading)
```)

// 这一段不要了
// === 特性二点五：内容类型的`func`方法可以直接拿来用

// `func`方法返回的就是函数本身，自然也可以拿来使用：

// #code(```typ
// 重新构造标题：#(([= 123]).func())([456])
// ```)

// 这一般没什么用，但是有的时候可以用于得到一些Typst没有暴露出来的内容函数，例如`styled`。

// #code(```typ
// #let type_styled = text(fill: red, "").func()
// #let st = text(fill: blue, "").styles
// #text([abc], st)
// ```)

=== 特性三：内容类型的`fields`方法

Typst中一切皆组合，它将所有内容打包成「内容类型」的值以完成类型上的统一，而非类型继承。

但是这也有坏处，坏处是无法“透明”访问内部内容。例如，我们可能希望知道`heading`的级别。如果不提供任何方法访问标题的级别，那么我们就无法编程完成与之相关的排版。

为了解决这个问题，Typst提供一个`fields`方法提供一个content的部分信息：

#code(```typ
#([= 123]).fields()
```)

`fields()`将部分信息组成字典并返回。如上图所示，我们可以通过这个字典对象进一步访问标题的内容和级别。

#code(```typ
#([= 123]).fields().at("depth")
```)

#pro-tip[
  这里的“部分信息”描述稍显模糊。具体来说，Typst只允许你直接访问元素中不受样式影响的信息，至少包含语法属性，而不允许你*直接*访问元素的样式。

  // 如下：

  // #code.with(al: top)(````typ
  // #let x = [= 123]
  // #rect([#x <the-heading>])
  // #x.fields() \
  // #locate(loc => query(<the-heading>, loc))
  // ````)
]

=== 特性四：内容类型与`fields`相关的糖 <grammar-content-member-exp>

由于我们经常需要与`fields`交互，Typst提供了`has`方法帮助我们判断一个内容的`fields`是否有相关的「键」。

#code(```typ
使用`... in x.fields()`判断：#("text" in `x`.fields()) \
等同于使用`has`方法判断：#(`x`.has("text"))
```)

Typst提供了`at`方法帮助我们访问一个内容的`fields`中键对应的值。

#code(```typ
使用`x.fields().at()`获取值：#(`www`.fields().at("text")) \
等同于使用`at`方法：#(`www`.at("text"))
```)

特别地，内容的成员包含`fields`的键，我们可以直接通过成员访问相关信息：

#code(```typ
使用`at`方法：#(`www`.at("text")) \
等同于访问`text`成员：#(`www`.text)
```)


================================================
FILE: src/tutorial/scripting-control-flow.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "控制流")

== `none`类型和`if`语句 <grammar-if>

默认情况下，在逻辑上，Typst按照顺序执行执行你的代码，即先执行前面的语句，再执行后面的语句。开发者如果想要控制程序执行的流程，就必须使用流程控制的语法结构，主要是条件执行和循环执行。

`if`语句用于条件判断，满足条件时，就执行指定的语句。

```typ
#if expression { then-block } else { else-block }
#if expression { then-block }
```

上面式子中，表达式`expression`为真（值为布尔值`true`）时，就执行`then-block`代码块，否则执行`else-block`代码块。特别地，`else`可以省略。

如下所示：

#code(```typ
#if (1 < 2) { "确实" } else { "啊？" }
```)

因为`1 < 2`表达式为真，所以脚本仅执行了`then-block`代码块，于是最后文档的内容为“确实”。

`if`语句还可以无限串联下去，你可以自行类比推理更长的`if`语句的语义：<grammar-if-if>

```typ
#if expression { .. } else if expression { .. } else { .. }
#if expression { .. } else if expression { .. }
#if expression { .. } else if expression { .. } else if ..
```
如果只写了`then`代码块，而没写`else`代码块，但偏偏表达式不为真，最终脚本会报错吗？请看：

#code(```typ
#repr(if (1 > 2) { "啊？" })
```)

当`if`表达式没写`else`代码块而条件为假时，结果为`none`。“none”在中文里意思是“无”，表示“什么都没有”。同时再次强调`none`在「可折叠」的值中很重要的一个性质：`none`在折叠过程中被忽略。

见下程序，其根据数组所包含的值输出特定字符串：

#code(```typ
#let 查成分(成分数组) = {
  "是个"
  if "A" in 成分数组 or "C" in 成分数组 or "G" in 成分数组 { "萌萌" }
  if "T" in 成分数组 { "工具" }
  "人"
}

#查成分(()) \
#查成分(("A","T",)) \
```)

由于`if`也是表达式，你可以直接将`if`作为函数体，例如fibnacci函数的递归可以非常简单：

#code(```typ
#let fib(n) = if n <= 1 { n } else {
  fib(n - 1) + fib(n - 2)
}
#fib(46)
```)

== `while`语句 <grammar-while>

// if condition {..}
// if condition [..]
// if condition [..] else {..}
// if condition [..] else if condition {..} else [..]

`while`语句用于循环结构，满足条件时，不断执行循环体。

```typ
#while expression { cont-block }
```

上面代码中，如果表达式`expression`为真，就会执行`cont-block`代码块，然后再次判断`expression`是否为假；如果`expression`为假就跳出循环，不再执行循环体。

#code(```typ
#let i = 0;
#while i < 10 { (i * 2, ); i += 1 }
```)

上面代码中，循环体会执行`10`次，每次将`i`增加`1`，直到等于`10`才退出循环。

== `for`语句 <grammar-for>

`for`语句也是常用的循环结构，它迭代访问某个对象的每一项。

```typ
#for X in A { cont-block }
```

上面代码中，对于`A`的每一项，都执行`cont-block`代码块。在执行`cont-block`时，项的内容是`X`。例如以下代码做了与之前循环相同的事情：

#code(```typ
#for i in range(10) { (i * 2, ) }
```)

其中`range(10)`创建了一个内容为`(0, 1, 2, .., 9)`一共10个值的数组。

== 使用内容块替代代码块

所有可以使用代码块的地方都可以使用内容块作为替代。

#code(```typ
#for i in range(4) [阿巴]......
```)

== 使用`for`遍历字典

与数组相同，同理所有字典也都可以使用`for`遍历。此时，在执行`cont-block`时，Typst将每个键值对以数组的形式交给你。键值对数组的第0项是键，键值对数组的第1项是对应的值。

#code(```typ
#let cat = (neko-mimi: 2, "utterance": "喵喵喵", attribute: [kawaii\~])
#for i in cat {
  [猫猫的 #i.at(0) 是 #i.at(1)\ ]
}
```)

你可以同时使用「解构赋值」让代码变得更容易阅读：<grammar-for-destruct>

```typ
#let cat = (neko-mimi: 2, "utterance": "喵喵喵", attribute: [kawaii\~])
#for (特色, 这个) in cat [猫猫的 #特色 是 #这个\ ]
```

== `break`语句和`continue`语句 <grammar-break>

无论是`while`还是`for`，都可以使用`break`跳出循环，或`continue`直接进入下一次执行。

基于以下`for`循环，我们探索`break`和`continue`语句的作用。

#code(```typ
#for i in range(10) { (i, ) }
```)

在第一次执行时，如果我们直接使用`break`跳出循环，但是在break之前就已经产生了一些值，那么`for`的结果是`break`前的那些值的「折叠」。

#code(```typ
#for i in range(10) { (i, ); (i + 1926, ); break }
```)

特别地，如果我们直接使用`break`跳出循环，那么`for`的结果是*`none`*。

#code(```typ
#for i in range(10) { break }
```)

在`break`之后的那些值将会被忽略：

#code(```typ
#for i in range(10) { break; (i, ); (i + 1926, ); }
```)

以下代码将收集迭代的所有结果，直到`i >= 5`：
#code(```typ
#for i in range(10) {
  if i >= 5 { break }
  (i, )
}
```)

// #for 方位 in ("东", "南", "西", "北", "中", "间", "东北", "西北", "东南", "西南") [鱼戏莲叶#方位，]

`continue`有相似的规则，便不再赘述。我们举一个例子，以下程序输出在`range(10)`中不是偶数的数字：<grammar-continue>

#code(```typ
#let 是偶数(i) = calc.even(i)
#for i in range(10) {
  if 是偶数(i) { continue }
  (i, )
}
```)

事实上`break`语句和`continue`语句还可以在参数列表中使用，但本书非常不推荐这些写法，因此也不多做介绍：

#code(```typ
#let add(a, b, c) = a + b + c
#while true { add(1, break, 2) }
```)

== 控制函数返回值

你可以通过多种方法控制函数返回值。

=== 占位符 <grammar-placeholder>

早在上节我们就学习过了占位符，这在编写函数体表达式的时候尤为有用。你可以通过占位符忽略不需要的函数返回值。

以下函数获取数组的倒数第二个元素：

#code(```typ
#let last-two(t) = {
  let _ = t.pop()
  t.pop()
}
#last-two((1, 2, 3, 4))
```)

=== `return`语句 <grammar-return>

你可以通过`return`语句忽略表达式其余*所有语句*的结果，而使用`return`语句返回特定的值。

以下函数获取数组的倒数第二个元素：

#code(```typ
#let last-two(t) = {
  t.pop()
  return t.pop()
}
#last-two((1, 2, 3, 4))
```)


== 「作用域」 <grammar-scope>

// 内容块与代码块没有什么不同。

「作用域」是一个非常抽象的概念。但是理解他也并不困难。我们需要记住一件事，那就是每个「代码块」创建了一个单独的「作用域」：

#code(```typ
两只#{
  [兔]
  set text(rgb("#ffd1dc").darken(15%))
  { [兔白]; set text(orange); [又白] }
  [，真可爱]
}
```)

从上面的染色结果来看，粉色规则可以染色到`[兔白]`、`[又白]`和`[真可爱]`，橘色规则可以染色到`[又白]`但不能染色到[，真可爱]。以内容的视角来看：
1. `[兔]`不是相对粉色规则的后续内容，更不是相对橘色规则的后续内容，所以它默认是黑色。
2. `[兔白]`是相对粉色规则的后续内容，所以它是粉色。
3. `[又白]`同时被两个规则影响，但是根据「执行顺序」，橘色规则被优先使用。
4. `[真可爱]`虽然从代码先后顺序来看在橘色规则后面，但不在橘色规则所在作用域内，不满足「`set`」影响范围的设定。

我们说「`set`」的影响范围是其所在「作用域」内的后续内容，意思是：对于每个「代码块」，「`set`」规则只影响到从它自身语句开始，到该「代码块」的结束位置。

接下来，我们回忆：「内容块」和「代码块」没有什么不同。上述例子还可以以「内容块」的语法改写成：

#code(```typ
两只#[兔#set text(fill: rgb("#ffd1dc").darken(15%))
  #[兔白#set text(fill: orange)
  又白]，真可爱
]
```)

由于断行问题，这不方便阅读，但从结果来看，它们确实是等价的。

最后我们再回忆：文件本身是一个「内容块」。

#code(```typ
两小只，#set text(fill: orange)
真可爱
```)

针对文件，我们仍重申一遍「`set`」的影响范围。其影响等价于：对于文件本身，*顶层*「`set`」规则影响到该文件的结束位置。

#pro-tip[
  也就是说，`include`文件内部的样式不会影响到外部的样式。
]

== 变量的可变性

理解「作用域」对理解变量的可变性有帮助。这原本是上一节的内容，但是前置知识包含「作用域」，故在此介绍。

话说Typst对内置实现的所有函数都有良好的自我管理，但总免不了用户打算写一些逆天的函数。为了保证缓存计算仍较为有效，Typst强制要求用户编写的*所有函数*都是纯函数。这允许Typst有效地缓存计算，在相当一部分文档的编译速度上，快过LaTeX等语言上百倍。

你可能不知道所谓的纯函数是为何物，本书也不打算讲解什么是纯函数。关键点是，涉及函数的*纯性*，就涉及到变量的可变性。

所谓变量的可变性是指，你可以任意改变一个变量的内容，也就是说一个变量默认是可变的：

#code(```typ
#let a = 1; #let b = 2;
#((a, b) = (b, a)); #a, #b \
#for i in range(10) { a += i }; #a, #b
```)

但是，一个函数的函数体表达式不允许涉及到函数体外的变量修改：

#code(
  ```typ
  #let a = 1;
  #let f() = (a += 1);
  #f()
  ```,
  res: [#text(red, [error]): variables from outside the function are read-only and cannot be modified],
)

这是因为纯函数不允许产生带有副作用的操作。

同时，传递进函数的数组和字典参数都会被拷贝。这将导致对参数数组或参数字典的修改不会影响外部变量的内容：

#code(```typ
#let a = (1, ); #a \ // 初始值
#let add-array(a) = (a += (2, ));
#add-array(a); #a \ // 函数调用无法修改变量
#(a += (2, )); #a \ // 实际期望的效果
```)

#pro-tip[
  准确地来说，数组和字典参数会被写时拷贝。所谓写时拷贝，即只有当你期望修改数组和字典参数时，拷贝才会随即发生。
]

为了“修改”外部变量，你必须将修改过的变量设法传出函数，并在外部更新外部变量。

#code(```typ
#let a = (1, ); #a \ // 初始值
#let add-array(a) = { a.push(2); a };
#(a = add-array(a)); #a \ // 返回值更新数组
```)

#pro-tip[
  一个函数是纯的，如果：
  + 对于所有相同参数，返回相同的结果。
  + 函数没有副作用，即局部静态变量、非局部变量、可变引用参数或输入/输出流等状态不会发生变化。

  本节所讲述的内容是对第二点要求的体现。
]

== 「`set if`」语法 <grammar-set-if>

回到「set」语法的话题。假设我们脚本中设置了当前文档是否处于暗黑主题，并希望使用「`set`」规则感知这个设定，你可能会写：

#code(```typ
#let is-dark-theme = true
#if is-dark-theme {
  set rect(fill: black)
  set text(fill: white)
}

#rect([wink!])
```)

根据我们的知识，这应该不起作用，因为`if`后的代码块创建了一个新的作用域，而「`set`」规则只能影响到该代码块内后续的代码。但是`if`的`then`和`else`一定需要创建一个新的作用域，这有点难办了。

`set if`语法出手了，它允许你在当前作用域设置规则。

#code(```typ
#let is-dark-theme = true
#set rect(fill: black) if is-dark-theme
#set text(fill: white) if is-dark-theme
#rect([wink!])
```)

解读`#set rect(fill: black) if is-dark-theme`。它的意思是，如果满足`is-dark-theme`条件，那么设置相关规则。这其实与下面代码“感觉”一样。

#code(```typ
#let is-dark-theme = true
#if is-dark-theme {
  set rect(fill: black)
}
#rect([wink!])
```)

区别仅仅在`set if`语法确实从语法上没有新建一个作用域。这就好像一个“规则怪谈”：如果你想要让「`set`」规则影响到对应的内容，就想方设法满足「`set`」影响范围的要求。


================================================
FILE: src/tutorial/scripting-layout.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "长度与布局")

#todo-box[本节处于校对阶段，所以可能存在不完整或错误。]

本章我们再度回到排版专题，拓宽制作文档的能力。

#let absent(content) = underline(offset: 1.5pt, underline(offset: 3pt, text(red, content)))
#let ng(content) = underline(offset: 1.5pt, text(blue, content))

== 长度类型

#show quote: it => {
  box(
    stroke: (
      left: 2pt + main-color,
    ),
    inset: (
      left: 12pt,
      y: 8pt,
    ),
    {
      stack(
        {
          set text(style: "italic")
          it.body
        },
        if "attribution" in it.fields() {
          1em
        },
        if "attribution" in it.fields() {
          align(right, [——] + it.attribution)
        },
      )
    },
  )
}

Typst有三种长度单位，它们是：绝对长度（absolute length）、相对长度（relative length）与上下文有关长度（context-sensitive length）。

+ 绝对长度：人们最熟知的长度单位。例如，```typc 1cm```恰等于真实的一厘米。
+ 相对长度：与父元素长度相关联的长度单位，例如```typc 70%```恰等于父元素高度或宽度的70%。
+ 上下文有关长度：与样式等上下文有关的长度单位，例如```typc 1em```恰等于当前位置设定的字体长度。

掌握不同种类的长度单位对构建期望的布局非常重要。它们是相辅相成的。

== 绝对长度

目前Typst一共提供四种绝对长度。除了公制长度单位```typc 1cm```与```typc 1mm```与英制长度单位```typc 1in```，Typst还提供排版专用的长度单位“点”，即```typc 1pt```。

#quote(attribution: link("https://zh.wikipedia.org/wiki/%E9%BB%9E_(%E5%8D%B0%E5%88%B7)")[维基百科：点 (印刷)])[
  点（英语：point），pt，是印刷所使用的长度单位，用于表示字型的大小，也用于余白（字距、行距）等其他版面构成要素的长度。作为铸字行业内部的一个专用单位，1 点的长度在世界各地、各个时代曾经有过不同定义，并不统一。当代最通行的是广泛应用于桌面排版软件的 DTP 点，72 点等于 1英寸（1 point = 127⁄360 mm = 0.352777... mm）。中国传统字体排印上的字号单位是号，而后采用“点”“号”兼容的体制。
]

Typst会将你提供的任意长度单位都统一成点单位，以便进行长度运算。

#{
  set align(center)
  let units = ((1pt, "pt"), (1mm, "mm"), (1cm, "cm"), (1in, "in"))
  let methods = (length.pt, length.mm, length.cm, length.inches)
  table(
    columns: 5,
    "",
    ..("pt", "mm", "cm", "in").map(e => raw("=?" + e)),
    ..units
      .map(((l, u)) => {
        (raw("1" + u, lang: "typc"),) + methods.map(method => [#calc.round(method(l), digits: 2)])
      })
      .flatten(),
  )
}

== 绝对长度的运算

长度单位可以参与任意多个浮点值的运算。一个长度表达式是合法的当且仅当运算结果*保持长度量纲*。请观察下列算式，它们都可以编译：

#code(```typ
#(1cm * 3), #(1cm / 3), #(2 * 1cm * 3 / 2), #(1cm + 3in)
```)

请观察下列算式，它们都不能编译：

#(
  ```typ
  #(1cm + 3), #(3 / 1cm), #(1cm * 1cm)
  ```
)

所谓*保持长度量纲*，即它存在一系列判别规则：

- 由于`1cm`与`3in`量纲均为长度量纲（`m`），它们之间*可以*进行*加减*运算。
- 由于`3`无量纲，`1cm`与`3`之间*不能*进行*加减*运算。

进一步，通过量纲运算，可以判断一个长度算术表达式是否合法：

#{
  set align(center)
  table(
    columns: 4,
    [长度表达式],
    [量纲运算],
    [检查合法性],
    [判断结果],
    ```typc 1cm * 3```,
    $bold(sans(m dot 1 = m))$,
    $bold(sans(m = m))$,
    table.cell(rowspan: 2, align: horizon)[合法],
    ```typc 1cm / 3```,
    $bold(sans(m op(slash) 1 = m))$,
    $bold(sans(m = m))$,
    ```typc 3 / 1cm```,
    $bold(sans(1 op(slash) m = m^(-1)))$,
    $bold(sans(m^(-1) = m))$,
    table.cell(rowspan: 2, align: horizon)[非法],
    ```typc 1cm * 1cm```,
    $bold(sans(m dot m = m^2))$,
    $bold(sans(m^2 = m))$,
  )
}

== 绝对长度的转换

你可以使用`length`类型上的「方法」实现不同单位到浮点数的转换：

#code(```typ
#1cm 是 #1cm.pt() 点 \
#1cm 是 #1cm.inches() 英尺
```)

你可以使用乘法实现浮点数到长度上的转换，例如```typc 28.3465 * 1pt```：

#code(```typ
#1cm 是 #(28.3465 * 1pt).cm() 厘米
```)

== 相对长度

有两种相对长度（Relative Length），一是百分比（Ratio），一是分数比（Fraction）。

=== 百分比 <reference-type-ratio>

#let p(w, f, ..args) = box(
  width: w,
  height: 10pt,
  fill: f,
  ..args,
)
#let code = code.with(scope: (p: p))

当「百分比」用作长度时，其实际值取决于父容器宽度：

#code(```typ
#let p(w, f, ..args) = box(
  width: w, height: 10pt, fill: f, ..args)
4比6：#p(100pt, blue, p(40%, red))
```)

Typst还支持以「分数比」作长度单位。当分数比作长度单位时，Typst按比例分配长度。

#code(```typ
4比6：#p(100pt, blue,
  p(4fr, red) + p(6fr, blue))
```)

结合代码与图例理解，`N fr`代表：在总的比例中，这个元素应当占有其中`N`份长度。

当同级元素既有分数比长度元素，又有其他长度单位元素时，优先将空间分配给其他长度单位元素。

#code(```typ
绿色先占60%: #p(100pt, blue, p(1fr, red) + p(2fr, blue) + p(60%, green)) \
绿色先占110%: #p(100pt, blue, p(1fr, red) + p(1fr, blue) + p(110%, green)) \
红色先占30pt: #p(100pt, blue, p(30pt, red) + p(1fr, blue) + p(110%, green))
```)

建议结合下文中grid布局关于长度的使用，加深对相对长度的理解。

== 上下文有关长度

目前Typst仅提供一种上下文有关长度，即当前上下文中的字体大小。历史上，定义该字体中大写字母`M`的宽度为`1em`，但是现代排版中，`1em`可以比`M`的宽度要更窄或者更宽。

上下文有关长度是与相对长度相区分的。区别是上下文有关长度的取值从「样式链」获取，而相对长度相对于父元素宽度。事实上`1em`的具体值可以通过上下文有关表达式获取：

#code(```typ
#let _1em = context measure(
  line(length: 1em)).width
#text(size: 10pt, [1em等于] + _1em) \
#text(size: 20pt, [1em等于] + _1em) \
```)

相比较，`1em`更好用一点，因为`text.size`只允许在上下文有关表达式内部使用。

== 混合长度

以上所介绍的各种长度可以通过「加号」任意混合成单个长度的值，其长度的值为每个分量总和：

#code(```typ
#(1pt + 1em + 100%)
```)

== 长度的内省或评估

你可以通过`measure`获取一个长度在当前位置的具体值：

#let length-of(l) = (measure(line(length: l)).width)
#let code = code.with(scope: (length-of: length-of))

#code(```typ
#let length-of(l) = measure(
  line(length: l)).width
#context [长度等于#length-of(1em+1pt)。]
```)

但是该方式是不被推荐的，因为一个长度值中的相对长度分量会被评估为`0pt`，从而导致计算失真：

#code(```typ
长度等于 #context length-of(1em+1pt+100%)。
```)

这是因为在评估的时候，`measure`没有为内容锚定一个“父元素”。

一种更为鲁棒的方法是使用`layout`函数获取`layout`位置的宽度和高度信息：

#code(```typ
长度等于#box(width: 1em+1pt+100%,
  layout(l => l.width))
```)

但是使用`layout`会导致布局的多轮迭代，有可能*严重*降低编译性能。

== 布局概览与布局模型

Typst的布局引擎仍未完成，其主要#absent[缺失]或#ng[不足]的内容为：
+ 修饰段落容器的#absent[行]或#ng[字符]的能力。
+ 将段落容器的接口#ng[暴露]给用户的能力。
+ #ng[浮动布局]的能力。
+ #ng[更灵活]的Layout Splitter。目前仅支持`columns`（多栏布局）的能力。

Typst的布局代码风格是用一系列容器函数包装的内容，再将整个内容交给布局引擎反复*迭代*求解。容器就是一类特殊的「元素」，它并不真正具备具体的内容，而仅仅容纳一个或多个「内容」，*以便布局*。这与JSX有些相似。

针对PDF页面模型，Typst构建了完整的容器层次。Todo：用cetz绘制层次：
#todo-box[在0.13.0之后, 情况有所改变]

1. page，一个PDF有很多页。
2. par，一个文档中有很多段。
3. block，一页/段中有很多块。
4. box，一个块中有很多行内元素。
5. sequence，很多个元素可以组成一个元素序列。
6. 各种基础元素。

=== page

每个`page`都单独产生一个单独的页面。并且若你希望将Typst文档导出为PDF，其恰好为PDF中单独的一页。

任何内容都会至少产生新的一页：

```typ
// 第一页
A
```

每个`pagebreak`函数（分页函数）将会产生新的一页：

```typ
// 第一页
A
#pagebreak()
// 第二页
B
```

```typ
// 第一页
A
#pagebreak()
// 第二页
#pagebreak()
// 第三页
B
```

你可以使用`#pagebreak(weak: true)`产生弱的分页。这里弱的意思是：假设当前页面并没有包含任何内容，`pagebreak(weak: true)`就不会创建新的页面。你可以理解为弱的分页意即非必要不分页。

```typ
// 第一页
A
#pagebreak(weak: true)
#pagebreak(weak: true)
// 第二页
B
```

每个`page`函数都会单列新的一页：

```typ
// 第一页
A
#page[
  // 第二页
  A
]
// 第三页
B
```

如果`page`的前后已经是空页，则`page`不会导致前后产生空页。

```typ
// 这里不分页
#page[
  // 第一页
  A
] // 这里不分页
#page[
  // 第二页
  A
] // 这里不分页
```

你可以理解为`page`前后自动产生弱的分页，其前后*非必要不分页*，上例相当于：

```typ
#pagebreak(weak: true)
// 第一页
A
#pagebreak(weak: true)
#pagebreak(weak: true)
// 第二页
A
#pagebreak(weak: true)
```

所以`page`与`pagebreak`是互通的，你可以随意使用你喜欢的风格创建新的页面。

*注意*：设置`page`样式将导致新的弱分页：

```typ
// 第一页
A
#set page(..)
// 第二页
B
```

等价于：

```typ
A
#pagebreak(weak: true)
#set page(..)
#pagebreak(weak: true)
B
```

=== par

每个`par`都单独产生一个单独的段落。

`par`的特性与`page`完全相同，其前后非必要不分段。

#code(```typ
#par[
  // 第一段
  A
]
```)

`parbreak`与`pagebreak`也是除了同理，除了`parbreak`一定是弱分段，并且没有可以指定的`weak`参数：

#code(```typ
// 第一段
A
#parbreak()
#parbreak()
// 第二段
B
```)

很多元素都会在其前后自动产生新的段落，例如`figure`和`heading`。

=== block

`block`是布局中的块状元素。块状元素会在布局中自成一行。你几乎可以将`block`理解为某种程度上的分段：

#code(```typ
// 第一段
#block(fill: blue)[A]
#block(fill: blue)[B]
```)

事实上`par`本来就由`block`组成。你可以通过对`block`设置规则影响到段间距：

#code(```typ
#set block(spacing: 0.5em)
A
#parbreak()
#parbreak()
B
```)

=== box

`box`是布局中的行内块元素。行内块元素会在布局中自成一行。所谓行内块即其自成一块但不会立即导致换行。如下所示：

#code(```typ
#rect(width: 100pt)[a a a #box(fill: blue)[A A A A A]a a a]
```)

`box`并不意味着不换行。`box`的宽度默认占满父元素内宽度的```typc 100%```。`box`内部的文本在其内部继续换行。如下所示，当文字太多时，将导致其在`box`内部换行：

#code(```typ
#rect(width: 100pt)[#box(fill: blue)[A A A A A A A A A A A A A]]
```)

`box`整体必须处于段落中的同一行：

#code(```typ
#rect(width: 100pt)[a a a a#box(fill: blue, width: 50%)[A A A A A A A A A]a a a]
#rect(width: 100pt)[a a a a a#box(fill: blue, width: 50%)[A A A A A A A A A]a a a]
```)

一个妙用是，你可以将“块元素”包裹一层`box`，使得这些块元素位于段落中的同一行：

#code(```typ
我们之中混入了
#box(rect(width: 100pt)[a a a a#box(fill: blue, width: 50%)[A A A A A A A A A]a a a])
两个矩形
#box(rect(width: 100pt)[a a a a a#box(fill: blue, width: 50%)[A A A A A A A A A]a a a])
```)

=== sequence

`sequence`是布局中最松散的组织。事实上，它正是我们在《基础文档》中就学过的「内容块」。它起不到任何效果，仅仅容纳一系列其他内容。

#code(```typ
#rect(width: 100pt)[#[a a a a a a] #[a a a a a a a a] ]
```)

我们来温习一下。`sequence`主要的作用是可以储存一段内容供函数使用。使用`sequence`的一个好处是允许「标签」准确地选中一段内容。例如，以下代码自制了`highlight`效果：

#code(```typ
#show <fill-blue>: it => {
  show regex("[\w]"): it => {
    box(place(dx: -0.1em, dy: -0.15em, box(fill: blue, width: 0.85em, height: 0.95em)) + it)
  }
  it
}
#rect(width: 100pt)[#[a a a a a a] #[a a a a a a a ab] <fill-blue> ]
```)

== 「布局分割及其断点」

「布局分割器」（Splitter）将所持有内容分成多段并放置于页面上。

目前Typst唯一提供的分割器是`columns`，其实现了多栏布局。因为缺乏好用的分割器，有很多布局都*难以*在Typst中实现，例如浮动布局。但注意，这不代表现在的Typst不支持各种特殊布局。已经有外部库帮助你实现了首字母下沉，浮动布局等特殊布局。

你可以使用`columns`在任意容器内创建多栏布局，并用`colbreak`分割每栏。

#code(```typ
#columns(2)[
  #lorem(13)
  #colbreak()
  #lorem(10)
]
```)

尽管还不是很完善，在与页面的结合中，Typst为`page`提供了一个`columns`参数。该`columns`允许你设置跨页的多栏布局。

// #frames(
//   ```typ
//   #set page(columns: 2)
//   #set text(size: 5pt)
//   #lorem(130)
//   ```,
//   prelude: ```typ
//   #set page(width: 120pt, height: 120pt)
//   ```,
// )

== 「布局编排」

「布局编排器」（Arranger）将多个内容组成一个新的带有布局的整体。目前，Typst提供了两种零维布局`pad`和`align`，一种一维布局`stack`，以及一种二维布局`grid`。

== pad

你可以使用`pad`函数为内部元素设置outer padding。`pad`接受一个内容，返回一个添加padding的新内容。默认情况下，`pad`函数不添加任何padding。

#code(```typ
#let square = rect(fill: blue, width: 15pt, height: 15pt)
#box(fill: red, square)
#box(fill: red, pad(square))
```)

与CSS的`padding`属性一样，你可以使用`left`、`top`、`right`、`bottom`设置四个方向的padding：

#code(```typ
#let square = rect(fill: blue, width: 15pt, height: 15pt)
#box(fill: red, pad(left: 5pt, square))
#box(fill: red, pad(top: 5pt, square))
#box(fill: red, pad(right: 5pt, square))
#box(fill: red, baseline: 5pt, pad(bottom: 5pt, square))
#box(fill: red, pad(left: 5pt, top: 5pt, square))
#box(fill: red, pad(left: 5pt, right: 5pt, square))
```)

特别地，你可以使用`x`同时设置`left`和`right`方向的padding，`y`同时设置`top`和`bottom`方向的padding，以及`rest`设置“其余”方向的padding。

#code(```typ
#let square = rect(fill: blue, width: 15pt, height: 15pt)
#box(fill: red, pad(x: 5pt, square))
#box(fill: red, baseline: 5pt, pad(y: 5pt, square))
#box(fill: red, baseline: 2pt, pad(left: 5pt, rest: 2pt, square))
```)

== align

你可以使用`align`函数为内部元素设置相对于父元素的对齐方式。默认情况下，`align`函数使用默认对齐方式（`start+top`）。

#let square = rect(fill: rgb("c45a65c0"), width: 15pt, height: 15pt)
#let abox = box.with(fill: gradient.radial(..color.map.mako), width: 20pt, height: 20pt)

#let align-scope = (
  square: square,
  abox: abox,
  red: rgb("c45a65c0"),
)

#code(
  ```typ
  #let square = rect(fill: red, width: 15pt, height: 15pt)
  #let abox = box.with(fill: gradient.radial(..color.map.mako), width: 20pt, height: 20pt)
  #abox(square)
  #abox(align(square))
  ```,
  scope: align-scope,
)

与上一节介绍的`pad`类似，你可以使用`left`、`top`、`right`、`bottom`设置四个方向的alignment，并任意使用加号（`+`）组合出你想要的二维对齐方式：

#code(
  ```typ
  #abox(align(left + top, square))
  #abox(align(right + top, square)) \
  #abox(align(left + bottom, square))
  #abox(align(right + bottom, square))
  ```,
  scope: align-scope,
)

除了以上四种基础对齐，Typst还额外提供两套对齐方式。第一套是居中对齐，你可以使用`center`实现水平居中对齐，以及`horizon`实现垂直居中对齐。

#code(
  ```typ
  #abox(align(center, square))
  #abox(align(horizon, square))
  #abox(align(center + horizon, square))
  ```,
  scope: align-scope,
)

第二套与文本流相关。你可以使用`start`实现与文本流方向一致的对齐，以及`end`实现与文本流方向相反的对齐。

#code(
  ```typ
  #let se = abox(align(start, square)) + abox(align(end, square))
  #se \
  #set text(dir: rtl)
  #se
  ```,
  scope: align-scope,
)

=== stack

与HTML中的`flex`容器类似，`stack`可以帮你实现各种一维布局。顾名思义，`stack`将其内部元素在页面上按顺序按方向排列。

#let rects = (rect(fill: red)[1], rect(fill: blue)[2], rect(fill: green)[3])

#code(
  ```typ
  #let rects = (rect(fill: red)[1], rect(fill: blue)[2], rect(fill: green)[3])
  #stack(dir: ltr, ..rects)
  ```,
  scope: (rects: rects),
)

`stack`主要只有两个可以控制的参数。

其一是排列的方向，参数对应为`dir`。一共有四种方向可以选择，分别是：
- `ltr`: 即left to right，从左至右。
- `rtl`: 即right to left，从右至左。
- `ttb`: 即top to bottom，从上至下。
- `btt`: 即bottom to top，从下至上。

方向默认为`ttb`。

#code(
  ```typ
  #columns(2)[
    `ltr`: #box(stack(dir: ltr, ..rects)) \ `rtl`: #box(stack(dir: rtl, ..rects))
    #colbreak()
    `ttb`: #box(stack(/* 默认值为：dir: ttb, */ ..rects)) #h(1em) `btt`: #box(stack(dir: btt, ..rects))
  ]
  ```,
  scope: (rects: rects, box: box.with(baseline: 50% - 0.25em)),
)

其二是排列的间距，参数对应为`spacing`。你可以使用各种长度为`stack`内部元素制定合适的间距。

#code(
  ```typ
  #let stack = stack.with(dir: ltr)
  #let example(s) = box(width: 100pt, stack(spacing: s, ..rects))
  `5pt    `: #example(5pt    ) \
  `10%    `: #example(10%    ) \
  `5pt+10%`: #example(5pt+10%) \
  `1fr    `: #example(1fr    ) \
  ```,
  scope: (rects: rects, box: box.with(baseline: 50% - 0.25em)),
)

你也可以直接将长度作为参数传入，为每一个元素前后微调间距。

#code(
  ```typ
  #let stack = stack.with(dir: ltr)
  #let r = rect(fill: blue)[ ]
  `1fr,0pt`: #box(width: 100pt, stack(r, 1fr, r, r)) \
  `1fr,2fr`: #box(width: 100pt, stack(r, 1fr, r, 2fr, r)) \
  `10%,40%`: #box(width: 100pt, stack(r, 10%, r, 40%, r)) \
  ```,
  scope: (rects: rects, box: box.with(baseline: 50% - 0.25em)),
)

当同时声明`spacing`参数和长度参数时，长度参数会覆盖`spacing`设置：

#code(
  ```typ
  #show stack: box.with(width: 100pt, stroke: green)
  #let stack = stack.with(dir: ltr)
  #let r = rect(fill: blue)[ ]
  `         `: #stack(spacing: 5pt, r, r, r, r, r) \
  ` 0pt     `: #stack(spacing: 5pt, r, r, r, r,  0pt, r) \
  `10pt     `: #stack(spacing: 5pt, r, r, r, r, 10pt, r) \
  `10pt+10pt`: #stack(spacing: 5pt, r, r, r, r, 10pt, 10pt, r) \
  ```,
  scope: (box: box.with(baseline: 50% - 0.25em)),
)

=== stack+align/pad

你可以将`stack`与`align/pad`相结合，实现更多一维布局。以下例子对应CSS相关属性：

#code(
  ```typ
  #let box = box.with(width: 100pt, stroke: green)
  #let stack = stack.with(dir: ltr, spacing: 1fr)
  #let r = rect(fill: blue)[ ]
  `space-around 5pt`: #box(stack(5pt, r, r, 5pt)) \
  `space-around 5pt`: #box(pad(x: 5pt, stack(r, r))) \
  `justify-content end`: #box(align(end, box(width: 60pt, stack(r, r)))) \
  `justify-content center`: #box(align(center, box(width: 60pt, stack(r, r)))) \
  ```,
  scope: (box: box.with(baseline: 50% - 0.25em)),
)

上例提示我们可以组合多种布局容器实现特定的布局效果。

=== grid

与HTML中的`flex`容器类似，`grid`可以帮你实现各种二维布局。如下：

#code(```typ
#show grid: box.with(stroke: green)
#let r = rect(fill: blue, width: 10pt, height: 10pt)
#grid(columns: 3, gutter: 5pt, r, r, r, r, r)
```)

与`stack`相比，`grid`要复杂得多。

其一，`grid`的前$N - 1$行可容纳的元素是有限的，而最后一行与`stack`一样容纳其余所有元素。你可以通过`columns`参数控制这一特性。

#let g-scope = (
  r: (n, width: 10pt, height: 10pt) => range(n).map(i => rect(
    fill: color.map.rainbow.at(calc.rem(i * 16, 80)),
    width: width,
    height: height,
  )),
)

`columns`要求你给定一个数组，该数组表示一行中每列的宽度。

#code(
  ```typ
  #let r(n, width: 10pt, height: 10pt) = range(n).map(i => rect(fill: color.map.rainbow.at(calc.rem(i * 16, 80)), width: width, height: height))
  #grid(columns: (auto, ) * 10, gutter: 5pt, ..r(10)) #h(1em)
  #grid(columns: (auto, ) * 8, gutter: 5pt, ..r(10)) #h(1em)
  #grid(columns: (auto, ) * 4, gutter: 5pt, ..r(10)) #h(1em)
  #grid(columns: (auto, ) * 2, gutter: 5pt, ..r(10))
  ```,
  scope: (..g-scope, grid: (..args) => box(stroke: green, grid(..args))),
)

上例中，当`columns`数组的长度为`N`时，表示每行允许容纳`N`个元素，每列的*最大宽度*为`auto`。长度设定为`auto`，则表示每列宽度始终和该行该列内部元素宽度相等。

每列宽度不仅可以为`auto`，而且可以指定为具体长度：

#code(
  ```typ
  #show grid: box.with(stroke: green, width: 100pt)
  #let grid = grid.with(gutter: 5pt, ..r(5, width: auto))
  1: #grid(columns: (10pt, 20pt, 30pt)) #h(1em)
  2: #grid(columns: (10%, 20%, 30%)) #h(1em)
  3: #grid(columns: (1fr, 2fr, 3fr)) #h(1em) \
  4: #grid(columns: (10pt, 1fr, 1fr)) #h(1em)
  5: #grid(columns: (10pt, 1fr, 2fr)) #h(1em)
  ```,
  scope: g-scope,
)

Typst允许你使用更简便的参数表示。特别地，如果`columns`数组内容恰为$N$个`auto`，那么可以直接传入一个数字。以下两种写法是等价的：

#code(
  ```typ
  #grid(columns: 4, gutter: 5pt, ..r(10)) #h(1em)
  #grid(columns: (auto, ) * 4, gutter: 5pt, ..r(10)) #h(1em)
  ```,
  scope: (..g-scope, grid: (..args) => box(stroke: green, grid(..args))),
)

特别地，如果期望`grid`只有一列，`columns`参数允许不传入数组而是单列的长度：

#code(
  ```typ
  #show grid: box.with(stroke: green, width: 20pt)
  #let grid = grid.with(gutter: 5pt, ..r(3, width: auto))
  #grid(columns: (10pt, )) #h(1em)
  #grid(columns: 10pt) #h(1em)
  #grid(columns: 50%) #h(1em)
  #grid(columns: 80%) #h(1em)
  ```,
  scope: g-scope,
)

特别地，columns的默认值可以理解为`auto`。

其二，`grid`不再允许混杂内容与长度来控制某行或某列元素之间的间隔。取而代之的是三个更为复杂的参数：`gutter`、`row-gutter`和`column-gutter`。这是因为“混杂的gutter”在二维布局中有歧义。

`gutter`参数事实上是`spacing`参数的加强版。它允许通过传入一个长度数组为*每行每列依次*设置间隔：

#code(
  ```typ
  #let grid = grid.with(columns: (auto, ) * 4, ..r(15))
  #grid(gutter: 5pt) #h(1em)
  #grid(gutter: (5pt, 10pt, 15pt)) #h(1em)
  ```,
  scope: (..g-scope, grid: (..args) => box(stroke: green, grid(..args))),
)

特别地，如果`gutter`参数数组比`rows`参数数组或者`columns`参数数组更短，其余行或列的的间隔以`gutter`参数数组的最后一个长度为准：

#code(
  ```typ
  #let grid = grid.with(columns: (auto, ) * 5, ..r(9))
  // 等价为`5pt, 5pt, 5pt, ..`, 一直5pt下去
  #grid(gutter: 5pt) #h(1em)
  // 等价为`5pt, 5pt, 5pt, ..`, 一直5pt下去
  #grid(gutter: (5pt,)) #h(1em)
  // 等价为`5pt, 10pt, 10pt, ..`, 一直10pt下去
  #grid(gutter: (5pt, 10pt)) #h(1em)
  ```,
  scope: (..g-scope, grid: (..args) => box(stroke: green, grid(..args))),
)

你可以指定`column-gutter`而非`gutter`，从而单独为*每列*设置间隔。`column-gutter`参数的优先级比`gutter`参数要高。

#code(
  ```typ
  #let grid = grid.with(columns: (auto, ) * 4, ..r(15))
  #grid(gutter: (5pt, 10pt, 15pt)) #h(1em)
  #grid(gutter: 5pt, column-gutter: (5pt, 10pt, 15pt)) #h(1em)
  #grid(column-gutter: (5pt, 10pt, 15pt)) #h(1em)
  ```,
  scope: (..g-scope, grid: (..args) => box(stroke: green, grid(..args))),
)

与`column-gutter`同理，你也可以指定`row-gutter`而非`gutter`，从而单独为*每行*设置间隔。

与`columns`同理，你可以指定`rows`从而为每行设置高度。但是请注意，Typst对`rows`参数数组的解释方式与`columns`不同，而与`gutter`相同：

#code(
  ```typ
  #show grid: box.with(stroke: green, height: 120pt)
  #let grid = grid.with(columns: 2, gutter: 5pt, ..r(7, height: auto))
  // 等价为`10pt, 10pt, 10pt, ..`, 一直10pt下去
  1: #grid(rows: (10pt, )) #h(1em)
  // 等价为`10pt, 20pt, 20pt, ..`, 一直20pt下去
  2: #grid(rows: (10pt, 20pt)) #h(1em)
  // 等价为`1fr, 2fr, 2fr, ..`, 一直2fr下去
  3: #grid(rows: (1fr, 2fr)) #h(1em)
  ```,
  scope: g-scope,
)

// #grid(gutter: (5pt, 10pt)) #h(1em)

== 「间距」

此类函数的概念引自LaTeX，又称胶水函数。一共有两个方向的间距，分别是水平间距与竖直间距。

水平间距（`h`，horizon）不包含内容，而仅仅在布局中占据一定宽度：

#code(```typ
两句话之间间隔`0pt`#h(0pt)两句话之间间隔`0pt` \
两句话之间间隔`5pt`#h(5pt)两句话之间间隔`5pt` \
两句话之间间隔`1em`#h(1em)两句话之间间隔`1em` \
间隔`1fr`#h(1fr)间隔`1fr` \
间隔`1fr`#h(1fr)间隔`...`#h(2fr)间隔`2fr` \
#h(1fr)夹心的`1fr``...`#h(1fr) \
```)

同理竖直间距（`v`，vertical）不包含内容，而仅仅在布局中占据一定高度。插入竖直间距将会导致强制换行。

#code(```typ
1 2 \
1 \ 2 \
1 #v(-1em) 2
```)

== 「空间变换」

一共有三种类型的空间变换，分别是：
- `move`：移动元素。
- `scale`：拉伸元素。
- `rotate`：旋转元素。

它们都*不会影响布局*，且都会*导致强制换行*。

`move`相对于当前位置移动一段距离。

#code(```typ
#rect(inset: 0pt, move(
  dx: 6pt, dy: 6pt,
  rect(
    inset: 8pt,
    fill: white,
    stroke: black,
    [Abra cadabra]
  )
))
```)

你可以使用`box`将其改为行内元素行为：

#code(```typ
#let TeX(width) = {
  set text(font: "New Computer Modern", weight: "regular")
  box(width: width, {
    [T]
    box(stroke: red, move(dx: -0.2em, dy: 0.22em)[E])
    box(stroke: green, move(dx: -0.4em)[X])
  })
}
#TeX(2.2em) is a digital typographical systems. \
#TeX(2.1em) is a digital typographical systems.
```)

`scale`可以拉伸元素，且`scale`会导致强制换行：

#code(```typ
#scale(x: 110%)[This is mirrored.]
#box(scale(x: 100%)[This is scaled.]) 1 \
#box(scale(x: 115%)[This is scaled.]) 1
```)

特别地，你可以指定负长度以反转元素：

#code(```typ
#scale(x: -100%)[This is mirrored.]
```)

`rotate`可以旋转元素：

#code(```typ
#rotate(5deg)[This is rotated.]
```)

== 让「空间变换」函数影响布局

虽然内置的`move`等函数不会影响布局，但是你可以通过`box`模拟子元素对父元素的布局影响：

#code(```typ
#let ac(a) = calc.abs(calc.cos(a))
#let ax(a) = calc.abs(calc.sin(a))
#let rot(x,y,a) = .5*(x*(ac(a)-1)+y*ax(a))
#let rotx(body, angle) = context {
let sz = measure(body)
box(stroke: green, inset: (
  x: rot(sz.width, sz.height, angle),
  y: rot(sz.height, sz.width, angle)),
  rotate(body, angle))
}
#lorem(7) This is a #rotx([Vertical],-90deg) word, and #rotx([this],-7deg) is #rotx([skew.],7deg) It also works with #rotx($e^(-x)$,-95deg). #lorem(20)
```)

例子使用了`measure`函数评估子元素的大小，并强行改变子元素的边界框（bounding box）。

== 「绝对定位布局」

你可以使用`place`完成「绝对定位布局」（absolute positioning）。`place`相对于父元素移动一段距离，其接受一个`alignment`参数，将元素放置在相对于父元素`alignment`的绝对位置。例如下例相对于父元素的右上角放置了一个矩形框：

#code(```typ
#box(height: 30pt, width: 100%)[
  Hello, world!
  #place(
    top + right,
    square(
      width: 20pt,
      stroke: 2pt + blue
    ),
  )
]
```)

`place`会使得子元素脱离父元素布局。对比两例：

#code(```typ
#let TeX(width: 2.2em) = {
  set text(font: "New Computer Modern", weight: "regular")
  box(width: width, {
    [T]
    box(stroke: red, move(dx: -0.2em, dy: 0.22em)[E])
    box(stroke: green, move(dx: -0.4em)[X])
  })
}
#TeX() is a digital typographical systems. \
#let TeX = {
  set text(font: "New Computer Modern", weight: "regular")
  box(width: 1.7em, {
    [T]
    place(top, dx: 0.56em, dy: 0.22em, box(stroke: red, [E]))
    place(top, dx: 1.1em, box(stroke: green, [X]))
  })
}
#TeX is a digital typographical systems.
```)

你可以使用`place(float: true)`以创建相对于父元素的浮动布局。（todo）

== 杂项
+ hide
+ repeat


================================================
FILE: src/tutorial/scripting-literal.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "基本类型")

Typst很快，并非因为它的#term("parser")和#term("interpreter")具有惊世的执行性能，而是语言特性本身适合缓存优化。

自本节起，本教程将进入第二阶段，希望不仅让你了解如何使用脚本，还一并讲解Typst的执行原理。当然，我们不会陷入Typst的细节。所有在教程中出现的原理都是为了更好地了解语言本身。

// 什么是自省
// 程序不会自己自省，这是给你看的

== 代码表示的自省函数 <grammar-repr>

在开始学习之前，先学习几个与排版无关但非常实用的函数。

#typst-func("repr")是一个#term("introspection function")，可以帮你获得任意值的代码表示，很适合用来在调试代码的时候输出内容。

#code(```typ
#[ 一段文本 ]

#repr([ 一段文本 ])
```)

#pro-tip[
  #term("introspection function")是指那些为你获取解释器内部状态的函数。它们往往接受一些语言对象，而返回存储在解释器内部的相关信息。在这里，#typst-func("repr")接受任意值，而返回对应的代码表示。
]

== `type`函数 <grammar-type>

与#typst-func("repr")类似，一个特殊的函数#typst-func("type")可以获得任意值的#term("type")。所谓#term("type")，就是这个值归属的分类。例如：
- `1`是整数数字，类型就对应于整数类型（integer）。
  #code(```typ
  #type(1)
  ```)
- `一段内容`是文本内容，类型就对应于内容类型（content）。
  #code(```typ
  #type[一段内容]
  ```)

=== 类型 <type-type>

一个值只会属于一种类型，因此类型是可以比较的：

#code(```typ
#(str == str) \
#(type("X") == type("Y")) \
#(type("X") == str) \
#([一段内容] == str)
```)

类型的类型是类型（它自身）：

#code(```typ
#(type(str)) \
#(type(type(str))) \
#(type(type(str)) == type) \
```)

== `eval`函数 <grammar-eval>

`eval`函数接受一个字符串，把字符串当作代码执行并求出结果：

#code(```typ
#eval("1"), #type(eval("1")) \
#eval("[一段内容]"), #type(eval("[一段内容]"))
```)

从```typc eval("[一段内容]")```的中括号被解释为「内容块」可以得知，`eval`默认以#term("code mode")解释你的代码。

你可以使用`mode`参数修改`eval`的「解释模式」。`code`对应为#term("code mode")，`markup`对应为#term("markup mode")：<grammar-eval-markup-mode>

#code(```typ
代码模式eval：#eval("[一段内容]", mode: "code") \
标记模式eval：#eval("[一段内容]", mode: "markup")
```)

// #let x = 1;

// #let f() = x

// #f()
// #(x = 2)
// #f()

== 基本字面量

我们将介绍所有基本字面量，这是脚本的“一加一”。其实在上一节，我们已经见过了一部分字面量，但皆凭直觉使用：```typc 1```不就是数字吗，那么在Typst中，它就是数字。与之相对，TeX底层没有数字和字符串的概念。

如果你学过Python等语言，那么这将对你来说不是问题。在Typst中，常用的字面量并不多，它们是：
+ #term("none literal")。
+ #term("boolean literal")。
+ #term("integer literal")。
+ #term("floating-point literal")。
+ #term("string literal")。

=== 空字面量 <grammar-none-literal>

就像是数学中的零与负数，空字面量自然产生于运算过程中。

#code(```typ
#repr((0, 1).find((_) => false)),
#repr(if false [啊？])
```)

上例第一行，当在「数组」中查找一个不存在的元素时，“没有”就是```typc none```。第二行，当条件不满足，且没有`false`分支时，“没有内容”就是```typc none```。

空字面量是纯粹抽象的概念，这意味着你在现实中很难找到对应的实体。

// #pro-tip[
//   空字面量自然产生于运算过程中。除上所述，以下是其他会产生```typc none```的自然场景：
//   - 当变量未初始化时。
//   #code(```typ
//   #let x; #type(x)
//   ```)
//   - 当`for`语句、`while`语句、函数没有产生任何值时，函数返回值为```typc none```。
//   #code(```typ
//   #let f() = {}; #type(f())
//   ```)
//   - 当函数显式`return`且未写明返回值时，函数返回值为```typc none```。
//   #code(```typ
//   #let f() = return; #type(f())
//   ```)
// ]

`none`值不会对输出文档有任何影响：

#code(```typ
#none
```)

`none`的类型是`none`类型。`none`值不等于`none`类型，因为一个是值而另一个是类型：

#code(```typ
#type(none), #(type(none) == none), #type(type(none))
```)

=== 布尔字面量

一个布尔字面量表示逻辑的确否。它要么为```typc false```（真）<grammar-true-literal>要么为```typc true```（假）<grammar-false-literal>。

#code(```typ
假设 #false 那么一切为 #true。
```)

一般来说，我们不直接使用布尔值。当代码做逻辑判断的时候，会自然产生布尔值。

#code(```typ
$1 < 2$的结果为：#(1 < 2)
```)

=== 整数字面量 <grammar-integer-literal>

一个整数字面量代表一个整数。Typst中的整数默认为十进制：

#code(```typ
三个值 #(-1)、#0 和 #1 偷偷混入了我们内容之中。
```)

#pro-tip[
  有的时候Typst不支持在#mark("#")后直接跟一个值。例如，Typst无法处理#mark("#")后直接跟随一个#mark("hyphen")的情况。这个时候无论多么复杂，都可以用括号包裹值：

  #code(```typ
  #(-1), #(0), #(1)
  ```)
]

有些数字使用其他进制表示更为方便。你可以分别使用`0x`、`0o`和`0b`前缀加上进制内容表示十六进制数、八进制数和二进制数：<grammar-n-adecimal-literal>

#code(```typ
#(0xbeef)、#(0o755)、#(-0b1001)
```)

整数的有效取值范围是$[-2^63,2^63)$，其中$2^63=9223372036854775808$。

=== 浮点数字面量 <grammar-float-literal>

浮点数与整数非常类似。最常见的浮点数由至少一个整数部分或小数部分组成：

#code(```typ
浮点数#(1.001)、小数部分#(.1) 和整数部分#(2.)。
```)

有些数字使用#term("exponential notation")更为方便：<grammar-exp-repr-float>

#code(```typ
#(1e2)、#(1.926e3)、#(-1e-3)
```)

Typst还为你内置了一些特殊的数值，它们都是浮点数：

#code(```typ
$inf$=#calc.inf,
$pi$=#calc.round(calc.pi, digits: 5),
$tau$=#calc.round(calc.tau, digits: 5)
```)
// NaN=#calc.nan \

=== 字符串字面量 <grammar-string-literal>

Typst中所有字符串都是`utf-8`编码的，因此使用时不存在编码转换问题。字符串由一对「英文双引号」定界：

#code(```typ
#"Hello world!!"
```)

有些字符无法置于双引号之内，例如双引号本身。与「标记模式」中的转义序列语法类似，这时候你需要嵌入字符的转义序列：

#code(```typ
#"Hello \"world\"!!"
```)

字符串中的转义序列与「标记模式」中的转义序列语法相同，但有效转义的字符集不同。字符串中如下转义序列是有效的：

#{
  set align(center)
  table(
    columns: 7,
    [代码], [`\\`], [`\"`], [`\n`], [`\r`], [`\t`], [`\u{2665}`],
    [效果], "\\", "\"", [(换行)], [(回车)], [(制表)], "\u{2665}",
  )
}

你同样可以使用`\u{unicode}`格式直接嵌入Unicode字符。

#code(```typ
#"香辣牛肉粉好吃\u{2665}"
```)

除了使用简单字面量构造，可以使用以下方法从代码块获得字符串：

#code(```typ
#repr(`包含换行符和双引号的

"内容"`.text)
```)

== 类型转换

类型本身也是函数，例如`int`类型可以接受字符串，转换成整数。

#code(```typ
#int("11"), #int("-23")
```)

从转换的角度，`eval`可以将代码字符串转换成值。例如，你可以转换16进制数字：

#code(```typ
#eval("0x3f")
```)

== 总结

// Typst如何保证一个简单函数甚至是一个闭包是“纯函数”？

// 答：1. 禁止修改外部变量，则捕获的变量的值是“纯的”或不可变的；2. 折叠的对象是纯的，且「折叠」操作是纯的。

// Typst的多文件特性从何而来？

// 答：1. import函数产生一个模块对象，而模块其实是文件顶层的scope。2. include函数即执行该文件，获得该文件对应的内容块。

// 基于以上两个特性，Typst为什么快？

// + Typst支持增量解析文件。
// + Typst所有由*用户声明*的函数都是纯的，在其上的调用都是纯的。例如Typst天生支持快速计算递归实现的fibnacci函数：

//   #code(```typ
//   #let fib(n) = if n <= 1 { n } else { fib(n - 1) + fib(n - 2) }
//   #fib(42)
//   ```)
// + Typst使用`include`导入其他文件的顶层「内容块」。当其他文件内容未改变时，内容块一定不变，而所有使用到对应内容块的函数的结果也一定不会因此改变。

// 这意味着，如果你发现了Typst中与一般语言的不同之处，可以思考以上种种优势对用户脚本的增强或限制。

#todo-box[重写总结]

基于《字面量、变量和函数》掌握的知识你应该可以：
+ 查看#(refs.ref-type-builtin)[《参考：内置类型》]，以掌握内置类型的使用方法。
+ 查看#(refs.ref-visualization)[《参考：图形与几何元素》]，以掌握图形和几何元素的使用方法。
+ 查看#(refs.ref-wasm-plugin)[《参考：WASM插件》]，以掌握在Typst中使用Rust、JavaScript、Python等语言编写插件库。
+ 阅读#(refs.ref-grammar)[《参考：语法示例检索表》]，以检查自己的语法掌握程度。
+ 查看#(refs.ref-typebase)[《参考：基本类型》]，以掌握基本类型的使用方法。
+ 查看#(refs.ref-color)[《参考：颜色、色彩渐变与模式》]，以掌握色彩的高级管理方法。
+ 查看#(refs.ref-data-process)[《参考：数据读写与数据处理》]，以助你从外部读取数据或将文档数据输出到文件。
+ 查看#(refs.ref-bibliography)[《参考：导入和使用参考文献》]，以助你导入和使用参考文献。
+ 阅读基本参考部分中的所有内容。

== 习题

#let q1 = ````typ
#let a0 = 2
#let a1 = a0 * a0
#let a2 = a1 * a1
#let a3 = a2 * a2
#let a4 = a3 * a3
#let a5 = a4 * a4
#a5
````

#exercise[
  使用本节所讲述的语法，计算$2^32$的值：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ````typ
#let a = [一]
#let b = [渔]
#let c = [江]
#let f(x, y) = a + x + a + y
#let g(x, y, z, u, v) = [#f(x, y + a + z)，#f(u, v)。]
#g([帆], [桨], [#(b)舟], [个#(b)翁], [钓钩]) \
#g([俯], [仰], [场笑], [#(c)明月], [#(c)秋])
````

#exercise[
  输出下面的诗句，但你的代码中至多只能出现17个汉字：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ````typ
#let calc-fib() = {
  let res = range(2).map(float)
  for i in range(2, 201) {
    res.push(res.at(i - 1) + res.at(i - 2))
  }

  res
}
#let fib(n) = calc-fib().at(n)

#fib(75)
````

#exercise[
  已知斐波那契数列的递推式为$F_n = F_(n-1) + F_(n-2)$，且$F_0 = 0, F_1 = 1$。使用本节所讲述的语法，计算$F_75$的值：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ````typ
#set align(center)
#let matrix-fmt(..args) = table(
  columns: args.at(0).len(),
  ..args.pos().flatten().flatten().map(str)
)
#matrix-fmt(
  (1, 2, 3),
  (4, 5, 6),
  (7, 8, 9),
)
````

#exercise[
  编写函数，使用`table`（表格）元素打印任意$N times M$矩阵，例如：

  ```typ
  #matrix-fmt(
    (1, 2, 3),
    (4, 5, 6),
    (7, 8, 9),
  )
  ```

  #rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]



================================================
FILE: src/tutorial/scripting-main.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "编译流程")

#todo-box[本节处于校对阶段，所以可能存在不完整或错误。]

经过几节稍显枯燥的脚本教程，我们继续回到排版本身。

在#(refs.writing-markup)[《初识标记模式》]中，我们学到了很多各式各样的内容。我们学到了段落、标题、代码片段......

接着我们又花费了三节的篇幅，讲授了各式各样的脚本技巧。我们学到了字面量、变量、闭包......

但是它们之间似乎隔有一层厚障壁，阻止了我们进行更高级的排版。是了，如果「内容」也是一种值，那么我们应该也可以更随心所欲地使用脚本操控它们。Typst以排版为核心，应当也对「内容类型」有着精心设计。

本节主要介绍如何使用脚本排版内容。这也是Typst的核心功能，并在语法上*与很多其他语言有着不同之处*。不用担心，在我们已经学了很多Typst语言的知识的基础上，本节也仅仅更进一步，教你如何真正以脚本视角看待一篇文档。

纵览Typst的编译流程，其大致分为4个阶段，解析、求值、排版和导出。

// todo: 介绍Typst的多种概念

// Source Code
// Value
// Type
// Content

// todo: 简化下面的的图片
#import "../figures.typ": figure-typst-arch
#align(center + horizon, figure-typst-arch())

// ，层层有缓存

为了方便排版，Typst首先使用了一个函数“解析和评估”你的代码。有趣地是，我们之前已经学过了这个函数。事实上，它就是#typst-func("eval")。

#code(```typ
#repr(eval("#[一段内容]", mode: "markup"))
```)

流程图展现了编译阶段间的关系，也包含了本节「块」与「表达式」两个概念之间的关系。

- #typst-func("eval")输入：在文件解析阶段，*代码字符串*被解析成一个语法结构，即「表达式」。古人云，世界是一个巨大的表达式。作为世界的一部分，Typst文档本身也是一个巨大的表达式。事实上，它就是我们在上一章提及的「内容块」。文档的本身是一个内容块，其由一个个标记串联形成。

- #typst-func("eval")输出：在内容排版阶段，排版引擎事实不作任何计算。用TeX黑话来说，文档被“解析和评估”完了之后，就成为了一个个「材料」（material）。排版引擎将材料。

在求值阶段。「表达式」被计算成一个方便排版引擎操作的值，即「材料」。一般来说，我们所谓的表达式是诸如`1+1`的算式，而对其求值则是做算数。

#code(```typ
#eval("1+1")
```)

显然，如果意图是让排版引擎输出计算结果，让排版引擎直接排版2要比排版“1+1”更简单。

但是对于整个文档，要如何理解对内容块的求值？这就引入了「可折叠」的值（Foldable）的概念。「可折叠」成为块作为表达式的基础。

== Typst的主函数

在Typst的源代码中，有一个Rust函数直接对应整个编译流程，其内容非常简短，便是调用了两个阶段对应的函数。“求值”阶段（`eval`阶段）对应执行一个Rust函数，它的名称为`typst::eval`；“内容排版”阶段（`typeset`阶段）对应执行另一个Rust函数，它的名称为`typst::typeset`。

```rs
pub fn compile(world: &dyn World) -> SourceResult<Document> {
    // Try to evaluate the source file into a module.
    let module = crate::eval::eval(world, &world.main())?;
    // Typeset the module's content, relayouting until convergence.
    typeset(world, &module.content())
}
```

从代码逻辑上来看，它有明显的先后顺序，似乎与我们所展示的架构略有不同。其`typst::eval`的输出为一个文件模块`module`；其`typst::typeset`仅接受文件的内容`module.content()`并产生一个已经排版好的文档对象`typst::Document`。

== 「`eval`阶段」与「`typeset`阶段」

现在我们介绍Typst的完整架构。

当Typst接受到一个编译请求时，他会使用「解析器」（Parser）从`main`文件开始解析整个项目；对于每个文件，Typst使用「评估器」（Evaluator）执行脚本并得到「内容」；对于每个「内容」，Typst使用「排版引擎」（Typesetting Engine）计算布局与合成样式。

当一切布局与样式都计算好后，Typst将最终结果导出为各种格式的文件，例如PDF格式。

我们回忆上一节讲过的内容，Typst大致上分为四个执行阶段。这四个执行阶段并不完全相互独立，但有明显的先后顺序：

#import "../figures.typ": figure-typst-arch
#align(center + horizon, figure-typst-arch())

我们在上一节着重讲解了前两个阶段。这里，我们着重讲解“表达式求值”阶段与“内容排版”阶段。

事实上，Typst直接在脚本中提供了对应“求值”阶段的函数，它就是我们之前已经介绍过的函数`eval`。你可以使用`eval`函数，将一个字符串对象「评估」为「内容」：

#code(```typ
以代码模式评估：#eval("repr(str(1 + 1))") \
以标记模式评估：#eval("repr(str(1 + 1))", mode: "markup") \
以标记模式评估2：#eval("#show: it => [c] + it + [t];a", mode: "markup")
```)

由于技术原因，Typst并不提供对应“内容排版”阶段的函数，如果有的话这个函数的名称应该为`typeset`。已经有很多地方介绍了潜在的`typeset`函数：
+ #link("https://github.com/andreasKroepelin/polylux")[Polylux], #link("https://github.com/touying-typ/touying")[Touying]等演示文档（PPT）框架需要将一部分内容固定为特定结果的能力。
+ Typst的作者在其博客中提及#link("https://laurmaedje.github.io/posts/frozen-state/")[Frozen State
  ]的可能性。
  + 他提及数学公式的编号在演示文档框架。
  + 即便不涉及用户需求，Typst的排版引擎已经自然存在Frozen State的需求。
+ 本文档也需要`typeset`的能力为你展示特定页面的最终结果而不影响全局状态。

== 延迟执行

架构图中还有两个关键的反向箭头，疑问顿生：这两个反向箭头是如何产生的？

我们首先关注与本节直接相关的「样式化」内容。当`eval`阶段结束时，「`show`」语法将会对应产生一个`styled`元素，其包含了被设置样式的内容，以及设置样式的「回调」：

#code(```typ
内容是：#repr({show: set text(fill: blue); [abc]}) \
样式无法描述，但它在这里：#repr({show: set text(fill: blue); [abc]}.styles)
```)

也就是说`eval`并不具备任何排版能力，它只能为排版准备好各种“素材”，并把素材交给排版引擎完成排版。

这里的「回调」术语很关键：它是一个计算机术语。所谓「回调函数」就是一个临时的函数，它会在后续执行过程的合适时机“回过头来被调用”。例如，我们写了一个这样的「`show`」规则：

#code(```typ
#repr({
  show raw: content => layout(parent => if parent.width > 100pt {
    set text(fill: red); content
  } else {
    content
  })
  `a`
})
```)

这里`parent.width > 100pt`是说当且仅当父元素的宽度大于`100pt`时，才为该代码片段设置红色字体样式。其中，`parent.width`与排版相关。那么，自然`eval`也不知道该如何评估该条件的真正结果。*计算因此被停滞*。

于是，`eval`干脆将整个`show`右侧的函数都作为“素材”交给了排版引擎。当排版引擎计算好了相关内容，才回到评估阶段，执行这一小部分“素材”函数中的脚本，得到为正确的内容。我们可以看出，`show`右侧的函数*被延后执行*可。

这种被延后执行零次、一次或多次的函数便被称为「回调函数」。相关的计算方法也有对应的术语，被称为「延迟执行」。

我们对每个术语咬文嚼字一番，它们都很准确：

1. *「表达式求值」*阶段仅仅“评估”出*「内容排版」*阶段所需的素材.*「评估器」*并不具备排版能力。
2. 对于依赖排版产生的内容，「表达式求值」产生包含*「回调函数」*的内容，让「排版引擎」在合适的时机“回过头来调用”。
3. 相关的计算方法又被称为*「延迟执行」*。因为现在不具备执行条件，所以延迟到条件满足时才继续执行。

现在我们可以理解两个反向箭头是如何产生的了。它们是下一阶段的回调，用于完成阶段之间复杂的协作。评估阶段可能会`import`或`include`文件，这时候会重新让解析器解析文件的字符串内容。排版阶段也可能会继续根据`styled`等元素产生复杂的内容，这时候依靠评估器执行脚本并产生或改变内容。

== 模拟Typst的执行

我们来模拟一遍上述示例的执行，以加深理解：

#code(```typ
#show raw: content => layout(parent => if parent.width < 100pt {
  set text(fill: red); content
} else {
  content
})
#box(width: 50pt, `a`)
`b`
```)

首先进行表达式求值得到：

```typ
#styled((box(width: 50pt, `a`), `b`), styles: content => ..)
```

排版引擎遇到``` `a` ```。由于``` `a` ```是`raw`元素，它「回调」了对应`show`规则右侧的函数。待执行的代码如下：

```typc
layout(parent => if parent.width < 100pt {
  set text(fill: red); `a`
} else {
  `a`
})
```

此时`parent`即为`box(width: 50pt)`。排版引擎将这个`parent`的具体内容交给「评估器」，待执行的代码如下：

```typc
if box(width: 50pt).width < 100pt {
  set text(fill: red); `a`
} else {
  `a`
}
```

由于此时父元素（`box`元素）宽度只有`50pt`，评估器进入了`then`分支，其为代码片段设置了红色样式。内容变为：

```typ
#(box(width: 50pt, {set text(fill: red); `a`}), styled((`b`, ), styles: content => ..))
```

待执行的代码如下：

```typc
set text(fill: red); text("a", font: "monospace")
```

排版引擎遇到``` `a` ```中的`text`元素。由于其是`text`元素，「回调」了`text`元素的「`show`」规则。记得我们之前说过`set`是一种特殊的`show`，于是排版器执行了`set text(fill: red)`。

```typ
#(box(width: 50pt, text(fill: red, "a", ..)), styled((`b`, ), styles: content => ..))
```

排版引擎离开了`show`规则右侧的函数，该函数调用由``` `a` ```触发。同时`set text(fill: red)`规则也被解除，因为离开了相关作用域。

回到文档顶层，待执行的代码如下：

```typc
#show raw: ...
`b`
```

排版引擎遇到``` `b` ```，再度「回调」了对应`show`规则右侧的函数。由于此时父元素（`page`元素，即整个页面）宽度有`500pt`，我们没有为代码片段设置样式。

```typ
#(box(width: 50pt, text(fill: red, "a", ..)), text("b", ..))
```

至此，文档的内容已经准备好「导出」（Export）了。

#pro-tip[
  有时候`show`规则会原地执行，这属于一种细节上的优化，例如：

  #code(```typ
  #repr({ show: it => it; [a] }) \
  #repr({ show: it => [c] + it + [d]; [a] })
  ```)

  这个时候`show`规则不会对应一个`styled`元素。

  这种优化告诉你前面手动描述的过程仅作理解。一旦涉及更复杂的环境，Typst的实际执行过程就会产生诸多变化。因此，你不应该依赖以上某步中排版引擎的瞬间状态。这些瞬间状态将产生「未注明特性」(undocumented details)，并随时有可能在未来被打破。
]


================================================
FILE: src/tutorial/scripting-shape.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "图形排版")

#todo-box[本节处于校对阶段，所以可能存在不完整或错误。]

== 颜色类型

Typst只有一种颜色类型，其由两部分组成。

#figure([
  #block(
    width: 200pt,
    align(left)[
      ```typ
      #color.rgb(87, 127, 230)
       --------- ------------
           |           +-- 色坐标
           +-- 色彩空间对应的构造函数
      ```
    ],
  )
  #text(todo-color)[这里有个图注解]
])


「色彩空间」（color space）是人们主观确定的色彩模型。Typst为不同的色彩空间提供了专门的构造函数。

「色坐标」（chromaticity coordinate）是客观颜色在「色彩空间」中的坐标。给定一个色彩空间，如果某种颜色*在空间内*，那么颜色能分解到不同坐标分量上，并确定每个坐标分量上的数值。反之，选择一个构造函数，并提供坐标分量上的数值，就能构造出这个颜色。

#todo-box[
  chromaticity coordinate这个名词是对的吗，每种色彩空间中的坐标都是这个名字吗？
]

习惯上，颜色的坐标分量又称为颜色的「通道」。从物理角度，Typst使用`f32`存储颜色每通道的值，这允许你对颜色进行较复杂的计算，且计算结果仍然保证较好的误差。

== 色彩空间

RGB是我们使用最多的色彩空间，对应Typst的`color.rgb`函数或`rgb`函数：

#code(```typ
#box(square(fill: color.rgb("#b1f2eb")))
#box(square(fill: rgb(87, 127, 230)))
#box(square(fill: rgb(25%, 13%, 65%)))
```)

除此之外，还支持HSL（`hsl`）、CMYK（`cmyk`）、Luma（`luma`）、Oklab（`oklab`）、Oklch（`oklch`）、Linear RGB（`color.linear-rgb`）、HSV（`color.hsv`）等色彩空间。感兴趣的可以自行搜索并使用。

#pro-tip[
  尽管你可以随意使用这些构造器，但是可能会导致PDF阅读器或浏览器的兼容性问题。它们可能不支持某些色彩空间（或色彩模式）。
]

== 预定义颜色

除此之外，你还可以使用一些预定义的颜色，详见#link("https://typst.app/docs/reference/visualize/color/#predefined-colors")[《Typst Docs: Predefined colors》。]

#code(```typ
#box(square(fill: red, size: 7pt))
#box(square(fill: blue, size: 7pt))
```)

== 颜色计算

Typst较LaTeX的一个有趣的特色是内置了很多方法对颜色进行计算。这允许你基于某个颜色主题（Theme）配置更丰富的颜色方案。这里给出几个常用的函数：

- `lighten/darken`：增减颜色的亮度，参数为绝对的百分比。
- `saturate/desaturate`：增减颜色的饱和度，参数为绝对的百分比。
- `mix`：参数为两个待混合的颜色。

#code(```typ
#show square: box
#set square(size: 15pt)
#square(fill: red.lighten(20%))
#square(fill: red.darken(20%)) \
#square(fill: red.saturate(20%))
#square(fill: red.desaturate(20%)) \
#square(fill: blue.mix(green))
```)

还有一些其他不太常见的颜色计算，详见#link("https://typst.app/docs/reference/visualize/color/#definitions-lighten")[《Typst Docs: Color operations》]。

== 渐变色

你可以以某种方式对Typst中的元素进行渐变填充。这有时候对科学作图很有帮助。

有三种渐变色的构造函数，可以分别构造出线性渐变（Linear Gradient），径向渐变（Radial Gradient），锥形渐变（Conic Gradient）。他们都接受一组颜色，对元素进行颜色填充。

#code(```typ
#let sqr(f) = square(fill: f(
    ..color.map.rainbow))
#stack(
  dir: ltr, spacing: 10pt,
  sqr(gradient.linear),
  sqr(gradient.radial),
  sqr(gradient.conic ))
```)

从字面意思理解`color.map.rainbow`是Typst为你预定义的一个颜色数组，按顺序给出了彩虹渐变的颜色。还有一些其他预定义的颜色数组，详见#link("https://typst.app/docs/reference/visualize/color/#predefined-color-maps")[《Typst Docs: Predefined color maps》]。

== 填充模式

Typst不仅支持颜色填充，还支持按照固定的模式将其他图形对元素进行填充。例如下面的pat定义了一个长为`61.8pt`，宽为`50pt`的图形。将其填充进一个矩形中，填充图形从左至右，从上至下布满矩形内容中。

#code(```typ
#let pat = pattern(size: (61.8pt, 50pt))[
  #place(line(start: (0%, 0%), end: (100%, 100%)))
  #place(line(start: (0%, 100%), end: (100%, 0%)))
]

#rect(fill: pat, width: 100%, height: 60pt, stroke: 1pt)
```)

== 线条

我们学习的第一个图形元素是直线。

`line`函数创建一个直线元素。这个函数接受一系列参数，包括线条的长度、起始点、终止点、颜色、粗细等。

#code(```typ
#line(length: 100%)
#line(end: (50%, 50%))
#line(
  length: 30%, stroke: 2pt + maroon)
```)

除了直线，Typst还支持二次、三次贝塞尔曲线，以及它们和直线的组合。贝塞尔曲线是一种光滑的曲线，由一系列点和控制点组成。

#code(```typ
#curve(
  stroke: blue,
  curve.move((0pt, 20pt)),
  curve.quad((40%, 0pt), (100%, 0pt)),
  curve.line((100%, 20pt)),
  curve.close()
)
```)

== 线条样式

与各类图形紧密联系的类型是「线条样式」（stroke）。线条样式可以是一个简单的「字典」，包含样式数据：

#code(```typ
#set line(length: 100%)
#let rainbow = gradient.linear(
  ..color.map.rainbow)
#stack(
  spacing: 1em,
  line(stroke: 2pt + red),
  line(stroke: (paint: blue, thickness: 4pt, cap: "round")),
  line(stroke: (paint: blue, thickness: 1pt, dash: "dashed")),
  line(stroke: 2pt + rainbow),
)
```)

你也可以使用`stroke`函数来设置线条样式：

#code(```typ
#set line(length: 100%)
#let blue-line-style = stroke(
  paint: blue, thickness: 2pt)
#line(stroke: blue-line-style)
```)

== 填充样式

填充样式（fill）是另一个重要的图形属性。如果一个路径是闭合的，那么它可以被填充。

#code(```typ
#curve(
  fill: blue.lighten(80%),
  stroke: blue,
  curve.move((0pt, 50pt)),
  curve.line((100pt, 50pt)),
  curve.cubic(none, (90pt, 0pt), (50pt, 0pt)),
  curve.close(),
)
```)

== 闭合图形

Typst为你预定义了一些基于贝塞尔曲线的闭合图形元素。下例子中，`#circle`、`#ellipse`、`#square`、`#rect`、`#polygon`分别展示了圆、椭圆、正方形、矩形、多边形的构造方法。

#code(```typ
#box(circle(radius: 12.5pt, fill: blue))
#box(ellipse(width: 50pt, height: 25pt))
#box(square(size: 25pt, stroke: red))
#box(rect(width: 50pt, height: 25pt))
```)

值得注意的是，这些图形元素都允许自适应一个内嵌的内容。例如矩形作为最常用的边框图形：

#code(```typ
#rect[
  Automatically sized \
  to fit the content.
]
```)

== 多边形

多边形是仅使用直线组合而成的闭合图形。你可以使用`polygon`函数构造一个多边形。

#code(```typ
#polygon(
  fill: blue.lighten(80%),
  stroke: blue,
  (20%, 0pt),
  (60%, 0pt),
  (80%, 2cm),
  (0%,  2cm),
)
```)

`polygon`不允许内嵌内容。

== 外部图形库

很多时候我们只需要在文档中插入分割线（直线）和文本框（带文本的矩形）。但是，若有需求，一些外部图形库可以帮助你绘制更复杂的图形：

+ 树形图：#link("https://typst.app/universe/package/syntree")[typst-syntree]
+ 拓扑图：#link("https://typst.app/universe/package/fletcher")[typst-fletcher]
+ Canvas通用图形库：#link("https://typst.app/universe/package/cetz")[cetz]

这些库也是很好的参考资料，你可以通过查看源代码来学习如何绘制复杂的图形。


================================================
FILE: src/tutorial/scripting-style.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "选择器与样式")

#todo-box[本节处于校对阶段，所以可能存在不完整或错误。]

== 「样式化」内容

当我们有一个`repr`玩具的时候，总想着对着各种各样的对象使用`repr`。我们在上一节讲解了「`set`」和「`show`」语法。现在让我们稍微深挖一些。

「`set`」是什么，`repr`一下：

#code(```typ
#repr({
  [a]; set text(fill: blue); [b]
})
```)

「`show`」是什么，`repr`一下：

#code(```typ
#repr({
  [b]; show raw: set text(fill: red)
  [a]
})
```)

我们知道`set text(fill: blue)`是`show: set text(fill: blue)`的简写，因此「`set`」语法和「`show`」语法都可以统合到第二个例子来理解。

对于第二个例子，我们发现`show`语句之后的内容都被重新包裹在`styled`元素中。虽然我们不知道`styled`做了什么事情，但是简单的事实是：

#code(```typ
该元素的类型是：#type({show: set text(fill: blue)}) \
该元素的构造函数是：#({show: set text(fill: blue)}).func()
```)

原来，你也是内容。从图中，我们可以看到被`show`过的内容会被封装成「样式化」内容，即图中构造函数为`styled`的内容。

关于`styled`的知识便涉及到Typst的核心架构。

// == 「可定位」的内容

// 在过去的章节中，我们了解了评估结果的具体结构，也大致了解了排版引擎的工作方式。

// 接下来，我们介绍一类内容的「可定位」（Locatable）特征。你可以与前文中的「可折叠」（Foldable）特征对照理解。

// 一个内容是可定位的，如果它可以以某种方式被索引得到。

// 如果一个内容在代码块中，并未被使用，那么显然这种内容是不可定位的。

// ```typ
// #{ let unused-content = [一段不可定位的内容]; }
// ```

// 理论上文档中所有内容都是可定位的，但由于*性能限制*，Typst无法允许你定位文档中的所有内容。

// 我们已经学习过元素函数可以用来定位内容。如下：

// #code(````typ
// #show heading: set text(fill: blue)
// = 蓝色标题
// 段落中的内容保持为原色。
// ````)

// 接下来我们继续学习更多选择器。

== 内容的「样式」

我们接下来循着文本样式的脉络学习排版内容的语法。

重点1：文本是段落的重要组成部分，与之对应的内容函数是`text`。

我们知道一个函数可以有各种参数。那么我们从函数视角来看，内容的样式便由创建时参数的内容决定。例如，我们想要获得一段蓝色的文本：

#code(```typ
#text("一段文本", fill: blue)
```)

`fill: blue`是函数的参数，指定了文本的样式。

这个视角有助于我们更好的将对「样式」的需求转换为对函数的操控。例如，我们可以使用函数的`with`方法，获得一个固定样式的文本函数：

#code(```typ
#let warning = text.with(fill: orange)
#warning[警告，你做个人吧]
```)

== 上下文有关表达式

// contextual expression

在介绍重要语法之前，我们先来一道开胃菜。

#code(```typ
#context text.size
```)

== 「`set`」语法 <grammar-set>

重点2：一个段落主要是一个内容序列，其中有可能很多个文本。

#code(```typ
#repr([不止包含......一个文本！])
```)

假设我们想要让一整个段落都显示成蓝色，显然不能将文本一个个用`text.with(fill: blue)`构造好再组装起来。这个时候「`set`」语法出手了。「`set`」关键字后可以跟随一个函数调用，为影响范围内所有函数关联的对应内容设置对应参数。

#code(```typ
#set text(fill: blue)
一段很长的话可能不止包含......一个文本！
- 似乎，列表中也有文本。
```)

重点：「`set`」的影响范围是其所在「作用域」内的后续内容。

我们紧接着来讲与之相关的，Typst中最重要的概念之一：「作用域」。

== 「内容」是一棵树

重点3：「内容」是一棵树，这意味着你可以“攀树而行”。

Typst对代码块有着的一系列语法设计，让代码块非常适合描述内容。又由于作用域的性质，最终代码块让「内容」形成为一颗树。

「内容」是一棵树。一个`main.typ`就是「内容」的一再嵌套。即便不使用任何标记语法，你也可以创建一个文档：

#code.with(al: top)(```typ
#let main-typ() = {
  heading("生活在Content树上")
  {
    [现代社会以海德格尔的一句]
    [“一切实践传统都已经瓦解完了”]
    [为嚆矢。]
  } + parbreak()
  [...] + parbreak()
  [在孜孜矻矻以求生活意义的道路上，对自己的期望本就是在与家庭与社会对接中塑型的动态过程。]
  [而我们的底料便是对不同生活方式、不同角色的觉感与体认。]
  [...]
}
#main-typ()
```)

// == 「样式链」

// 理解「作用域」对

== 「`show`」语法 <grammar-show>

「`set`」语法是「`show set`」语法的简写。因此，「`show`」语法显然可以比`set`更强大。<grammar-show-set>

#code(```typ
#show: set text(fill: blue)
wink!
```)

我们可以看到「`show`」语法由两部分组成，由冒号分隔。

`show`的右半部分是一个函数，表示选择文档的一部分以作修改。

#pro-tip[
  你可能会问，先姑且不问函数要怎么写，难道`set text(fill: blue)`也能算一个函数吗？

  事实上，`set`规则是「内容类型」，它接受一个样式和一个内容，返回一个`styled`内容：

  #code(```typ
  #let x = [#set text(fill: blue)]
  #x.func()
  ```)

  以下使用方法非常黑客，请最好不要在你的文档中包含这种代码。仅用于理解：

  #code(```typ
  #let styled = [#set text(blue)].func()
  #let styles = text("", red).styles
  #styled([Red Text], styles)
  ```)

  1. 第一行代码，我们说`func`方法返回内容函数本身，这里便返回了一个内部的函数`styled`。
  2. 第二行代码，这里我们从`text`内容上找到了它关于设置红色文本的样式（参数）。
  3. 第三行代码，把一个内容及一个无论如何从某处得到了的样式传递给`styled`函数。
  4. 最终我们构造出了一个真实的红色文本。

]

`show`的左半部分是选择器，表示选择文档的一部分以作修改。它作用于「作用域」内的*后续*所有*被选择器选中*的内容。

如果选择器为空，则默认选择*后续所有*内容。这也是「`set`」语法对应规则的原理。如果选择器不为空，那么因为我们还没讲解选择器，所以这里不作过多讲解。

但有一种选择器比较简单易懂。我们可以将内容函数作为选择器，选择相应内容作影响。

以下脚本设置所有代码片段的颜色：

#code(```typ
#show raw: set text(fill: blue)
被秀了的`代码片段`！
```)

以下脚本设置所有数学公式的颜色，但同时也修改代码片段的颜色：

// todo: ugly code
#code(```typ
#show raw: set text(red)
#show math.equation: set text(blue)
#let dif2(x) = math.op(math.Delta + $x$)
一个公式：$ sum_(f in S(x))
  #`refl`;(f) dif2(x) $
```)

我们说，`show`的右半部分是一个函数，表示选择文档的一部分以作修改。除了直接应用`set`，应该可以有很多其他操作。现在是时候解锁Typst强大能力了。

这个函数接受一个参数：参数是*未打包*（unpacked）的内容；这个函数返回一个*任意*内容。

以下示例说明它接受一个*未打包*的内容。对于代码片段，我们使用「`show`」语法择区其中第二行：

#code(````typ
#show raw: it => it.lines.at(1)
获取代码片段第二行内容：```typ
#{
set text(fill: true)
}
```
````)

在《内容类型的特性》中，我们所接触到的*已经打包*（packed）的代码片段并不包含`lines`字段。在打包后，内部大部分信息已经被屏蔽了。

以下示例说明它可以返回*任意*内容。这里我们选择语言为`my-calc`的代码片段，执行并返回一个*非代码片段*：

#code(````typ
#show raw.where(lang: "my-calc"): it => eval(it.text)
嵌入一个计算器语言，计算`1*2+2*(2+3)`：```my-calc 1*2+2*(2+3)```
````)

由于`show`的右半部分只要求接受内容并返回内容，我们可以有非常优雅的写法，使用一些天然满足要求的函数。

以下规则将每个代码片段用方框修饰：

#code(````typ
#show raw: rect
``` QwQ ```
````)

以下规则将每个代码片段用蓝色方框修饰：

#code(````typ
#show raw: rect.with(stroke: blue)
``` QwQ ```
````)

// == 内容的「实例化过程」

// 通过`query`我们获得同一个内容上更多的信息，即「样式」属性，即内容上的那些可选函数参数。

// 根据上述例子，我们来理解为什么它只提供了语法属性。假设只看`= 123`这5个字符，显然我们从*语法*上只能获得两个信息：
// + 它是一级标题。
// + 它的内容是`123`。

// 与之相对，当一个标题真正被放置到一个具体的「上下文」中时，才能真正关联与之相关的样式属性。例如，标题的`numbering`字段是与上下文相关的。

// - location()

// == import/include/styled

// == 「`include`」语法 <grammar-include>

// 介绍`read`，`eval(mode)`。

// 路径分为相对路径和绝对路径。如果是相对路径，`read("other-file.typ")`相当于在*当前*文件夹寻找对对应的文件。

// `include`的本质就是`eval(read("other-file.typ", mode: "markup"))`，获得一个「内容」，*插入到原地*。

// 假设我们有一个文件：

// #code(```typ
// // 以下是other-file.typ文件的内容
// 一段文本
// #set text(fill: red)
// 另一段文本
// ```)

// 那么```typ #include "other-file.typ"```将获得该文件的「内容」，*插入到原地*。

// #code(```typ
// #{
//   set text(fill: blue)
//   include "other-file.typ"
// }
// #include "other-file.typ"
// ```)

// `include`的文件是一个「内容块」，自带一个作用域。

== 文本选择器 <grammar-text-selector>

你可以使用「字符串」或「正则表达式」（`regex`）匹配文本中的特定内容，例如为`c++`文本特别设置样式：

#code(````typ
#show "cpp": strong(emph(box("C++")))
在古代，cpp是一门常用语言。
````)

这与使用正则表达式的效果相同：<grammar-regex-selector>

#code(````typ
#show regex("cp{2}"): strong(emph(box("C++")))
在古代，cpp是一门常用语言。
````)

关于正则表达式的知识，推荐在#link("https://regex101.com")[Regex 101]中继续学习。

这里讲述一个关于`regex`选择器的重要知识。当文本被元素选中时，会创建一个不可见的分界，导致分界之间无法继续被正则匹配：

#code(````typ
#show "ab": set text(fill: blue)
#show "a": set text(fill: red)
ababababababa
````)

因为`"a"`规则比`"ab"`规则更早应用，每个`a`都被单独分隔，所以`"ab"`规则无法匹配到任何本文。

#code(````typ
#show "a": set text(fill: red)
#show "ab": set text(fill: blue)
ababababababa
````)

虽然每个`ab`都被单独分隔，但是`"a"`规则可以继续在分界内继续匹配文本。

这个特征在设置文本的字体时需要特别注意：

为引号单独设置字体会导致错误的排版结果。因为句号与双引号之间产生了分界，使得Typst无法应用标点挤压规则：

#code(````typ
#show "”": it => {
  set text(font: "KaiTi")
  highlight(it, fill: yellow)
}
“无名，万物之始也；有名，万物之母也。”
````)

以下正则匹配也会导致句号与双引号之间产生分界，因为没有对两个标点进行贪婪匹配：

#code(````typ
#show regex("[”。]"): it => {
  set text(font: "KaiTi")
  highlight(it, fill: yellow)
}
“无名，万物之始也；有名，万物之母也。”
````)

以下正则匹配没有在句号与双引号之间创建分界。考虑两个标点的字体设置规则，Typst能排版出这句话的正确结果：

#code(````typ
#show regex("[”。]+"): it => {
  set text(font: "KaiTi")
  highlight(it, fill: yellow)
}
“无名，万物之始也；有名，万物之母也。”
````)

== 标签选择器 <grammar-label-selector>

基本上，任何元素都包含文本。这使得你很难对一段话针对性排版应用排版规则。「标签」有助于改善这一点。标签是「内容」，由一对「尖括号」（`<`和`>`）包裹：

#code(````typ
一句话 <some-label>
````)

「标签」可以选中恰好在它*之前*的一个内容。示例中，`<some-label>`选中了文本内容`一句话`。

也就是说，「标签」无法选中在它*之前*的多个内容。以下选择器选中了`#[]`后的一句话：

#code(````typ
#show <一句话>: set text(fill: blue)
#[一句话。]还是一句话。 <一句话>

另一句话。
````)

这是因为`#[一句话。]`被分隔为了单独的内容。

我们很难判断一段话中有多少个内容。因此为了可控性，我们可以使用内容块将一段话括起来，然后使用标签准确选中这一整段话：

#code(````typ
#show <一整段话>: set text(fill: blue)
#[
  $lambda$语言是世界上最好的语言。#[]还是一句话。
] <一整段话>

另一段话。
````)

== 选择器表达式 <grammar-selector-exp>

任意「内容」可以使用「`where`」方法创建选中满足条件的选择器。

例如我们可以选中二级标题：

#code(````typ
#show heading.where(level: 2): set text(fill: blue)
= 一级标题
== 二级标题
````)

这里`heading`是一个元素，`heading.where`创建一个选择器：

#code(````typ
选择器是：#repr(heading.where(level: 2)) \
类型是：#type(heading.where(level: 2))
````)

同理我们可以选中行内的代码片段而不选中代码块：

#code(````typ
#show raw.where(block:false): set text(fill: blue)
`php`是世界上最好的语言。
```
typst也是。
```
````)

// == 「`numbering`」函数

// 略

== 总结

本节仅以文本、代码块和内容块为例讲清楚了文件、作用域、「set」语法和「show」语法。为了拓展广度，你还需要查看《基本参考》中各种元素的用法，这样才能随心所欲排版任何「内容」。

== 习题

// == 字数统计

// 从一个典型程序开始，这个程序基本解决我们一个需求：完成一段内容的字数统计。按照惯例，这一个程序涉及了本节所有的知识点。

// ```typ
// #let plain-text(it) = {
//   if it.has("children") {
//     ("", ..it.children.map(plain-text)).join()
//   } else if it.has("child") {
//     plain-text(it.child)
//   } else if it.has("body") {
//     plain-text(it.body)
//   } else if it.has("text") {
//     it.text
//   } else if it.func() == smartquote {
//     if it.double { "\"" } else { "'" }
//   } else {
//     " "
//   }
// }
// ```

// 以及基于其上实现一个字数统计函数：

// ```typ
// #let word-count(it) = {
//   plain-text(it).replace(regex("\p{hani}"), "\1 ").split().len()
// }
// ```

// 以下是该函数的表现：

// #code.with(scope: code-scope)(```typ
// #let show-me-the(it) = {
//   repr(plain-text(it))
//   [ 的字数统计为 ]
//   repr(word-count(it))
// }
// #show-me-the([])\
// #show-me-the([一段文本]) \
// #show-me-the([A bc]) \
// #show-me-the([
//   - 列表项1
//   - 列表项2
// ])
// ```)

#let plain-text(it) = {
  if it.has("children") {
    ("", ..it.children.map(plain-text)).join()
  } else if it.has("child") {
    plain-text(it.child)
  } else if it.has("body") {
    plain-text(it.body)
  } else if it.has("text") {
    it.text
  } else if it.func() == smartquote {
    if it.double {
      "\""
    } else {
      "'"
    }
  } else {
    " "
  }
}
#let word-count(it) = {
  plain-text(it).replace(regex("\p{hani}"), "\1 ").split().len()
}

#let code-scope = (plain-text: plain-text, word-count: word-count)

#let q1 = ````typ
#let plain-text(it) = {
  if type(it) == str {
    it
  } else if it.has("children") {
    ("", ..it.children.map(plain-text)).join()
  } else if it.has("child") {
    plain-text(it.child)
  } else if it.has("body") {
    plain-text(it.body)
  } else if it.has("text") {
    it.text
  } else if it.func() == smartquote {
    if it.double {
      "\""
    } else {
      "'"
    }
  } else {
    " "
  }
}
#let main-typ() = {
  heading("生活在Content树上")
  {
    [现代社会以海德格尔的一句]
    [“一切实践传统都已经瓦解完了”]
    [为嚆矢。]
  } + parbreak()
  [...] + parbreak()
  [在孜孜矻矻以求生活意义的道路上，对自己的期望本就是在与家庭与社会对接中塑型的动态过程。]
  [而我们的底料便是对不同生活方式、不同角色的觉感与体认。]
  [...]
}
#plain-text(main-typ())
````

#exercise[
  实现内容到字符串的转换`plain-text`：对于文中出现的`main-typ()`内容，它输出：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ````typ
#let plain-text(it) = {
  if type(it) == str {
    it
  } else if it.has("children") {
    ("", ..it.children.map(plain-text)).join()
  } else if it.has("child") {
    plain-text(it.child)
  } else if it.has("body") {
    plain-text(it.body)
  } else if it.has("text") {
    it.text
  } else if it.func() == smartquote {
    if it.double {
      "\""
    } else {
      "'"
    }
  } else {
    " "
  }
}
#let word-count(it) = {
  plain-text(it).replace(regex("\p{hani}"), "\1 ").split().len()
}
#let main-typ() = {
  heading("生活在Content树上")
  {
    [现代社会以海德格尔的一句]
    [“一切实践传统都已经瓦解完了”]
    [为嚆矢。]
  } + parbreak()
  [...] + parbreak()
  [在孜孜矻矻以求生活意义的道路上，对自己的期望本就是在与家庭与社会对接中塑型的动态过程。]
  [而我们的底料便是对不同生活方式、不同角色的觉感与体认。]
  [...]
}
#word-count(main-typ())
````

#exercise[
  实现字数统计`word-count`：对于文中出现的`main-typ()`内容，它输出：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#exercise[
  思考题：`plain-text`有何局限性？为什么在`show`规则影响下，`word-count`输出分别为4和5？

  #code.with(scope: code-scope)(```typ
  #let show-me-the(it) = {
    it + [ 的字数统计为#word-count(it) ]
  }
  #show-me-the([#show raw: it => {"123"; it}; `一段文本`]) \
  #show-me-the([#show: it => {"123"; it}; 一段文本])
  ```)
][
  #q1
]


================================================
FILE: src/tutorial/scripting-variable.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "变量与函数")

== 变量声明 <grammar-var-decl>

变量是存储“字面量”的一个个容器。它相当于为一个个字面量取名，以方便在脚本中使用。

如下语法，「变量声明」表示使得`x`的内容与`"Hello world!!"`相等。我们对语法一一翻译：

#code(```typ
   #let    x     =  "Hello world!!"
// ^^^^    ^     ^  ^^^^^^^^^^^^^^^^
//  令    变量名  为    初始值表达式
```)

#pro-tip[
  同时我们看见输出的文档为空，这是因为「变量声明」本身的值是`none`。
]

「变量声明」一共分为3个有效部分。

+ `let`关键字：告诉Typst接下来即将开启一段「声明」。在英语中let是"令"的意思。
+ #term("variable identifier")、#mark("=")：标识符是变量的“名称”。「变量声明」后续的位置都可以通过标识符引用该变量。
+ #term("initialization expression")：#mark("=")告诉Typst变量初始等于一个表达式的值。该表达式在编译领域有一个专业术语，称为#term("initialization expression")。这里，#term("initialization expression")可以为任意表达式，请参阅

建议标识符简短且具有描述性。尽管标识符中可以包含中文等unicode字符，但仍建议标识符中仅含英文与#mark("hyphen")。

// #link(<scripting-expression>)[表达式小节]。

// 「变量声明」可以没有初始值表达式：

// #code(```typ
// #let x
// #repr(x)
// ```)

// 事实上，它等价于将`x`初始化为`none`。

// #code(```typ
// #let x = none
// #repr(x)
// ```)

// 尽管Typst允许你不写初始值表达式，本书还是建议你让所有的「变量声明」都具有初始值表达式。因为初始值表达式还告诉阅读你代码的人这个变量可能具有什么样的类型。

「变量声明」后续的位置都可以继续使用该变量，取决于「作用域」。
// + 标识符以Unicode字母、Unicode数字和#mark("_")开头。以下是示例的合法变量名：
//   ```typ
//   // 以英文字母开头，是Unicode字母
//   #let a; #let z; #let A; #let Z;
//   // 以汉字开头，是Unicode字母
//   #let 这;
//   // 以下划线开头
//   #let _;
//   ```
// + 标识符后接有限个Unicode字母、Unicode数字、#mark("hyphen")和#mark("_")。以下是示例的合法变量名：
//   ```typ
//   // 纯英文变量名，带连字号
//   #let alpha-test; #let alpha--test;
//   // 纯中文变量名
//   #let 这个变量; #let 这个_变量; #let 这个-变量;
//   // 连字号、下划线在多种位置
//   #let alpha-; // 连字号不能在变量名开头位置
//   #let _alpha; #let alpha_;
//   ```
// + 特殊规则：标识符仅为#mark("_")时，不允许在后续位置继续使用。
//   #code(```typ
//   #let _ = 1;
//   // 不能编译：#_
//   ```)
//   该标识符被称为#term("placeholder")。
// + 特殊规则：标识符不允许为`let`、`set`、`show`等关键字。
//   #code(```typ
//   // 不能编译：
//   // #let let = 1;
//   ```)

#pro-tip[
  关于作用域，你可以参考#(refs.content-scope-style)[《内容、作用域与样式》]。
]

变量可以重复输出到文档中：

#code(```typ
#let x = "阿吧"
#x#x，#x#x
```)

任意时刻都可以将任意类型的值赋给一个变量。上一节所提到的「内容块」也可以赋值给一个变量。

#code(```typ
#let y = [一段文本]; #y \
#(y = 1) /* 重新赋值为一个整数 */ #y \
```)

任意时刻都可以重复定义相同变量名的变量，但是之前被定义的变量将无法再被使用：

#code(```typ
#let y = [一段文本]; #y \
#let y = 1; /* 重新声明为一个整数 */ #y \
```)

== 成员

// ，它们是：
// + #term("array literal", postfix: "。")
// + #term("dictionary literal", postfix: "。")

Typst提供了一系列「成员」和「方法」访问字面量、变量与函数中存储的“信息”。

// 其实在上一节（甚至是第二节），你就已经见过了「成员」语法。<grammar-member-exp>你可以通过「点号」获得代码块的“text”（文本内容）：

// #code(```typ
// #repr(`OvO`.text), #type(`OvO`), #type(`OvO`.text)
// ```)

每个类型有哪些「成员」是由Typst决定的。你需要逐渐积累经验以知晓这些「成员」的分布，才能更快地通过访问成员快速编写出收集和处理信息的脚本。(todo: 建议阅读《参考：XXX》)

当然，为防你不知道，大家不都是死记硬背的：有软件手段帮助你使用这些「成员」。许多编辑器都支持LSP（Language Server Protocol，语言服务），例如VSCode安装Tinymist LSP。当你对某个对象后接一个点号时，编辑器会自动为你做代码补全。

#figure(image("./IDE-autocomplete.png", width: 120pt), caption: [作者使用编辑器作代码补全的精彩瞬间。])

从图中可以看出来，该代码片段「对象」上有七个「成员」。特别是“text”成员赫然立于其中，就是它了。除了「成员」列表，编辑器还会告诉你每个「成员」的作用，以及如何使用。这时候只需要选择一个「成员」作为补全结果即可。

=== 函数声明 <grammar-func-decl>

「函数声明」也由`let`关键字开始。如果你仔细对比，可以发现它们在语法上是一致的。

如下语法，「函数声明」表示使得`f(x, y)`的内容与右侧表达式的值相等。我们对语法一一翻译：

```typ
   #let    f(x, y)      = [两个值#(x)和#(y)偷偷混入了我们内容之中。]
// ^^^^    ^^^^^^^      ^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
//  令  函数名(参数列表)  为               一段内容
```

「函数声明」一共分为4个部分，相较于「变量声明」，多了一个参数列表。

参数列表中参数的个数可以有零个，一个，至任意多个，由逗号分隔。每个参数都是一个单独的#term("parameter identifier")。

```typ
// 零个参数，一个参数，两个参数，..
    #f(),   #f(x), #f(x, y)
```

#term("parameter identifier")的规则与功能与#term("variable identifier")相似。为参数取名是为其能在函数体中使用。

视角挪到等号右侧。#term("function body expression")的规则与功能与#term("initialization expression")相似。#term("function body expression")可以任意使用参数列表中的“变量”，并组合出一个表达式。组合出的表达式的值就是函数调用的结果。

结合例子理解函数的作用。将对应参数应用于函数可以取得对应的结果：

#code(```typ
#let f(x, y) = [两个值#(x)和#(y)偷偷混入了我们内容之中。]

#let x = "Hello world!!"
#let y = [一段文本]
#f(repr(x), y)
```)

其中```typ #f(repr(x), y)```的执行过程是这样的：

```typ
#f(repr(x), y) // 转变为
#f([\"Hello world!!\"], [一段文本])
```

注意，此时我们进入右侧表达式。

```typ
#[两个值#(x)和#(y)偷偷混入了我们内容之中。] // 转变为
#[两个值#([\"Hello world!!\"])和#([一段文本])偷偷混入了我们内容之中。]
```

最后整理式子得到，也即是我们看到的输出：

```typ
两个值\"Hello world!!\"和一段文本偷偷混入了我们内容之中。
```

这里仅作较为基础的理解。在下一节，等我们学会了数组和字典，我们可以定义更复杂的函数。

// 请体会我们在介绍「变量声明」时的特殊措辞，并与「函数声明」的语法描述相对应。

// - 以下「变量声明」表示使得`x`的内容与`"Hello world!!"`相等。

//   ```typ
//   #let x = "Hello world!!"
//   ```

// - 以下「函数声明」表示使得`f(x, y)`的内容与经过计算后的`[两个值#(x)和#(y)偷偷混入了我们内容之中。]`相等。

//   ```typ
//   #let f(x, y) = [两个值#(x)和#(y)偷偷混入了我们内容之中。]
//   ```

== 函数闭包 <grammar-closure>

「闭包」是一类特殊的函数，又称为匿名函数。一个简单的闭包如下：

#code(```typ
#let f = (x, y) => [#(x)和#(y)。]
#f("我", "你")
```)

我们可以看到其以箭头为体，两侧为参数列表和函数体。不像「函数声明」，它不需要取名。

闭包以其匿名特征，很适合就地使用，让我们不必为一个暂时使用的函数起名，例如作为「回调」函数。我们将会在下一章经常使用「回调」函数。例如，Typst提供了「`show`」语法，其可以接收一个选择器和一个函数，并将其作用范围内被选择器选中的内容都使用给定函数处理：

#code(```typ
#let style(body) = text(blue, underline(body))
#show heading.where(level: 3): style
=== 标题
```)

但是，等价地，此时「函数声明」不如「闭包声明」优美：

#code(```typ
#show heading.where(level: 3): it => text(blue, underline(it))
=== 标题
```)

== 方法 <grammar-method-exp>

「方法」是一种特殊的「成员」。准确来说，如果一个「成员」是一个对象的函数，那么它就被称为该对象的「方法」。

来看以下代码，它们输出了相同的内容，事实上，它们是*同一*「函数调用」的不同写法：

#code(```typ
#let x = "Hello World"
#let str-split = str.split
#str-split(x, " ") \
#str.split(x, " ") \
#x.split(" ")
```)

第三行脚本含义对照如下。之前已经学过，这正是「函数调用」的语法：

```typ
#(        str-split(         x,  " "   ))
// 调用  字符串拆分函数，参数为 变量x和空格
```

与第三行脚本相比，第四行脚本仍然是在做「函数调用」，只不过在语法上更为紧凑。

第五行脚本则更加简明，此即「方法调用」。约定`str.split(x, y)`可以简写为`x.split(y)`，如果：
+ 对象`x`是`str`类型，且方法`split`是`str`类型的「成员」。
+ 对象`x`用作`str.split`调用的第一个参数。

「方法调用」即一种特殊的「函数调用」规则（语法糖），在各编程语言中广泛存在。其大大简化了脚本。但你也可以选择不用，毕竟「函数调用」一样可以完成所有任务。

#pro-tip[
  这里有一个问题：为什么Typst要引入「方法」的概念呢？主要有以下几点考量。

  其一，为了引入「方法调用」的语法，这种语法相对要更为方便和易读。对比以下两行，它们都完成了获取`"Hello World"`字符串的第二个单词的第一个字母的功能：

  #code(
    ```typ
    #"Hello World".split(" ").at(1).split("").at(1)
    #array.at(str.split(array.at(str.split("Hello World", " "), 1), ""), 1)
    ```,
    al: top,
  )

  可以明显看见，第二行语句的参数已经散落在括号的里里外外，很难理解到底做了什么事情。

  其二，相比「函数调用」，「方法调用」更有利于现代IDE补全脚本。你可以通过`.split`很快定位到“字符串拆分”这个函数。

  其三，方便用户管理相似功能的函数。不仅仅是字符串可以拆分，似乎内容及其他许多类型也可以拆分。如果一一为它们取不同的名字，那可就太头疼了。相比，`str.split`就简单多了。要知道，很多程序员都非常头痛为不同的变量和函数取名。
]

== 总结

// Typst如何保证一个简单函数甚至是一个闭包是“纯函数”？

// 答：1. 禁止修改外部变量，则捕获的变量的值是“纯的”或不可变的；2. 折叠的对象是纯的，且「折叠」操作是纯的。

// Typst的多文件特性从何而来？

// 答：1. import函数产生一个模块对象，而模块其实是文件顶层的scope。2. include函数即执行该文件，获得该文件对应的内容块。

// 基于以上两个特性，Typst为什么快？

// + Typst支持增量解析文件。
// + Typst所有由*用户声明*的函数都是纯的，在其上的调用都是纯的。例如Typst天生支持快速计算递归实现的fibnacci函数：

//   #code(```typ
//   #let fib(n) = if n <= 1 { n } else { fib(n - 1) + fib(n - 2) }
//   #fib(42)
//   ```)
// + Typst使用`include`导入其他文件的顶层「内容块」。当其他文件内容未改变时，内容块一定不变，而所有使用到对应内容块的函数的结果也一定不会因此改变。

// 这意味着，如果你发现了Typst中与一般语言的不同之处，可以思考以上种种优势对用户脚本的增强或限制。

== 总结

#todo-box[总结]

== 习题

#todo-box[习题]


================================================
FILE: src/tutorial/stateful/q0.typ
================================================

#let curr-heading = state("curr-heading", ())

#set text(size: 8pt)

#let set-heading(content) = {
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  set page(header: {
    set text(size: 5pt);
    [这是页眉]
  })

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-heading
#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。


================================================
FILE: src/tutorial/stateful/q1.typ
================================================

#set text(size: 8pt)

#let calc-headings(headings) = {
  let max-page-num = calc.max(..headings.map(it => it.location().page()))
  let first-headings = (none,) * max-page-num
  let last-headings = (none,) * max-page-num

  for h in headings {
    if first-headings.at(h.location().page() - 1) == none {
      first-headings.at(h.location().page() - 1) = h
    }
    last-headings.at(h.location().page() - 1) = h
  }

  let res-headings = (none,) * max-page-num
  for i in range(res-headings.len()) {
    res-headings.at(i) = if first-headings.at(i) != none {
      first-headings.at(i)
    } else {
      last-headings.at(i) = last-headings.at(
        calc.max(0, i - 1),
        default: none,
      )
      last-headings.at(i)
    }
  }

  (
    res-headings,
    if max-page-num > 0 {
      last-headings.at(-1)
    },
  )
}

#let get-heading-at-page() = {
  let (headings, last-heading) = calc-headings(query(heading.where(level: 2)))
  headings.at(here().page() - 1, default: last-heading)
}

#let set-heading(content) = {
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  set page(
    header: context {
      set text(size: 5pt)
      emph(get-heading-at-page())
    },
  )

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-heading
#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。


================================================
FILE: src/tutorial/stateful/s1.typ
================================================

#let curr-heading = state("curr-heading", ())

#set text(size: 8pt)

#let first-heading = state("first-heading", (:))
#let last-heading = state("last-heading", (:))

#let find-headings(headings, page-num) = if page-num > 0 {
  headings.at(str(page-num), default: find-headings(headings, page-num - 1))
}

#let get-heading-at-page() = {
  let first-headings = first-heading.final()
  let last-headings = last-heading.at(here())
  let page-num = here().page()

  first-headings.at(str(page-num), default: find-headings(last-headings, page-num))
}

#let update-heading-at-page(h) = context {
  let k = str(here().page())
  last-heading.update(it => {
    it.insert(k, h)
    it
  })
  first-heading.update(it => {
    if k not in it {
      it.insert(k, h)
    }
    it
  })
}

#let set-heading(content) = {
  show heading.where(level: 2): it => {
    it
    update-heading-at-page(it.body)
  }
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  set page(
    header: context {
      set text(size: 5pt)
      emph(get-heading-at-page())
    },
  )

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-heading
#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。



================================================
FILE: src/tutorial/stateful/s2.typ
================================================

#let curr-heading = state("curr-heading", ())

#set text(size: 8pt)

#let set-heading(content) = {
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。



================================================
FILE: src/tutorial/stateful/s3.typ
================================================

#let curr-heading = state("curr-heading", ())

#set text(size: 8pt)

#let set-heading(content) = {
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-heading
#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。



================================================
FILE: src/tutorial/stateful-v0.12.0/q0.typ
================================================

#let curr-heading = state("curr-heading", ())

#set text(size: 8pt)

#let set-heading(content) = {
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  // @typstyle off
  set page(header: {
    set text(size: 5pt);
    [这是页眉]
  })

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-heading
#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。


================================================
FILE: src/tutorial/stateful-v0.12.0/q1.typ
================================================

#set text(size: 8pt)

#let calc-headings(headings) = {
  let max-page-num = calc.max(..headings.map(it => it.location().page()))
  let first-headings = (none,) * max-page-num
  let last-headings = (none,) * max-page-num

  for h in headings {
    if first-headings.at(h.location().page() - 1) == none {
      first-headings.at(h.location().page() - 1) = h
    }
    last-headings.at(h.location().page() - 1) = h
  }

  let res-headings = (none,) * max-page-num
  for i in range(res-headings.len()) {
    res-headings.at(i) = if first-headings.at(i) != none {
      first-headings.at(i)
    } else {
      last-headings.at(i) = last-headings.at(
        calc.max(0, i - 1),
        default: none,
      )
      last-headings.at(i)
    }
  }

  (
    res-headings,
    if max-page-num > 0 {
      last-headings.at(-1)
    },
  )
}

#let get-heading-at-page() = {
  let (headings, last-heading) = calc-headings(query(heading.where(level: 2)))
  headings.at(here().page() - 1, default: last-heading)
}

#let set-heading(content) = {
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  // @typstyle off
  set page(header: context {
    set text(size: 5pt)
    emph(get-heading-at-page())
  })

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-heading
#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。


================================================
FILE: src/tutorial/stateful-v0.12.0/s1.typ
================================================

#let curr-heading = state("curr-heading", ())

#set text(size: 8pt)

#let first-heading = state("first-heading", (:))
#let last-heading = state("last-heading", (:))

#let find-headings(headings, page-num) = if page-num > 0 {
  headings.at(str(page-num), default: find-headings(headings, page-num - 1))
}

#let get-heading-at-page() = {
  let first-headings = first-heading.final()
  let last-headings = last-heading.get()
  let page-num = here().page()

  first-headings.at(str(page-num), default: find-headings(last-headings, page-num))
}

#let update-heading-at-page(h) = context {
  let k = str(here().page())
  last-heading.update(it => {
    it.insert(k, h)
    it
  })
  first-heading.update(it => {
    if k not in it {
      it.insert(k, h)
    }
    it
  })
}

#let set-heading(content) = {
  show heading.where(level: 2): it => {
    it
    update-heading-at-page(it.body)
  }
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  set page(
    header: context {
      set text(size: 5pt)
      emph(get-heading-at-page())
    },
  )

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-heading
#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。



================================================
FILE: src/tutorial/stateful-v0.12.0/s2.typ
================================================

#let curr-heading = state("curr-heading", ())

#set text(size: 8pt)

#let set-heading(content) = {
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。



================================================
FILE: src/tutorial/stateful-v0.12.0/s3.typ
================================================

#let curr-heading = state("curr-heading", ())

#set text(size: 8pt)

#let set-heading(content) = {
  show heading.where(level: 3): it => {
    show regex("[\p{hani}\s]+"): underline
    it
  }
  show heading: it => {
    show regex("KiraKira"): box("★", baseline: -20%)
    show regex("FuwaFuwa"): box("✎", baseline: -20%)
    it
  }

  content
}

#let set-text(content) = {
  show regex("feat|refactor"): emph
  content
}

#show: set-heading
#show: set-text

#set page(width: 120pt, height: 120pt, margin: (top: 12pt, bottom: 10pt, x: 5pt))

== 雨滴书v0.1.2
=== KiraKira 样式改进
feat: 改进了样式。
=== FuwaFuwa 脚本改进
feat: 改进了脚本。

== 雨滴书v0.1.1
refactor: 移除了LaTeX。

feat: 删除了一个多余的文件夹。

== 雨滴书v0.1.0
feat: 新建了两个文件夹。



================================================
FILE: src/tutorial/writing-chinese.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "中文排版")

建议结合#link("https://typst-doc-cn.github.io/docs/chinese/")[《Typst中文文档：中文用户指南》]食用。

== 中文排版 —— 字体

== 设置中文字体

如果中文字体不符合 typst 要求，那么它不会选择你声明的字体，例如字体的变体数量不够，参考更详细的 issue。

+ typst fonts 查看系统字体，确保字体名字没有错误。
+ typst fonts --font-path path/to/your-fonts 指定字体目录。
+ typst fonts --variants 查看字体变体。
+ 检查中文字体是否已经完全安装。

== 设置语言和区域

如果字体与 ```typc text(lang: .., region: ..)``` 不匹配，可能会导致连续标点的挤压。例如字体不是中国大陆的，标点压缩会出错；反之亦然。

=== 伪粗体

=== 伪斜体

=== 同时设置中西字体（以宋体和Times New Roman为例）

== 中文排版 —— 间距

=== 首行缩进

#let empty-par = par[#box()]
#let fake-par = context empty-par + v(-measure(empty-par + empty-par).height)

#let no-indent = context h(-par.first-line-indent)

#let a = {
  1
}

=== 代码片段与中文文本之间的间距

=== 数学公式与中文文本之间的间距

== 中文排版 —— 特殊排版

=== 使用中文编号

=== 为汉字和词组注音

=== 为汉字添加着重号

=== 竖排文本

=== 使用国标文献格式

== Typst v0.10.0为止的已知问题及补丁

=== 源码换行导致linebreak

=== 标点字体fallback

== 模板参考

#link("https://github.com/typst-doc-cn/tutorial/blob/b452e6ec436aa150a6429becb8cf046d08360f63/typ/templates/page.typ")[本书各章节使用的模板]

todo: 内嵌和超链接可直接食用的模板

== 进一步阅读

+ 参考#link("https://typst-doc-cn.github.io/docs/chinese/")[《Typst中文文档：中文用户指南》]，包含中文用户常见问题。
+ 参考#(refs.scripting-modules)[《模块、外部库与多文件文档》]，在你的电脑上共享中文文档模板。
+ 推荐使用的外部库列表


================================================
FILE: src/tutorial/writing-markup.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [标记模式])

Typst是一门简明但强大的现代排版语言，你可以使用简洁直观的语法排版出好看的文档。

Typst希望你总是尽可能少的配置样式，就获得一个排版精良的文档。多数情况下，你只需要专心撰写文档，而不需要在文档内部对排版做任何更复杂的调整。

得益于此设计目标，为了使你可以用Typst编写一篇基本文档，本节仍只需涉及最基本的语法。哪怕只依靠这些语法，你已经可以编写满足很多场合需求的文档。

== 段落 <grammar-paragraph>

普通文本默认组成一个个段落。

#code(```typ
我是一段文本
```)

另起一行文本不会产生新的段落。为了创建新的段落，你需要空至少一行。

#code(```typ
轻轻的我走了，
正如我轻轻的来；

我轻轻的招手，
作别西天的云彩。
```)

缩进并不会产生新的空格：

#code(```typ
  轻轻的我走了，
      正如我轻轻的来；

  我轻轻的招手，
      作别西天的云彩。
```)

注意：如下图的蓝框高亮所示，另起一行会引入一个小的空格。该问题会在未来修复。

#code(
  ```typ
  轻轻的我走了，#box(fill: blue, outset: (right: 0.2em), sym.space)
  正如我轻轻的来；

  轻轻的我走了，正如我轻轻的来；
  ```,
  code-as: ```typ
  轻轻的我走了，
  正如我轻轻的来；

  轻轻的我走了，正如我轻轻的来；
  ```,
)

== 标题 <grammar-heading>

你可以使用一个或多个*连续*的#mark("=")开启一个标题。

#code(```typ
= 一级标题
我走了。
== 二级标题
我来了。
=== 三级标题
我走了又来了。
```)

等于号的数量恰好对应了标题的级别。一级标题由一个#mark("=")开启，二级标题由两个#mark("=")开启，以此类推。

注意：正如你所见，标题会强制划分新的段落。

#pro-tip[
  使用show规则可以改变“标题会强制划分新的段落”这个默认规则。

  #code(```typ
  #show heading.where(level: 3): box
  = 一级标题
  我走了。

  === 三级标题
  我走了又来了。
  ```)
]

== 着重和强调语义

有许多与#mark("=")类似的语法标记。当你以相应的语法标记文本内容时，相应的文本就被赋予了特别的语义和样式。

#pro-tip[
  与HTML一样，Typst总是希望语义先行。所谓语义先行，就是在编写文档时总是首先考虑标记语义。所有样式都是附加到语义上的。

  例如在英文排版中，#typst-func("strong")的样式是加粗，#typst-func("emph")的样式是倾斜。你完全可以在中文排版中为它们更换样式。

  #if is-web-target {
    code(```typ
    #show strong: content => {
      show regex("\p{Hani}"): it => box(place(text("·", size: 0.8em), dx: 0.1em, dy: 0.75em) + it)
      content.body
    }
    *中文排版的着重语义用加点表示。*
    ```)
  } else {
    code(```typ
    #show strong: content => {
      show regex("\p{Hani}"): it => box(place(text("·", size: 1.3em), dx: 0.3em, dy: 0.5em) + it)
      content.body
    }
    *中文排版的着重语义用加点表示。*
    ```)
  }
]

与许多标记语言相同，Typst中使用一系列#term("delimiter")规则确定一段语义的开始和结束。为赋予语义，需要将一个#term("delimiter")置于文本*之前*，表示某语义的开始；同时将另一个#term("delimiter")置于文本*之后*，表示该语义的结束。

例如，#mark("*")作为定界符赋予所包裹的一段文本以#term("strong semantics")。 <grammar-strong>

#code(```typ
着重语义：这里有一个*重点！*
```)

与#term("strong semantics")类似，#mark("_")作为定界符将赋予#term("emphasis semantics")： <grammar-emph>

#code(```typ
强调语义：_emphasis_
```)

着重语义一般比强调语义语气更重。着重和强调语义可以相互嵌套：

#code(```typ
着重且强调：*_strong emph_* 或 _*strong emph*_
```)

注意：中文排版一般不使用斜体表示着重或强调。

== （计算机）代码片段 <grammar-raw>

Typst的#term("raw block")标记语法与Markdown完全相同。

配对的#mark("`")包裹一段内容，表示内容为#term("raw block")。

#code(````typ
短代码片段：`code`
````)

有时候你希望允许代码内容包含换行或#mark("`")。这时候，你需要使用*至少连续*三个#mark("`")组成定界符标记#term("raw block")：<grammar-long-raw>

#code(`````typ
使用三个反引号包裹：``` ` ```

使用四个反引号包裹：```` ``` ````
`````)

对于长代码片段，你还可以在起始定界符后*紧接着*指定该代码的语言类别，以便Typst据此完成语法高亮。<grammar-lang-raw>

#code(`````typ
一段有高亮的代码片段：```javascript function uninstallLaTeX {}```

另一段有高亮的代码片段：````typst 包含反引号的长代码片段：``` ` ``` ````
`````)

除了定界符的长短，代码片段还有是否成块的区分。如果代码片段符合以下两点，那么它就是一个#term("blocky raw block")： <grammar-blocky-raw>
+ 使用*至少连续*三个#mark("`")，即其需为长代码片段。
+ 内容包含至少一个#term("line break")。

#code(`````typ
非块代码片段：```rust trait World```

块代码片段：```js
function fibnacci(n) {
  return n <= 1 ?: `...`;
}
```
`````)

// typ
// typc

== 列表

Typst的列表语法与Markdown非常类似，但*不完全相同*。

一行以#mark("-")开头即开启一个无编号列表项： <grammar-enum>

#code(```typ
- 一级列表项1
```)

与之相对，#mark("+")开启一个有编号列表项。 <grammar-list>

#code(```typ
+ 一级列表项1
```)

利用缩进控制列表项等级：

#code(```typ
- 一级列表项1
  - 二级列表项1.1
    - 三级列表项1.1.1
  - 二级列表项1.2
- 一级列表项2
  - 二级列表项2.1
```)

有编号列表项可以与无编号列表项相混合。<grammar-mix-list-emum>

#code(```typ
+ 一级列表项1
  - 二级列表项1.1
    + 三级列表项1.1.1
  - 二级列表项1.2
+ 一级列表项2
  - 二级列表项2.1
```)

和Markdown相同，Typst同样允许使用显式的编号`1.`开启列表。这方便对列表继续编号。<grammar-continue-list>

#code(```typ
1. 列表项1
1. 列表项2
```)

#code(```typ
1. 列表项1
+  列表项2

列表间插入一段描述。

3. 列表项3
+  列表项4
+  列表项5
```)

== 转义序列 <grammar-escape-sequences>

你有时希望直接展示标记符号本身。例如，你可能想直接展示一个#mark("_")，而非使用强调语义。这时你需要利用#term("escape sequences")语法：

#code(````typ
在段落中直接使用下划线 >\_<！
````)

遵从许多编程语言的习惯，Typst使用#mark("\\")转义特殊标记。下表给出了部分可以转义的字符：

#let escaped-sequences = (
  (`\\`, [\\]),
  (`\/`, [\/]),
  (`\[`, [\[]),
  (`\]`, [\]]),
  (`\{`, [\{]),
  (`\}`, [\}]),
  (`\<`, [\<]),
  (`\>`, [\>]),
  (`\(`, [\(]),
  (`\)`, [\)]),
  (`\#`, [\#]),
  (`\*`, [\*]),
  (`\_`, [\_]),
  (`\+`, [\+]),
  (`\=`, [\=]),
  (`\~`, [\~]),
  // @typstyle off
  (```\` ```, [\`]),
  (`\$`, [\$]),
  (`\"`, [\"]),
  (`\'`, [\']),
  (`\@`, [\@]),
  (`\a`, [\a]),
  (`\A`, [\A]),
)

#let mk-tab(seq) = {
  set align(center)
  let u = it => raw(it.at(0).text, lang: "typ")
  let ovo = it => it.at(1)
  let w = 8
  table(
    columns: w + 2,
    [代码],
    ..seq.slice(w * 0, w * 1).map(u),
    u((`\u{cccc}`, [\u{cccc}])),
    [效果],
    ..seq.slice(w * 0, w * 1).map(ovo),
    [\u{cccc}],
    [代码],
    ..seq.slice(w * 1, w * 2).map(u),
    u((`\u{cCCc}`, [\u{cCCc}])),
    [效果],
    ..seq.slice(w * 1, w * 2).map(ovo),
    [\u{cCCc}],
    [代码],
    ..seq.slice(w * 2).map(u),
    [],
    u((`\u{2665}`, [\u{2665}])),
    [效果],
    ..seq.slice(w * 2).map(ovo),
    [],
    [\u{2665}],
  )
}

#mk-tab(escaped-sequences)

以上大部分#term("escape sequences")都紧跟单个字符，除了表中的最后一列。 <grammar-unicode-escape-sequences>

表中的最后一列所展示的`\u{unicode}`语法被称为Unicode转义序列，也常见于各种语言。你可以通过将`unicode`替换为#link("https://zh.wikipedia.org/zh-cn/%E7%A0%81%E4%BD%8D")[Unicode码位]的值，以输出该特定字符，而无需*输入法支持*。例如，你可以这样输出一句话：

#code(
  ````typ
  \u{9999}\u{8FA3}\u{725B}\u{8089}\u{7C89}\u{597D}\u{5403}\u{2665}
  ````,
  code-as: ````typ
  \u{9999}\u{8FA3}\u{725B}\u{8089}\u{7C89}
  \u{597D}\u{5403}\u{2665}
  ````,
)

诸多#term("escape sequences")无需死记硬背，你只需要记住：
+ 如果其在Typst中已经被赋予含义，请尝试在字符前添加一个#mark("\\")。
+ 如果其不可见或难以使用输入法获得，请考虑使用`\u{unicode}`。

== 输出换行符 <grammar-newline>

输出换行符是一种特殊的#term("escape sequences")，它使得文档输出换行。

#mark("\\")后紧接一个任意#term("whitespace")，表示在此处主动插入一个段落内的换行符： <grammar-newline-by-space>

#code(````typ
转义空格可以换行 \ 转义回车也可以换行 \
换行！
````)

空白字符可以取短空格（`U+0020`）、长空格（`U+3000`）、回车（`U+000D`）等。

== 速记符号 <grammar-shorthand>

在#term("markup mode")下，一些符号需要用特殊的符号组合打出，这种符号组合被称为#term("shorthand")。它们是：

空格（`U+0020`）的#term("shorthand")是#mark("~")： <grammar-shorthand-space>

#code(```typ
AB v.s. A~B
```)

连接号（en dash, `U+2013`）的#term("shorthand")由两个连续的#mark("hyphen")组成：

#code(```typ
北京--上海路线的列车正在到站。
```)

// 破折号的#term("shorthand")由三个连续的#mark("hyphen")组成（有问题，毋用，请直接使用em dash，`—`）：

// #code(```typ
// 你的生日------四月十八日------每年我总记得。\
// 你的生日——四月十八日——每年我总记得。
// ```)

省略号的#term("shorthand")由三个连续的#mark(".")组成：

#code(```typ
真的假的......
```)

// - minusi
// -? soft-hyphen

完整的速记符号列表参考#link("https://typst.app/docs/reference/symbols/")[Typst Symbols]。

== 注释 <grammar-inline-comment>

Typst的#term("comment")直接采用C语言风格的注释语法，有两种表示方法。

第一种写法是将注释内容放在两个连续的#mark("/")后面，从双斜杠到行尾都属于#term("comment")。

#code(````typ
// 这是一行注释
一行文本 // 这也是注释
````)

与代码片段的情形类似，Typst也提供了另外一种可以跨行的#term("comment")，形如`/*...*/`。<grammar-cross-line-comment>

#code(````typ
你没有看见/* 混入其中 */注释
````)

值得注意的是，Typst会将#term("comment")从源码中剔除后再解释你的文档，因此它们对文档没有影响。

以下两个段落等价：

#code(````typ
注释不会
// 这是一行注释 // 注释内的注释还是注释
插入换行 // 这也是注释

注释不会
插入换行
````)

以下三个段落等价：

#code(````typ
注释不会/* 混入其中 */插入空格

注释不会/*
混入其中
*/插入空格

注释不会插入空格
````)

== 总结

基于《初识标记模式》掌握的知识，你应该编写一些非常简单的文档。

== 习题

#let q1 = ````typ
欲穷千里目，/*
*/更上一层楼。
````

#exercise[
  使源码至少有两行，第一行包含“欲穷千里目，”，第二行包含“更上一层楼。”，但是输出不换行不空格：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#exercise[
  输出一个#mark("*")，期望的输出：#rect(width: 100%)[\*]
][
  ```typ
  \*
  ```
]

#let q1 = ````typ
```
`
```
````

#exercise[
  插入代码片段使其包含一个反引号，期望的输出：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ```typ

```

#let q1 = `````typ
````
```
````
`````

#exercise[
  插入代码片段使其包含三个反引号，期望的输出：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ````typ
你可以在Typst内通过插件 ```typc plugin("typst.wasm")``` 调用Typst编译器。
````

#exercise[
  插入行内的“typc”代码，期望的输出：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q2 = ```typ
约法五章。
1. 其一。
+ 其二。

前两条不算。

3. 其三。
+ 其四。
+ 其五。
```

#exercise[
  在有序列表间插入描述，期望的输出：#rect(width: 100%, eval(q2.text, mode: "markup"))
][
  #q2
]


================================================
FILE: src/tutorial/writing-math.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "数学排版")

== 数学排版


================================================
FILE: src/tutorial/writing-scripting.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: [脚本模式])

从现在开始，示例将会逐渐开始出现脚本。不要担心，它们都仅涉及脚本的简单用法。

== 内容块 <grammar-content-block>

有时，文档中会出现连续大段的标记文本。

#code(````typ
*从前有座山，山会讲故事，故事讲的是*

*从前有座山，山会讲故事，故事讲的是*

*...*

````)

这可行，但稍显麻烦。如下代码则显得更为整洁，它不必为每段都打上着重标记：

#code(````typ
#strong[
  从前有座山，山会讲故事，故事讲的是

  从前有座山，山会讲故事，故事讲的是

  ...
]
````)

例中，```typ #strong[]```这个内容的语法包含三个部分：
+ `#`使解释器进入#term("code mode")。
+ #typst-func("strong")是赋予#term("strong semantics")函数。
+ `[]`作为#term("content block")标记一段内容，供`strong`使用。

本小节首先讲解第三点，即#term("content block")语法。

#term("content block")的内容使用中括号包裹，如下所示：

#code(```typ
#[一段文本]#[两段文本] #[三段文本]
```)

#term("content block")不会影响包裹的内容——Typst仅仅是解析内部代码作为#term("content block")的内容。#term("content block")也*几乎不影响内容的书写*。

#term("content block")的唯一作用是“界定内容”。它收集一个或多个#term("content")，以待后续使用。有了#term("content block")，你可以*准确指定*一段内容，并用#term("scripting")加工。

#import "../figures.typ": figure-content-decoration
#align(center + horizon, figure-content-decoration())

#v(1em)

所谓#term("scripting")，就是对原始内容增删查改，进而形成文档的过程描述。因为有了#term("scripting")，Typst才能有远超Markdown的排版能力，在许多情况下不逊于LaTeX排版，将来有望全面超越LaTeX排版。

在接下来两小节你将看到Typst作为一门*编程语言*的核心设计，也是进行更高级排版必须要掌握的知识点。由于我们的目标首先仅是*编写一篇基本文档*，我们将会尽可能减少引入更多知识点，仅仅介绍其中最简单常用的语法。

== 解释模式 <grammar-enter-script>

```typ #strong[]```语法第一点提及：`#`使解释器进入#term("code mode")。

#code(```typ
#[一段文本]
```)

这个#mark("#")不属于内容块的语法一部分，而是模式转换的标志。

这涉及到Typst的编译原理。Typst是一个动态解释器，其按顺序查看并#term("interpret")你的文档源码。而#mark("#")就是告诉这个当前处于「标记模式」的解释器，接下来请转为「脚本模式」。

实际上，相比python等语言，Typst的确有些特殊。它的解释器可以在不同#term("interpreting mode")下运行。在不同模式下，解释器以不同的语法规则解释你的文档。这便是借鉴了LaTeX的文本和数学模式。Typst一共有三种#term("interpreting mode")：标记模式的语法更适合你组织文本，代码模式更适合你书写脚本，而数学模式则最适合输入复杂的公式。

// todo 三种解释模式的visualization

=== 标记模式

当解释器解释一个文件时，其默认就处于#term("markup mode")，在这个模式下，你可以使用各种记号创建标题、列表、段落......在这个模式下，Typst语法几乎就和Markdown一样。这些标记，我们大多在之前的章节已经学过。

=== 脚本模式

在「脚本模式」下，你可以转而*主要*计算各种内容。例如，你可以计算一个算式的「内容」：

#code(```typ
#(1024*1024*8*7*17+1)是一个常见素数。
```)

当处于「脚本模式」时，解释器在*适当*的时候从「脚本模式」退回为「标记模式」。如下所示，在「脚本模式」下解析到数字```typc 2```后解释器回到了「标记模式」：

#code(```typ
#2是一个常见素数。
```)

Typst总是倾向于更快地退出脚本模式。

#pro-tip[
  具体来说，你几乎可以认为解释器至多只会解释一个*完整的表达式*，之后就会*立即*退出「脚本模式」。
]

=== 以另一个视角看待内容块

你可以在「脚本模式」下使用「内容块」语法。这意味着，你还可以通过「内容块」临时又返回「标记模式」，以嵌套复杂的逻辑：

#code(```typ
#([== 脚本模式下创建一个标题] + strong[后接一段文本])
```)

如此反复，Typst就同时具备了方便文档创作与脚本编写的能力。

#pro-tip[
  能否直接像使用「星号」那样，让#term("markup mode")直接将中括号包裹的一段作为内容块的内容？

  这是可以的，但是存在一些问题。例如，人们也常常在正文中使用中括号等标记：

  #code(```typ
  遇事不决睡大觉 (¦3[▓▓]
  ```)

  如此，「标记模式」下默认将中括号解析为普通文本看起来更为合理。
]

== 数学模式

Typst解释器一共有三种模式，其中两种我们之前已经介绍。这剩下的最后一种被称为#term("math mode")。很多人认为Typst针对LaTeX的核心竞争点之一就是优美的#term("math mode")。

Typst的数学模式如下：<grammar-inline-math> ~ <grammar-display-math>

#code(````typ
行内数学公式：$sum_x$

行间数学公式：$ sum_x $
````)

由于使用#term("math mode")有很多值得注意的地方，且#term("math mode")是一个较为独立的模式，本书将其单列为一章参考，可选阅读。有需要在文档中插入数学公式的同学请移步#(refs.ref-math-mode)[《参考：数学模式》]。

== 函数和函数调用 <grammar-func-call>

这里仅作最基础的介绍。#(refs.scripting-base)[《常量与变量》]和#(refs.scripting-complex)[《块与表达式》]中有对函数和函数调用更详细的介绍。

函数与函数调用同样归属#term("code mode")，所以在调用函数前，你需要先使用#mark("#")让Typst先进入#term("code mode")。

与大部分语言相同的是，在调用Typst函数时，你可以向其传递以逗号分隔的#term("value")，这些#term("value")被称为函数的参数。

#code(```typ
四的三次方为#calc.pow(4, 3)。
```)

这里#typst-func("calc.pow")是编译器内置的幂计算函数，其接受两个参数：
+ 一为```typc 4```，为幂的底
+ 一为```typc 3```，为幂的指数。

你可以使用函数修饰#term("content block")。例如，你可以使用着重函数#typst-func("strong") 标记一整段内容：

#code(```typ
#strong([
  And every _fair from fair_ sometime declines,
])
```)

首先，中括号包裹的是一段内容。在之前已经学到，这是一个#term("content block")。然后#term("content block")在参数列表中，说明它是#typst-func("strong")的参数。#typst-func("strong")与幂函数调用没有什么语法上的区别，无非是接受了一个#term("content block")作为参数。

类似地，#typst-func("emph")可以标记一整段内容为强调语义：

#code(```typ
#emph([
  And every *fair from fair* sometime declines,

  ......
])
```)

你应该也注意到了#typst-func("strong")事实上就是《初识标记模式》中讲过的着重标记，#typst-func("emph")就是强调标记。

Typst强调#term("consistency")，因此无论是使用标记还是使用函数修饰内容，最终效果都是一样的。你可以根据实际情况选择合适的方法修饰内容。

== 内容参数的糖 <grammar-content-param>

在许多的语言中，所有函数参数必须包裹在函数调用参数列表的「圆括号」之内。

#code(```typ
着重语义：这里有一个#strong([重点！])
```)

但在Typst中，如果将内容块作为参数，内容块可以紧贴在参数列表的「圆括号」之后。

#code(```typ
着重语义：这里有一个#strong()[重点！]
```)

特别地，如果参数列表为空，Typst允许省略多余的参数列表。

#code(```typ
着重语义：这里有一个#strong[重点！]
```)

所以，示例也可以写为：

#code(```typ
#strong[
  And every _fair from fair_ sometime declines,
]

#emph[
  And every *fair from fair* sometime declines,
]
```)

#pro-tip[
  函数调用可以后接不止一个内容参数。例如下面的例子后接了两个内容参数：

  #code(```typ
  #let exercise(question, answer) = strong(question) + parbreak() + answer

  #exercise[
    Question: _turing complete_？
  ][
    Answer: Yes, Typst is.
  ]
  ```)
]

== 文字修饰

现在你可以使用更多的文本函数来丰富你的文档效果。

=== 背景高亮 <grammar-highlight>

你可以使用#typst-func(`highlight`)高亮一段内容：

#code(```typ
#highlight[高亮一段内容]
```)

你可以传入`fill`参数以改变高亮颜色。

#code(```typ
#highlight(fill: orange)[高亮一段内容]
//         ^^^^^^^^^^^^ 具名传参
```)

这种传参方式被称为#(refs.scripting-base)[「具名传参」。]冒号的左侧写`fill`，代表是令`fill`参数为冒号右边的`orange`（橘色）。

=== 修饰线

你可以分别使用#typst-func("underline")、#typst-func("overline")、或#typst-func("strike")为一段内容添加下划线<grammar-underline>、上划线<grammar-overline>或中划线（删除线）<grammar-strike>：

#{
  set text(font: "Source Han Serif SC")
  code(```typ
  平地翻滚：#underline[ጿኈቼዽጿኈቼዽ] \
  施展轻功：#overline[ጿኈቼዽጿኈቼዽ] \
  泥地打滚：#strike[ጿኈቼዽጿኈቼዽ] \
  ```)
}

值得注意地是，线段的高度受到被修饰文本的字体影响。

#code(```typ
#set text(font: ("Linux Libertine", "Source Han Serif SC"))
下划线效果：#underline[空格 字体不一致] \
#set text(font: "Source Han Serif SC")
下划线效果：#underline[空格 字体一致] \
```)

这是因为#typst-func("underline")的`offset`参数默认与字体有关。这个参数决定了下划线相对于「基线」的偏移量。令其默认与字体有关是合理的，但是在一行文本混合多个字体的情况下表现不佳。

#code(
  ```typ
  #set text(font: ("Linux Libertine", "Source Han Serif SC"))
  #underline(offset: 1.5pt)[空格 字体的下划线offset均为1.5pt]
  ```,
  code-as: ```typ
  #underline(offset: 1.5pt)[空格 字体的下划线offset均为1.5pt]
  ```,
)

你也可以通过`offset`参数制作双下划线：

#code(```typ
#underline(offset: 1.5pt, underline(offset: 3pt, [双下划线]))
```)

如果你更喜欢连贯的下划线，你可以设置`evade`参数，以解除驱逐效果。<grammar-underline-evade>

#code(```typ
带驱逐效果：#underline[Language] \
不带驱逐效果：#underline(evade: false)[Language]
```)

=== 上下标

你可以分别使用#typst-func("sub")<grammar-subscript>或#typst-func("super")<grammar-superscript>将一段文本调整至下标位置或上标位置：

#code(```typ
下标：威严满满#sub[抱头蹲防] \
上标：香風とうふ店#super[TM] \
```)

你可以为上下标设置特定的字体大小：

#code(```typ
上标：香風とうふ店#super(size: 0.8em)[™] \
```)

你可以为上下标设置相对基线的合适高度：

#code(```typ
上标：香風とうふ店#super(size: 1em, baseline: -0.1em)[™] \
```)

== 文字属性

文本本身也可以设置一些「具名参数」。与#typst-func("strong")和#typst-func("emph")类似，文本也有一个对应的元素函数#typst-func("text")。#typst-func("text")接受任意内容，返回一个影响内部文本的结果。

当输入是单个文本时很好理解，返回的就是一个文本元素：

#code(````typ
#text("一段内容")
````)

当输入是一段内容时，返回的是该内容本身，但是对于内容的中的每一个文本元素，都作相应文本属性的修改。下例修改了「代码片段」元素中的文本元素为红色：

#code(````typ
#text(fill: red)[```
影响块元素的内容
```]
````)

进一步，我们强调，其实际修改了*缺省*的文本属性。对比以下两个情形：

#code(````typ
#text[```typ #strong[一段内容] #emph[一段内容]```] \
#text(fill: red)[```typ #strong[一段内容] #emph[一段内容]```] \
````)

可以看见“红色”的设置仅对代码片段中的“默认颜色”的文本生效。对于那些已经被语法高亮的文本，“红色”的设置不再生效。

这说明了为什么下列情形输出了蓝色的文本：

#code(````typ
#text(fill: red, text(fill: blue, "一段内容"))
````)

=== 设置大小 <grammar-text-size>

通过`size`参数，可以设置文本大小。

#code(```typ
#text(size: 12pt)[一斤鸭梨]
#text(size: 24pt)[四斤鸭梨]
```)

其中`pt`是点单位。中文排版中常见的#link("https://ccjktype.fonts.adobe.com/2009/04/post_1.html")[号单位]与点单位有直接换算关系：

#let owo = (
  [初号],
  [小初],
  [一号],
  [小一],
  [二号],
  [小二],
  [三号],
  [小三],
  [四号],
  [小四],
  [五号],
  [小五],
  [六号],
  [小六],
  [七号],
  [八号],
)
#let owo2 = ([42], [36], [26], [24], [22], [18], [16], [15], [14], [12], [10.5], [9], [7.5], [6.5], [5.5], [5])
#let owo3 = ([42], [–], [27.5], [-], [21], [–], [16], [–], [13.75], [–], [10.5], [–], [8], [–], [5.25], [4])
#{
  set align(center)
  table(
    columns: 9,
    [字号],
    ..owo.slice(0, 8),
    [中国（单位：点）],
    ..owo2.slice(0, 8),
    [日本（单位：点）],
    ..owo3.slice(0, 8),
    [字号],
    ..owo.slice(8),
    [中国（单位：点）],
    ..owo2.slice(8),
    [日本（单位：点）],
    ..owo3.slice(8),
  )
}

另一个常见单位是`em`：

#code(```typ
#text(size: 1em)[一斤鸭梨]
#text(size: 2em)[四斤鸭梨]
```)

```typc 2em```即是两倍于当前文字大小的长度。

关于Typst中长度单位的详细介绍，可以挪步#(refs.ref-length)[《参考：长度单位》]。

#pro-tip[
  如果记不住或嫌麻烦，#link("https://typst.app/universe/package/pointless-size")[pointless-size]包可帮助转换字号单位。

  #code(```typ
  #import "@preview/pointless-size:0.1.0": zh

  #zh(1) // 一号（26pt）
  ```)
]

=== 设置颜色 <grammar-text-fill>

你可以通过`fill`参数为文字配置各种颜色：

#code(```typ
#text(fill: red)[红色鸭梨]
#text(fill: blue)[蓝色鸭梨]
```)

你还可以通过颜色函数创建自定义颜色：

#code(```typ
#text(fill: rgb("ef475d"))[茉莉红色鸭梨]
#text(fill: color.hsl(200deg, 100%, 70%))[天依蓝色鸭梨]
```)

关于Typst中色彩系统的详细介绍，详见#(refs.ref-color)[《参考：颜色、渐变填充与模式填充》]。

=== 设置字体 <grammar-text-font>

你可以通过`font`参数为文字配置字体：
todo: CI上没有这些字体。

#code(```typ
#text(font: "FangSong")[北京鸭梨]
#text(font: "Microsoft YaHei")[板正鸭梨]
```)

你还可以用逗号分隔的「列表」为文本同时设置多个字体。Typst优先使用列表中靠前字体。例如可以同时设置西文为Times New Roman字体，中文为仿宋字体：

#code(```typ
#text(font: ("Times New Roman", "FangSong"))[中西Pear]
```)

关于如何配置中文、西文、数学等多种字体，详见#(refs.misc-font-setting)[《字体设置》]。

== 「`set`」语法

Typst的元素可以与其构造函数一一对应。Typst允许你设置元素的（函数）参数，就像是设置元素的样式。这个特性由「`set`」语法实现。

例如，你可以这样设置文本字体：

#code(```typ
#set text(fill: red)
红色鸭梨
```)

`set`关键字后跟随一个函数调用语法，表示此后所有的元素都具有指定的样式。这比```typ #text(fill: red)[红色鸭梨]```要更易读。

默认情况下文本元素的`fill`参数为黑色，即文本默认为黑色。经过`set`规则，其往后的文本都默认为红色。

#code(```typ
黑色鸭梨
#set text(fill: red)
红色鸭梨
```)

你仍然可以在创建元素的时候指定样式：

#code(```typ
#set text(fill: red)
#text(fill: blue)[蓝色鸭梨]
```)

#pro-tip[
  上面例子中，Typst引擎并没有立即实例化文本，而是将蓝色文本添加到「样式链」上，并继续评估内容块的内容。

  ```typ
  #set text(fill: red)
  #{ set text(fill: blue); {// text函数调用相当于set样式。
    "蓝色鸭梨" // 直到此处才获取样式并创建文本元素。
  }}
  ```

  从这个观点，你很容易就知道鸭梨文本是蓝色的。
]

本节前面讲述的所有元素的「具名参数」都可以如是设置，例如文本大小、字体等。

关于对「`set`」语法更详细的介绍，详见#(refs.content-scope-style)[《内容、作用域与样式》]。

== 图像 <grammar-image>

图像对应元素函数#typst-func("image")。

你可以通过#(refs.scripting-modules)[绝对路径或相对路径]加载一个图片文件：

#{
  show image: set align(center)
  set image(width: 40%)
  code(```typ
  #image("/assets/files/香風とうふ店.jpg")
  ```)
}

#typst-func("image")有一个很有用的`width`参数，用于限制图片的宽度：

#{
  show image: set align(center)
  code(```typ
  #image("/assets/files/香風とうふ店.jpg", width: 100pt)
  ```)
}

你还可以相对于父元素设置宽度，例如设置为父元素宽度的`50%`：

#{
  show image: set align(center)
  code(```typ
  #image("/assets/files/香風とうふ店.jpg", width: 50%)
  ```)
}

同理，你也可以用`height`参数限制图片的高度。

#{
  show image: set align(center)
  code(```typ
  #image("/assets/files/香風とうふ店.jpg", height: 100pt)
  ```)
}

当同时设置了图片的宽度和高度时，图片默认会被裁剪：

#{
  show image: set align(center)
  code(```typ
  #image("/assets/files/香風とうふ店.jpg", width: 100pt, height: 100pt)
  ```)
}

如果想要拉伸图片而非裁剪图片，可以同时使用`fit`参数：<grammar-image-stretch>

#{
  show image: set align(center)
  code(```typ
  #image("/assets/files/香風とうふ店.jpg", width: 100pt, height: 100pt, fit: "stretch")
  ```)
}

“stretch”在英文中是拉伸的意思。

== 图形 <grammar-figure>

你可以通过#typst-func("figure")函数为图像设置标题：

#{
  show image: set align(center)
  set image(width: 40%)
  code(```typ
  #figure(image("/assets/files/香風とうふ店.jpg"), caption: [上世纪90年代，香風とうふ店送外卖的宝贵影像])
  ```)
}

#typst-func("figure")不仅仅可以接受#typst-func("image")作为内容，而是可以接受任意内容：

#{
  show raw: set align(left)
  code(````typ
  #figure(```typ
  #image("/assets/files/香風とうふ店.jpg")
  ```, caption: [用于加载香風とうふ店送外卖的宝贵影像的代码])
  ````)
}

// == 标签与引用

// #code(```typ
// #set heading(numbering: "1.")
// == 一个神秘标题 <myst>

// @myst 讲述了一个神秘标题。
// ```)

== 行内盒子 <grammar-box>

todo：本节添加box的基础使用。<grammar-image-inline>

#code(```typ
在一段话中插入一个#box(baseline: 0.15em, image("/assets/files/info-icon.svg", width: 1em))图片。
```)

== 链接 <grammar-link>

链接可以分为外链与内链。最简单情况下，你只需要使用#typst-func("link")函数即可创建一个链接：<grammar-http-link>

#code(```typ
#link("https://zh.wikipedia.org")
```)

特别地，Typst会自动识别文中的HTTPS和HTTP链接文本并创建链接：

#code(```typ
https://zh.wikipedia.org
```)

无论是内链还是外链，你都可以额外传入一段*任意*内容作为链接标题：

#code(```typ
不基于比较方法，#link("https://zh.wikipedia.org/zh-hans/%E5%9F%BA%E6%95%B0%E6%8E%92%E5%BA%8F")[排序]可以做到 $op(upright(O)) (n)$ 时间复杂度。
```)

请回忆，这其实等价于调用函数：

#code(```typ
#link("...")[链接] 等价于 #link("...", [链接])
```)

=== 内部链接 <grammar-internal-link>

你可以通过创建标签，标记*任意*内容：

#code(```typ
== 一个神秘标题 <myst>
```)

上例中`myst`是该标签的名字。每个标签都会附加到恰在其之前的内容，这里内容即为该标题。

#pro-tip[
  在脚本模式中，标签无法附加到之前的内容。

  #code(```typ
  #show <awa>: set text(fill: red)
  #{[a]; [<awa>]}
  #[b] <awa>
  ```)

  对比上例，具体来说，标签附加到它的#term("syntactic predecessor")。

  这不是问题，但是易用性有可能在将来得到改善。
]

你可以通过#typst-func("link")函数在文档中的任意位置链接到该内容：

#code(```typ
== 一个神秘标题 <mystery>

讲述了#link(<mystery>)[一个神秘标题]。
```)

== 表格基础 <grammar-table>

你可以通过#typst-func("table")函数创建表格。#typst-func("table")接受一系列内容，并根据参数将内容组装成一个表格。如下，通过`columns`参数设置表格为2列，Typst自动为你生成了一个2行2列的表格：

#code(```typ
#table(columns: 2, [111], [2], [3])
```)

你可以为表格设定对齐：<grammar-table-align>

#code(```typ
#table(columns: 2, align: center, [111], [2], [3])
```)

其他可选的对齐有`left`、`right`、`bottom`、`top`、`horizon`等，详见#(refs.ref-layout)[《参考：布局函数》]。

== 使用其他人的模板

虽然这是一篇教你写基础文档的教程，但是为什么不更进一步？有赖于Typst将样式与内容分离，如果你能找到一个朋友愿意为你分享两行神秘代码，当你粘贴到文档开头时，你的文档将会变得更为美观：

#code(````typ
#import "latex-look.typ": latex-look
#show: latex-look

= 这是一篇与LaTeX样式更接近的文档

Hey there!

Here are two paragraphs. The
output is shown to the right.

Let's get started writing this
article by putting insightful
paragraphs right here!
+ following best practices
+ being aware of current results
  of other researchers
+ checking the data for biases

$
  f(x) = integral _(-oo)^oo hat(f)(xi)e^(2 pi i xi x) dif xi
$
````)

一般来说，使用他人的模板需要做两件事：
+ 将`latex-look.typ`放在你的文档文件夹中。
+ 使用以下两行代码应用模板样式：

  ```typ
  #import "latex-look.typ": latex-look
  #show: latex-look
  ```

== 总结

基于《编写一篇基本文档》掌握的知识你应该可以：
+ 像使用Markdown那样，编写一篇基本不设置样式的文档。
+ 查看#(refs.ref-math-mode)[《参考：数学模式》]和#(refs.ref-math-symbols)[《参考：常用数学符号》]，以助你编写简单的数学公式。
+ 查看#(refs.ref-datetime)[《参考：时间类型》]，以在文档中使用时间。

// todo: 术语-翻译表
// todo: 本文使用的符号-标记对照表

== 习题

#let q1 = ````typ
#underline(offset: -0.4em, evade: false)[
  吾輩は猫である。
]
````

#exercise[
  用#typst-func("underline")实现“删除线”效果，其中删除线距离baseline距离为`40%`：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ````typ
#text(fill: rgb("00000001"))[I'm the flag]
````

#exercise[
  攻击者有可能读取你文件系统中的内容，并将其隐藏存储在你的PDF中。请尝试将用户密码“I'm the flag”以文本形式存放在PDF中，但不可见：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ````typ
走#text(size: 1.5em)[走#text(size: 1.5em)[走#text(size: 1.5em)[走]]]
````

#exercise[
  请仅用`em`实现以下效果，其中后一个字是前一个字大小的1.5倍：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ````typ
走#text(size: 1.5em)[走#text(size: 1.5em)[走]]
走#text(size: 1.5em)[走#text(size: 1.5em)[走]]
````

#exercise[
  请仅用`em`实现以下效果，其中后一个字是前一个字大小的1.5倍：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]

#let q1 = ````typ
#set text(size: 2.25em);走#set text(size: 0.666666666em);走#set text(size: 0.666666666em);走
````

#exercise[
  请仅用`em`实现以下效果，其中前一个字是后一个字大小的1.5倍。要求代码中不允许出现中括号也不允许出现双引号：#rect(width: 100%, eval(q1.text, mode: "markup"))
][
  #q1
]


================================================
FILE: src/tutorial/writing.typ
================================================
#import "mod.typ": *

#show: book.page.with(title: "编写一篇进阶文档")

// document
// list again
// figure again
// footnote
// quote
// smallcaps
// upper
// lower
// heading
// - outlined
// - bookmarked
// outline
// par
// parbreak
// table again
// lorem
// color again
// read/query/metadata
// # sys.version


================================================
FILE: typ/book/lib.typ
================================================

// #import "@preview/typst-ts-variables:0.1.0": page-width, target

#import "variables.typ": page-width, target

// export typst.ts variables again, don't import typst-ts-variables directly
#let get-page-width() = page-width
#let target = target
#let is-web-target() = target.starts-with("web")
#let is-pdf-target() = target.starts-with("pdf")

#let _labeled-meta(label) = context {
  let res = query(label)
  if res.len() <= 0 {
    none
  } else if res.len() == 1 {
    res.at(0).value
  } else {
    res.map(it => it.value)
  }
}

#let book-meta-state = state("book-meta", none)

/// helper function to get (and print/use) the final book metadata
#let get-book-meta() = _labeled-meta(<typst-book-book-meta>)

/// helper function to get (and print/use) the final build metadata
#let get-build-meta() = _labeled-meta(<typst-book-build-meta>)

/// Book metadata in summary.typ
///
/// title: The title of the book
/// authors: The author(s) of the book
/// description: A description for the book, which is added as meta information in the
///   html <head> of each page
/// repository: The github repository for the book
/// repository-edit: The github repository editing template for the book
///   example: `https://github.com/Me/Book/edit/main/path/to/book/{path}`
/// language: The main language of the book, which is used as a language attribute
///   <html lang="en"> for example.
/// summary: Content summary of the book
#let book-meta(
  title: "",
  description: "",
  repository: "",
  repository-edit: "",
  authors: (),
  language: "",
  summary: none,
) = [
  #metadata((
    kind: "book",
    title: title,
    description: description,
    repository: repository,
    repository_edit: repository-edit,
    authors: authors,
    language: language,
    summary: summary,
  )) <typst-book-raw-book-meta>
]

/// Build metadata in summary.typ
/// dest-dir: The directory to put the rendered book in. By default this is book/ in
/// the book's root directory. This can overridden with the --dest-dir CLI
/// option.
#let build-meta(dest-dir: "") = [
  #metadata(("dest-dir": dest-dir)) <typst-book-build-meta>
]

#let link2page = state("typst-book-link2page", (:))

#let encode-url-component(s) = {
  let prev = false
  for (idx, c) in s.codepoints().enumerate() {
    if c.starts-with(regex("[a-zA-Z]")) {
      if prev {
        prev = false
        "-"
      }
      c
    } else {
      prev = true
      if idx != 0 {
        "-"
      }
      str(c.to-unicode())
    }
  }
}

#let cross-link-path-label(path) = {
  assert(path.starts-with("/"), message: "absolute positioning required")
  encode-url-component(path)
}

/// Cross link support
#let cross-link(path, reference: none, content) = {
  let path-lbl = cross-link-path-label(path)
  if reference != none {
    assert(type(reference) == label, message: "invalid reference")
  }

  assert(content != none, message: "invalid label content")
  context {
    if reference != none {
      let result = query(reference)
      // whether it is internal link
      if result.len() > 0 {
        link(reference, content)
        return
      }
    }

    let link-result = link2page.final()
    if path-lbl in link-result {
      link((page: link-result.at(path-lbl), x: 0pt, y: 0pt), content)
      return
    }
    // assert(read(path) != none, message: "no such file")

    let lnk = {
      "cross-link://jump?path-label="
      path-lbl
      if reference != none {
        "&label="
        encode-url-component(str(reference))
      }
    }
    link(lnk, content)
  }
}

// Collect text content of element recursively into a single string
// https://discord.com/channels/1054443721975922748/1088371919725793360/1138586827708702810
#let plain-text(it) = {
  if type(it) == str {
    it
  } else if it == [ ] {
    " "
  } else if it.has("children") {
    it.children.map(plain-text).filter(t => type(t) == str).join()
  } else if it.has("body") {
    plain-text(it.body)
  } else if it.has("text") {
    it.text
  } else if it.func() == smartquote {
    if it.double {
      "\""
    } else {
      "'"
    }
  } else {
    none
  }
}

#let _store-content(ct) = if type(ct) == "string" {
  (kind: "plain-text", content: ct)
} else if ct.func() == text {
  (kind: "plain-text", content: ct.text)
} else {
  // Unreliable since v0.8.0
  // ( kind: "raw", content: ct )
  (kind: "plain-text", content: plain-text(ct))
}

/// Represents a chapter in the book
/// link: path relative (from summary.typ) to the chapter
/// title: title of the chapter
/// section: manually specify the section number of the chapter
///
/// Example:
/// ```typ
/// #chapter("chapter1.typ")["Chapter 1"]
/// #chapter("chapter2.typ", section: "1.2")["Chapter 1.2"]
/// ```
#let chapter(link, title, section: auto) = metadata((
  kind: "chapter",
  link: link,
  section: section,
  title: _store-content(title),
))

/// Represents a prefix/suffix chapter in the book
/// Example:
/// ```typ
/// #prefix-chapter("chapter-pre.typ")["Title of Prefix Chapter"]
/// #prefix-chapter("chapter-pre2.typ")["Title of Prefix Chapter 2"]
/// // other chapters
/// #suffix-chapter("chapter-suf.typ")["Title of Suffix Chapter"]
/// ```
#let prefix-chapter(link, title) = chapter(link, title, section: none)
#let suffix-chapter(link, title) = chapter(link, title, section: none)

/// Represents a divider in the summary sidebar
#let divider = metadata((kind: "divider"))

/// Internal method to convert summary content nodes
#let _convert-summary(elem) = {
  // The entry point of the metadata nodes
  if metadata == elem.func() {
    // convert any metadata elem to its value
    let node = elem.value

    // Convert the summary content inside the book elem
    if node.at("kind") == "book" {
      let summary = node.at("summary")
      node.insert("summary", _convert-summary(summary))
    }

    return node
  }

  // convert a heading element to a part elem
  if heading == elem.func() {
    return (kind: "part", content: elem, title: _store-content(elem.body))
  }

  // convert a (possibly nested) list to a part elem
  if list.item == elem.func() {
    // convert children first
    let maybe-children = _convert-summary(elem.body)

    if type(maybe-children) == "array" {
      // if the list-item has children, then process subchapters
      if maybe-children.len() <= 0 {
        panic("invalid list-item, no maybe-children")
      }

      // the first child is the chapter itself
      let node = maybe-children.at(0)

      // the rest are subchapters
      let rest = maybe-children.slice(1)
      node.insert("sub", rest)

      return node
    } else {
      // no children, return the list-item itself
      return maybe-children
    }
  }

  // convert a sequence of elements to a list of node
  if [].func() == elem.func() {
    return elem.children.map(_convert-summary).filter(it => it != none)
  }

  // All of rest are invalid
  none
}

/// Internal method to number sections
/// meta: array of summary nodes
/// base: array of section number
#let _numbering-sections(meta, base: ()) = {
  // incremental section counter used in loop
  let cnt = 1
  for c in meta {
    // skip non-chapter nodes or nodes without section number
    if c.at("kind") != "chapter" or c.at("section") == none {
      (c,)
      continue
    }

    // default incremental section
    let idx = cnt
    cnt += 1
    let num = base + (idx,)
    // c.insert("auto-section", num)

    let user-specified = c.at("section")
    // c.insert("raw-section", repr(user-specified))

    // update section number if user specified it by str or array
    if user-specified != none and user-specified != auto {
      // update number
      num = if type(user-specified) == str {
        // e.g. "1.2.3" -> (1, 2, 3)
        user-specified.split(".").map(int)
      } else if type(user-specified) == array {
        for n in user-specified {
          assert(
            type(n) == int,
            message: "invalid type of section counter specified " + repr(user-specified) + ", want number in array",
          )
        }

        // e.g. (1, 2, 3)
        user-specified
      } else {
        panic("invalid type of manual section specified " + repr(user-specified) + ", want str or array")
      }

      // update cnt
      cnt = num.last() + 1
    }

    // update section number
    let auto-num = num.map(str).join(".")
    c.at("section") = auto-num

    // update sub chapters
    if "sub" in c {
      c.sub = _numbering-sections(c.at("sub"), base: num)
    }

    (c,)
  }
}

/// show template for a book file
/// Example:
/// ```typ
/// #show: book
/// ```
#let book(content) = {
  // set page(width: 300pt, margin: (left: 10pt, right: 10pt, rest: 0pt))
  [#metadata(toml("typst.toml")) <typst-book-internal-package-meta>]

  context {
    let data = query(<typst-book-raw-book-meta>).at(0)
    let meta = _convert-summary(data)
    meta.at("summary") = _numbering-sections(meta.at("summary"))

    book-meta-state.update(meta)
    [
      #metadata(meta) <typst-book-book-meta>
    ]
  }

  // #let sidebar-gen(node) = {
  //   node
  // }
  // #sidebar-gen(converted)
  // #get-book-meta()
  content
}

#let external-book(spec: none) = {
  place(
    hide[
      #spec
    ],
  )
}

#let visit-summary(x, visit) = {
  if x.at("kind") == "chapter" {
    let v = none

    let link = x.at("link")
    if link != none {
      let chapter-content = visit.at("inc")(link)

      if chapter-content.children.len() > 0 {
        let t = chapter-content.children.at(0)
        if t.func() == [].func() and t.children.len() == 0 {
          chapter-content = chapter-content.children.slice(1).sum()
        }
      }

      if "children" in chapter-content.fields() and chapter-content.children.len() > 0 {
        let t = chapter-content.children.at(0)
        if t.func() == parbreak {
          chapter-content = chapter-content.children.slice(1).sum()
        }
      }

      show: it => {
        let abs-link = cross-link-path-label("/" + link)
        context {
          link2page.update(it => {
            it.insert(abs-link, here().page())
            it
          })
        }

        it
      }

      visit.at("chapter")(chapter-content)
    }

    if "sub" in x and x.sub != none {
      x.sub.map(it => visit-summary(it, visit)).sum()
    }
  } else if x.at("kind") == "part" {
    // todo: more than plain text
    visit.at("part")(x.at("title").at("content"))
  } else {
    // repr(x)
  }
}


================================================
FILE: typ/book/typst.toml
================================================
[package]
name = "book"
version = "0.2.3"
entrypoint = "lib.typ"
authors = ["Myriad-Dreamin"]
license = "Apache-2.0"
description = "A simple tool for creating modern online books in pure typst."


================================================
FILE: typ/book/variables.typ
================================================

// It is in default A4 paper size
#let page-width = 595.28pt

// default target is "pdf"
#let target = "pdf"


================================================
FILE: typ/embedded-typst/example.typ
================================================

#import "lib.typ": *

#let doc = svg-doc(```
#set page(header: [
  #set text(size: 20pt)
  The book compiled by embedded typst
])
#set text(size: 30pt)

#v(1em)
= The first section <embedded-typst>
#lorem(120)
= The second section
#lorem(120)
```)

#let query-result = doc.header.at(0)

The selected element is:
#query-result.func#[[#[#query-result.body.text]]]

#grid(columns: (1fr, 1fr), column-gutter: 0.6em, row-gutter: 1em, ..doc.pages.map(data => image(bytes(data))).map(rect))


================================================
FILE: typ/embedded-typst/lib.typ
================================================

#let separator = "\n\n\n\n\n\n\n\n"

#let allocate-fonts(data) = (kind: "font", hash: none, data: data)

#let create-font-ref(data) = {
  let data = read(data, encoding: none)

  (kind: "font", data: data)
}

#let default-fonts() = (
  "/assets/typst-fonts/LinLibertine_R.ttf",
  "/assets/typst-fonts/LinLibertine_RB.ttf",
  "/assets/typst-fonts/LinLibertine_RBI.ttf",
  "/assets/typst-fonts/LinLibertine_RI.ttf",
  "/assets/typst-fonts/NewCMMath-Book.otf",
  "/assets/typst-fonts/NewCMMath-Regular.otf",
  "/assets/typst-fonts/NewCM10-Regular.otf",
  "/assets/typst-fonts/NewCM10-Bold.otf",
  "/assets/typst-fonts/NewCM10-Italic.otf",
  "/assets/typst-fonts/NewCM10-BoldItalic.otf",
  "/assets/typst-fonts/DejaVuSansMono.ttf",
  "/assets/typst-fonts/DejaVuSansMono-Bold.ttf",
  "/assets/typst-fonts/DejaVuSansMono-Oblique.ttf",
  "/assets/typst-fonts/DejaVuSansMono-BoldOblique.ttf",
)

#let default-cjk-fonts() = (
  "/assets/fonts/SourceHanSerifSC-Regular.otf",
  "/assets/fonts/SourceHanSerifSC-Bold.otf",
)

#let create-world(fonts) = {
  let base = plugin("/assets/artifacts/embedded_typst.wasm")
  let with-fonts = fonts.fold(
    base,
    (pre, path) => {
      let data = read(path, encoding: none)
      plugin.transition(pre.allocate_data, bytes("font"), data)
    },
  )

  plugin.transition(with-fonts.resolve_world)
}

#let _svg-doc(code, fonts) = {
  let typst-with-fonts = create-world(fonts)
  let (header, ..pages) = str(typst-with-fonts.svg(code)).split(separator)
  (header, pages)
}

#let svg-doc(code, fonts: none) = {
  let code = bytes(if type(code) == str {
    code
  } else {
    code.text
  })
  if fonts == none {
    fonts = default-fonts()
  }
  let (header, pages) = _svg-doc(code, fonts)
  (header: json(bytes(header)), pages: pages)
}



================================================
FILE: typ/templates/ebook.typ
================================================
#import "@preview/shiroa:0.2.3": *
#import "/typ/templates/page.typ": project, part-style, dash-color
#import "/typ/templates/term.typ": reset-term-state

#let _page-project = project

/// Show a title page with a full page background
#let cover(display-title) = {
  // #set text(fill: black, font: titleFont)
  // #if logo != none {
  //   place(top + center, pad(top:1cm, image(logo, width: 3cm)))
  // }
  stack(
    1fr,
    align(
      center + horizon,
      block(
        width: 100%,
        fill: dash-color.lighten(70%),
        height: 6.2cm,
        pad(x: 2cm, y: 1cm)[
          // #text(size: 3em, weight: 900, project-meta.display-title)
          #text(size: 3em, weight: 900, [The Raindrop-Blue Book])
          #v(1cm, weak: true)
          // #text(size: 3em, project-meta.at("subtitle", default: none))
          #text(size: 2em, display-title)
          #v(1cm, weak: true)
          #text(size: 1em, weight: "bold", "Myriad-Dreamin等著")
        ],
      ),
    ),
    2fr,
  )
}

#let p = counter("book-part")
#let p-num = numbering.with("1")
#let default-styles = (
  cover-image: "./rm175-noon-02.jpg",
  cover: cover,
  part: it => {
    //set image(width: 100%, height: 100%)
    page(
      margin: 0cm,
      header: none,
      background: [
        #move(dy: 3%, scale(x: -130%, y: 130%, rotate(38.2deg, image("./rustacean-flat-gesture.svg", width: 130%))))
      ],
      {
        p.step()
        stack(
          1fr,
          align(
            right + bottom,
            block(
              width: 100%,
              fill: dash-color.lighten(70%),
              height: 6.2cm,
              pad(x: 1cm, y: 1cm)[
                #set text(size: 32pt)
                #v(1em)
                #context {
                  let loc = here()
                  heading([Part.#p-num(..p.at(loc))#sym.space] + it)
                }
              ],
            ),
          ),
          2fr,
        )
      },
    )
  },
  chapter: it => reset-term-state + it,
)

#let project(title: "", display-title: none, authors: (), spec: "", content, styles: default-styles) = {
  let display-title = display-title
  if display-title == none {
    display-title = title
  }

  // inherit styles
  let styles = default-styles + styles

  // set document metadata early
  set document(
    author: authors,
    title: title,
  )

  // set web/pdf page properties
  set page(numbering: "1")

  // todo: abstraction
  {
    // inherit from page setting
    show: _page-project.with(title: none, kind: none)

    //set image(width: 100%, height: 100%)
    set page(
      margin: 0cm,
      header: none,
      background: [
        #place({
          set block(spacing: -0.1em)
          image("./circuit-board.svg", width: 100%)
          image("./circuit-board.svg", width: 100%)
        })
        #move(dy: 3%, scale(x: -130%, y: 130%, rotate(38.2deg, image("./rustacean-flat-gesture.svg", width: 130%))))
      ],
    )

    // place book meta
    external-book(spec: (styles.inc)(spec))
    (styles.cover)(display-title)
  }

  context {
    let loc = here()
    let project-meta = (title: title, display-title: display-title, book: book-meta-state.final(), styles: styles)

    {
      // inherit from page setting
      show: _page-project.with(title: none, kind: none)

      // set web/pdf page properties
      set page(numbering: none)

      include "/src/prefaces/license.typ"
      include "/src/prefaces/acknowledgement.typ"

      let outline-numbering-base = numbering.with("1.")
      let outline-numbering(a0, ..args) = if a0 > 0 {
        h(1em * args.pos().len())
        outline-numbering-base(a0, ..args) + [ ]
      }

      let outline-counter = counter("outline-counter")
      show outline.entry: it => {
        let has-part = if it.body().func() != none and "children" in it.body().fields() {
          for ch in it.body().children {
            if "text" in ch.fields() and ch.text.contains("Part") {
              ch.text
            }
          }
        }

        let numbering = if has-part == none {
          outline-counter.step(level: it.level + 1)
          context outline-counter.display(outline-numbering)
        } else {
          outline-counter.step(level: 1)
        }
        link(it.element.location(), text(black, it.indented(numbering + it.prefix(), it.inner())))
      }

      set outline.entry(fill: repeat[.])
      outline(depth: 1)
    }

    if project-meta.book != none {
      project-meta.book.summary.map(it => visit-summary(it, styles)).sum()
    }
  }

  content
}


================================================
FILE: typ/templates/page.typ
================================================

// This is important for typst-book to produce a responsive layout
// and multiple targets.
#import "@preview/shiroa:0.2.3": get-page-width, is-pdf-target, is-web-target, plain-text, target, templates
#import templates: *
#import "template-link.typ": *
#import "/typ/templates/side-notes.typ": side-attrs

// Metadata
#let page-width = get-page-width()
#let is-pdf-target = is-pdf-target()
#let is-web-target = is-web-target()

// Theme (Colors)
#let (
  style: theme-style,
  is-dark: is-dark-theme,
  is-light: is-light-theme,
  main-color: main-color,
  dash-color: dash-color,
  code-extra-colors: code-extra-colors,
) = book-theme-from(toml("theme-style.toml"), xml: it => xml(it))

// Sizes
#let main-size = if is-web-target {
  16pt
} else {
  10.5pt
}

#let heading-sizes = if is-web-target {
  (36pt, 26pt, 22pt, 18pt, main-size)
} else {
  (26pt, 22pt, 14pt, 12pt, main-size)
}
#assert(
  heading-sizes.at(-1) < heading-sizes.at(-2),
  message: "The second smallest heading size should be larger than the paragraph size (main-size).",
)

#let list-indent = 0.5em
#let par-leading = if is-web-target {
  0.8em
} else {
  // typst's default
  0.65em
}
// 1.2, 1.5 * this parameter
#let block-spacing = if is-web-target {
  par-leading * 1.5
} else {
  0.7em
}
#let heading-below = block-spacing * 1.
#let heading-spacing = heading-below * 1.5

// Fonts
#let use-fandol-fonts = false
#let main-font-cn = {
  if is-web-target {
    ("Noto Sans CJK SC",)
  } else if use-fandol-fonts {
    ("FandolSong",)
  }
  ("Source Han Serif SC",)
}

#let code-font-cn = ("Noto Sans CJK SC",)

#let main-font = if use-fandol-fonts {
  ("New Computer Modern", ..main-font-cn)
} else {
  (
    // "Charter",
    // typst-book's embedded font
    "Libertinus Serif",
    ..main-font-cn,
  )
}

#let code-font = (
  "BlexMono Nerd Font Mono",
  // typst-book's embedded font
  "DejaVu Sans Mono",
  ..code-font-cn,
)

// todo: move code theme parser to another lib file
#let code-theme-file = theme-style.at("code-theme")

#let code-extra-colors = if code-theme-file.len() > 0 {
  let data = xml(theme-style.at("code-theme")).first()

  let find-child(elem, tag) = {
    elem.children.find(e => "tag" in e and e.tag == tag)
  }

  let find-kv(elem, key, tag) = {
    let idx = elem.children.position(e => "tag" in e and e.tag == "key" and e.children.first() == key)
    elem.children.slice(idx).find(e => "tag" in e and e.tag == tag)
  }

  let plist-dict = find-child(data, "dict")
  let plist-array = find-child(plist-dict, "array")
  let theme-setting = find-child(plist-array, "dict")
  let theme-setting-items = find-kv(theme-setting, "settings", "dict")
  let background-setting = find-kv(theme-setting-items, "background", "string")
  let foreground-setting = find-kv(theme-setting-items, "foreground", "string")
  (bg: rgb(background-setting.children.first()), fg: rgb(foreground-setting.children.first()))
} else {
  (bg: rgb(239, 241, 243), fg: none)
}

#let make-unique-label(it, disambiguator: 1) = label({
  let k = plain-text(it).trim()
  if disambiguator > 1 {
    k + "_d" + str(disambiguator)
  } else {
    k
  }
})

#let heading-reference(it, d: 1) = make-unique-label(it.body, disambiguator: d)

// The project function defines how your document looks.
// It takes your content and some metadata and formats it.
// Go ahead and customize it to your liking!
#let project(title: "Typst中文教程", authors: (), kind: "page", body) = {
  let is-ref-page = kind == "reference-page"
  let is-page = kind == "page"

  // set basic document metadata
  set document(
    author: authors,
    title: title,
  ) if not is-pdf-target

  // set web/pdf page properties
  set page(
    numbering: if is-pdf-target {
      "1"
    },
  )

  // set web/pdf page properties
  set page(
    number-align: center,
    width: page-width,
  )

  // remove margins for web target
  set page(
    margin: (
      // reserved beautiful top margin
      top: 20pt,
      // reserved for our heading style.
      // If you apply a different heading style, you may remove it.
      left: 20pt,
      // Typst is setting the page's bottom to the baseline of the last line of text. So bad :(.
      bottom: 0.5em,
      // remove rest margins.
      rest: 0pt,
    ),
    height: auto,
  ) if is-web-target

  // set text style
  set text(
    font: main-font,
    size: main-size,
    fill: main-color,
    lang: "zh",
    region: "cn",
  )
  set block(spacing: block-spacing)

  let ld = state("label-disambiguator", (:))
  let update-ld(k) = ld.update(it => {
    it.insert(k, it.at(k, default: 0) + 1)
    it
  })
  let get-ld(loc, k) = make-unique-label(k, disambiguator: ld.at(loc).at(k))

  // show regex("[A-Za-z]+"): set text(font: main-font-en)
  let cjk-markers = regex("[“”‘’．，。、？！：；（）｛｝［］〔〕〖〗《》〈〉「」【】『』─—＿·…\u{30FC}]+")
  show cjk-markers: set text(font: main-font-cn)
  show raw: it => {
    show cjk-markers: set text(font: code-font-cn)
    it
  }
  // show regex("[a-zA-Z\s\#\[\]]+"): set text(baseline: -0.05em)
  // show regex("[“”]+"): set text(font: main-font-cn)

  // Set text, spacing for headings
  // Render a hash to hint headings instead of bolding it as well if it's for web.
  show heading: set text(weight: "regular") if is-web-target
  show heading: it => {
    let it = {
      set text(size: heading-sizes.at(it.level))
      if is-web-target {
        heading-hash(it, hash-color: dash-color)
      }
      it
    }

    block(
      spacing: heading-spacing,
      below: heading-below,
      it,
    )
  }

  // link setting
  show link: set text(fill: dash-color)

  // math setting
  show math.equation: set text(weight: 400)

  // code block setting
  show raw: it => {
    if "block" in it.fields() and it.block {
      rect(
        width: 100%,
        inset: (x: 4pt, y: 5pt),
        radius: 2pt,
        stroke: none,
        fill: code-extra-colors.at("bg"),
        [
          #set text(font: code-font)
          #set text(fill: code-extra-colors.at("fg")) if code-extra-colors.at("fg") != none
          #set par(justify: false)
          #it
        ],
      )
    } else {
      set text(
        font: code-font,
        baseline: -0.08em,
      )
      it
    }
  }

  // figure setting
  set rect(stroke: main-color)
  set table(stroke: main-color)

  show <typst-raw-func>: it => {
    let children = it.lines.at(0).body.children
    let rb = children.position(e => e.at("text", default: none) == "(")
    children.slice(0, rb).join()
  }


  if title != none {
    if is-web-target {
      // [= #title]
    } else {
      v(0.5em)
      align(center, [= #title])
      v(1em)
    }
  }

  // Main body.
  set par(leading: par-leading, justify: true)

  if is-ref-page {
    let side-space = 4 * main-size
    let side-overflow = 2 * main-size
    let gutter = 1 * main-size
    grid(
      columns: (side-space, 100% - side-space - gutter),
      column-gutter: gutter,
      place(
        dx: -side-overflow,
        block(
          breakable: true,
          width: side-space + side-overflow,
          context {
            let loc = here()
            side-attrs.update(it => {
              it.insert("left", loc.position().x)
              it.insert("width", side-space + side-overflow)
              it.insert("gutter", gutter)
              it
            })
          },
        ),
      ),
      body,
    )
  } else if is-page {
    side-attrs.update(it => {
      it.insert("left", 0pt)
      it.insert("width", 0pt)
      it.insert("gutter", 0pt)
      it
    })
    body
  } else {
    body
  }
}

#let part-style = heading


================================================
FILE: typ/templates/side-notes.typ
================================================

#let side-attrs = state("tuturial-side-note-attrs", (:))

#let side-note(dy: -0.65em, content) = context {
  let loc = here()
  let attr = side-attrs.get()
  // side-notes.update(it => {
  //   let p = str(loc.page())
  //   let arr = it.at(p, default: ())
  //   arr.push((loc.position().y, content))
  //   it.insert(p, arr)
  //   it
  // })
  box(
    width: 0pt,
    box(
      width: attr.width,
      place(
        left,
        dy: dy,
        dx: attr.left - loc.position().x,
        {
          set text(size: 10.5pt)
          content
        },
      ),
    ),
  )
}



================================================
FILE: typ/templates/template-link.typ
================================================

// #import "supports-text.typ": plain-text
#import "@preview/shiroa:0.2.3": plain-text

#let make-unique-label(it, disambiguator: 1) = label({
  let k = plain-text(it).trim()
  if disambiguator > 1 {
    k + "_d" + str(disambiguator)
  } else {
    k
  }
})

#let label-disambiguator = state("label-disambiguator", (:))
#let update-label-disambiguator(k) = label-disambiguator.update(it => {
  it.insert(k, it.at(k, default: 0) + 1)
  it
})
#let get-label-disambiguator(loc, k) = make-unique-label(k, disambiguator: label-disambiguator.at(loc).at(k))

#let heading-reference(it, d: 1) = make-unique-label(it.body, disambiguator: d)

#let enable-heading-hash = state("enable-heading-hash", true)

#let heading-hash(it, hash-color: blue) = {
  let title = plain-text(it.body)
  if title != none {
    let title = title.trim()
    update-label-disambiguator(title)
    context if enable-heading-hash.get() {
      let loc = here()
      let dest = get-label-disambiguator(loc, title)
      let h = measure(it.body).height
      place(
        left,
        dx: -16pt,
        [
          #set text(fill: hash-color)
          #link(loc)[\#] #dest
        ],
      )
    }
  }
}


================================================
FILE: typ/templates/term.typ
================================================

#let term-state = state("term", (:))
#let reset-term-state = term-state.update(it => (:))

#let _term(term-list, term, en: none) = (
  context {
    let s = term-state.get()
    if term in s {
      [「#term-list.at(term)#("」")]
    } else {
      let en-term = term
      if en != none {
        en-term = en
      }
      [「#term-list.at(term)」（#en-term#("）")]
    }
  }
    + term-state.update(it => {
      it.insert(term, "")
      it
    })
)


================================================
FILE: typ/templates/theme-style.toml
================================================

[light]
color-scheme = "light"
main-color = "#000"
dash-color = "#20609f"
code-theme = ""

[rust]
color-scheme = "light"
main-color = "#262625"
dash-color = "#2b79a2"
code-theme = ""

[coal]
color-scheme = "dark"
main-color = "#98a3ad"
dash-color = "#2b79a2"
code-theme = "/assets/files/tokyo-night.tmTheme"

[navy]
color-scheme = "dark"
main-color = "#bcbdd0"
dash-color = "#2b79a2"
code-theme = "/assets/files/tokyo-night.tmTheme"

[ayu]
color-scheme = "dark"
main-color = "#c5c5c5"
dash-color = "#0096cf"
code-theme = "/assets/files/tokyo-night.tmTheme"


================================================
FILE: typ/typst-meta/docs.typ
================================================


#let iterate-scope(env, scope, belongs) = {
  let p = (..scope.path, scope.name).join(".")
  scope.insert("belongs", belongs)
  env.scoped-items.insert(p, scope)

  if "scope" in scope {
    let belongs = (kind: "scope", name: scope.name)
    for c in scope.scope {
      env = iterate-scope(env, c, belongs)
    }
  }

  return env
}

#let iterate-docs(env, route, path) = {
  if route.body.kind == "func" {
    env.funcs.insert(route.body.content.name, route)
  } else if route.body.kind == "type" {
    env.types.insert(route.body.content.name, route)

    // iterate-scope()
    if "scope" in route.body.content {
      let belongs = (kind: "type", name: route.body.content.name)
      for c in route.body.content.scope {
        env = iterate-scope(env, c, belongs)
      }
    }
  }

  for ch in route.children {
    env = iterate-docs(env, ch, path + (route.title,))
  }

  return env
}

#let load-docs() = {
  let m = json("/assets/artifacts/typst-docs-v0.11.0.json")
  let env = (funcs: (:), types: (:), scoped-items: (:))
  for route in m {
    env = iterate-docs(env, route, ())
  }

  return env
}

#let typst-v11 = load-docs()