feat: 《文件与模块》修订1

src/intermediate/modulize-modules.typ

@@ -1,26 +1,28 @@
 #import "mod.typ": *
 
-#show: book.page.with(title: "模块化文档")
+#show: book.page.with(title: [文件与模块])
 
-正如我们在《基础文档》中所说的，Typst提供了脚本语言方便排版。但事实上，若是能少写甚至不写脚本，便能完成排版，这才算便捷之至。我们总希望Typst能够允许我们以一种优雅的方式#strike[复制粘贴]引入已有代码。理想情况下，当某位前辈为我们准备好了模板，我们可以只用两行代码便可完成排版的配置：
+正如我们在《初识脚本模式》中所说的，Typst提供了脚本语言方便排版。但事实上，写作时若能少写甚至不写脚本，这才算真正的便捷。我们总希望Typst能够允许我们以一种优雅的方式#strike[复制粘贴]引入已有代码。理想情况下，只需两行代码便可引入前辈写好的模板：
 
 #```typ
 #import "@preview/senpai-no-awesome-template.typ:0.x.x": *
 #show: template.with(..)
 ```
 
-模块便是为复制而生。Typst的模块（module）机制非常简单：每个文件都是一个独立的模块。它允许你：
-+ 在本地工作区内，在多个文档之间共享你爱用的排版函数。
+模块便是为复制而生。
+
+
+Typst的模块（module）机制非常简单：每个文件都是一个独立的模块。它允许你：
 + 将一份文档分作多个文件编写。
-+ 通过本地注册或网络共享，使用外部模板或库。
++ 使用本机器或网上的模板或库。
 
-本节主要伴随讲解一些日常使用模块机制时所遇到的问题。由于Typst的模块机制过于简单，本节将不会涉及很多需要理解的地方。
+由于Typst的模块机制过于简单，本节主要伴随讲解一些日常使用模块机制时所遇到的问题，而不会涉及很多需要理解的地方。
 
 == 根目录
 
-根目录的概念是Typst自0.1.0开始就引入的。根目录是一个重要的编译参数。在早期，Typst就禁止访问*根目录以外的内容*。尽管扩大可访问的文件数量在某种程度上增进了便捷性，也意味着降低了执行Typst脚本的安全性。这是因为，根目录下所有的子文件夹和子文件都有机会被*你编写的或其他人编写（外部库）的Typst脚本访问*。
+根目录是一个重要的编译参数。Typst早在v0.1.0时就禁止访问*根目录以外的内容*，以保证安全执行代码。最坏情况下，*其他人编写的Typst脚本（来自互联网）*可以访问根目录下所有的文件。
 
-简单来说，文档一般可以访问文档所在目录的资源。如果需要访问文档所在目录以外其他资源，则需要配置*根目录*。有的时候，你所使用的工具会为你自动配置*根目录*。
+你所使用的工具可能会为你自动配置*根目录*。
 
 #pro-tip[
   + 当你使用`typst-cli`程序时，根目录默认为文档所在目录。你也可以通过`--root`命令行参数手动指定一个根目录。例如你可以指定当前工作目录的父文件夹作为编译程序的根目录：
@@ -31,37 +33,26 @@
   + 当你使用VSCode的tinymist或typst-preview程序时，为了方便多文件的编写，根目录默认为你所打开的文件夹。如果你打开一个VSCode工作区，则根目录相对于离你所编辑文件最近的工作目录。
 ]
 
-一个常见的错误做法是，为了共享本地代码或模板，在使用`typst-cli`的时候将根目录指定为系统的根目录。
-- 如果你是Windows用户，则以下使用方法将有可能导致个人隐私泄露：
-
-  ```bash
-  typst c --root C:\
-  ```
-
-  并访问你系统中的某处文件。
+一个常见的错误做法是，为了共享本地代码或模板，在使用`typst-cli`的时候将根目录指定为系统的根目录。以下使用方法将有可能导致个人隐私泄露：
 
-  ```typ
-  #import "/Users/me/templates/book.typ": book-template
-  ```
-- 如果你是Linux或macOS用户，则以下使用方法将有可能导致个人隐私泄露：
-
-  ```bash
-  typst c --root /
-  ```
+```bash
+typst c --root "C:\\" # Windows
+typst c --root / # Linux或macOS
+```
 
-  并访问你系统中的某处文件。
+并访问你系统中的某处文件。
 
-  ```typ
-  #import "/home/me/templates/book.typ": book-template
-  ```
+```typ
+#import "/Users/me/templates/book.typ": book-template
+```
 
-本节将介绍另外一种方式——通过在注册本地包在你的多个Typst项目之间共享代码。
+本节将介绍另外一种创建本地「库」（package）的方式以在Typst项目之间安全地共享代码和资源。
 
 == 绝对路径与相对路径
 
 我们已经讲解过`read`函数和`include`语法，其中都有路径的概念。
 
-如果路径以字符`/`开头，则其为「绝对路径」。绝对路径相对于根目录解析。若设置了根目录为#text(red, `/OwO/`)，则路径`/a/b/c`对应路径#text(red, `/OwO/`)`a/b/c`。
+如果路径以字符`/`开头，则其为「绝对路径」。绝对路径相对于「根目录」解析。若设置了根目录为#text(red, `/OwO/`)，则路径`/a/b/c`对应路径#text(red, `/OwO/`)`a/b/c`。
 
 #code(
   ```typ
@@ -81,7 +72,7 @@
 
 == 「import」语法与「模块」
 
-Typst中的模块概念相当简单，你只需记住：每个文件都是一个模块。
+Typst中的模块概念相当简单。你只需记住：每个文件都是一个模块。
 
 #let m1-code = raw(read("packages/m1.typ").trim().replace("\r", ""), lang: "typ", block: true)
 
@@ -150,33 +141,25 @@ Typst中的模块概念相当简单，你只需记住：每个文件都是一个
 
 == 「include」语法与「import」语法的关系
 
-在Typst内部，当解析完一个文件时，文件将被分为顶层作用域中的「内容」和「变量声明」，组成一个文件模块。
+在Typst内部，当解析完一个文件时，文件将被分为顶层作用域中的「内容」和「变量声明」，共同组成一个文件模块。`include`取其「内容」，`import`则取其「变量声明」。
 
-例如对于`packages/m1.typ`文件：
-
-#m1-code
+仍然以前文中的`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
 ```
 

src/intermediate/packages/m1.typ

@@ -1,11 +1,5 @@
 
-一段内容
-
+XXX
 #let add(x, y) = x + y
-
-另一段内容
-
-#let sub = {
-  let sub(x, y) = x - y
-  sub
-}
+YYY
+#let sub(x, y) = x - y

src/introduction.typ

@@ -159,7 +159,7 @@ typst watch file.typ
 
 + 接着，阅读《基础教程》脚本Ⅱ和排版Ⅲ的五篇文章。
 
-  这两部分分别介绍了如何使用Typst的模块功能与状态功能。模块允许你将文档拆分为多个文件。状态则类似于其他编程语言中的全局变量的概念，可用于收集和维护数据。
+  这两部分分别介绍了如何使用Typst的模块机制与状态机制。模块允许你将文档拆分为多个文件。状态则类似于其他编程语言中的全局变量的概念，可用于收集和维护数据。
 
 + 最后，同时阅读《基础参考》和《进阶教程》。你可以根据你的需求挑选《基础参考》的部分章节阅读。即便不阅读任何《基础参考》中的内容，你也可以继续阅读《进阶教程》。
 

src/mod.typ

@@ -124,8 +124,14 @@
   )
 }
 
+#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: left) = {
+#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 {
@@ -134,13 +140,13 @@
 
   let vv = exec-code(cc, res: res, scope: scope, eval: eval)
   if al == left {
-    layout(lw => style(styles => {
+    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, styles)
-      let v-box = measure(v, styles)
+      let u-box = measure(u)
+      let v-box = measure(v)
 
       let height = calc.max(u-box.height, v-box.height)
       stack(
@@ -154,7 +160,7 @@
           rect(height: height, width: width, inset: 10pt, vv.body)
         },
       )
-    }))
+    })
   } else {
     code-as
     vv