PreTeXt 学习教程

注意: TeXLive 完整安装约 5GB，如果只需要 HTML 输出可以跳过。

PreTeXt 学习教程

一、环境准备

前置知识

学习 PreTeXt 需要以下基础：

知识 程度 说明
XML 基础 必须 理解标签、属性、嵌套
LaTeX 数学 推荐 在 <m> 标签中使用 LaTeX 公式
命令行操作 必须 使用 CLI 工具构建项目
Python 可选 仅 CLI 安装需要 pip

安装步骤

1. 安装 PreTeXt CLI

# 使用 pip 安装（当前版本 2.37.2，需要 Python 3.10+）
python -m pip install --user pretext

# 验证安装
pretext --version

# 如果 pretext 不在 PATH 中
python -m pretext --version

2. 安装 TeXLive（PDF 输出需要）

# macOS
brew install --cask mactex

# Ubuntu/Debian
sudo apt install texlive-full

# 验证
xelatex --version

注意: TeXLive 完整安装约 5GB，如果只需要 HTML 输出可以跳过。

3. 安装 VS Code 扩展（推荐）

在 VS Code 中搜索并安装 oscarlevin.pretext-tools 扩展（或搜索 pretext-tools），提供： - .ptx 文件语法高亮 - LaTeX 数学公式识别 - XML 代码片段（覆盖大部分 PreTeXt 元素） - Schema 自动补全（配合 vscode-xml 扩展） - CLI 命令集成（状态栏菜单） - 快捷键: Ctrl-Alt-B 构建, Ctrl-Alt-V 预览, Ctrl-Alt-P 命令菜单 - LaTeX → PreTeXt 转换（实验性）

环境验证

# 检查 CLI
pretext --version

# 创建测试项目
pretext new "my-first-book"
cd my-first-book

# 尝试构建
pretext build html

二、快速开始

Hello World

第一步: 创建新项目

# 创建新项目（支持模板: book, article, course, demo, hello, slideshow）
pretext new "我的第一本书"       # 默认使用 book 模板
cd 我的第一本书

CLI 会生成以下项目结构：

我的第一本书/
├── project.ptx          # 项目配置文件
├── source/
│   └── main.ptx         # 主要内容文件
├── assets/              # 图片等资源
├── output/              # 构建输出目录
│   └── html/            # HTML 输出
└── publication/         # 发布配置

第二步: 编写内容

编辑 source/main.ptx：

<?xml version="1.0" encoding="utf-8"?>
<pretext>
  <book xml:id="my-first-book">
    <title>我的第一本 PreTeXt 书</title>
    <frontmatter>
      <titlepage>
        <author>
          <personname>张三</personname>
        </author>
      </titlepage>
    </frontmatter>

    <chapter xml:id="ch-hello">
      <title>你好，PreTeXt</title>
      <p>这是我的第一本 PreTeXt 书籍。PreTeXt 让我可以写一次，
        发布到多种格式。</p>
      <p>最令人兴奋的是数学公式的支持。比如欧拉公式：
        <me>e^{i\pi} + 1 = 0</me>
      </p>
    </chapter>
  </book>
</pretext>

第三步: 构建

# 构建 HTML 版本
pretext build html

# 构建 PDF 版本（需要 TeXLive）
pretext build pdf

# 查看结果
pretext view html

三、核心概念

概念图谱

PreTeXt 核心概念
├── 文档类型
│   ├── book（书籍）
│   ├── article（文章）
│   ├── letter（信件）
│   └── slideshow（幻灯片）
│
├── 文档结构
│   ├── frontmatter（前言部分）
│   ├── part（部分/卷）
│   ├── chapter（章）
│   ├── section（节）
│   ├── subsection（小节）
│   └── backmatter（后记部分）
│
├── 内容类型
│   ├── 段落与文本（p, blockquote）
│   ├── 数学（m, me, men）
│   ├── 列表（ol, ul, dl）
│   ├── 图片与媒体
│   ├── 程序代码
│   └── 表格
│
├── 学术元素
│   ├── 定理与证明
│   ├── 定义与公理
│   ├── 练习与解答
│   ├── 示例与活动
│   └── 参考文献
│
└── 输出格式
    ├── HTML（在线交互）
    ├── PDF（印刷版）
    ├── EPUB（电子书）
    ├── Jupyter Notebook
    ├── RevealJS（幻灯片）
    └── Braille（盲文）

核心概念详解

1. XML 文档结构

PreTeXt 文档是标准的 XML 文件，扩展名通常为 .ptx：

<?xml version="1.0" encoding="utf-8"?>
<!-- 这是 XML 声明 -->

<pretext>
  <!-- 根元素，所有内容都在这里 -->

  <book xml:id="unique-id">
    <!-- 文档主体 -->
  </book>

</pretext>

关键规则： - 所有标签必须闭合（<p>...</p> 或 <br/>） - 标签名大小写敏感（全部小写） - 属性值必须用引号包裹 - xml:id 提供唯一标识符，用于交叉引用

2. 数学排版

PreTeXt 使用 LaTeX 数学语法，通过不同的标签区分行内和行间公式：

<p>
  行内公式: 勾股定理 <m>a^2 + b^2 = c^2</m> 是基本定理。
</p>

<p>
  行间公式（无编号）:
  <me>\int_0^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}</me>
</p>

<p>
  行间公式（有编号）:
  <men xml:id="eq-euler">e^{i\theta} = \cos\theta + i\sin\theta</men>
  引用: 方程 (<xref ref="eq-euler"/>) 是欧拉公式。
</p>

3. 交叉引用

PreTeXt 的交叉引用系统自动处理编号：

<!-- 定义引用目标 -->
<chapter xml:id="ch-intro">
  <title>引言</title>
  ...
  <theorem xml:id="thm-main">
    <title>主定理</title>
    <statement><p>...</p></statement>
  </theorem>
  <figure xml:id="fig-diagram">
    <caption>示意图</caption>
    ...
  </figure>
</chapter>

<!-- 在其他位置引用 -->
<p>如 <xref ref="ch-intro"/> 所述，特别是定理 <xref ref="thm-main"/>
  和图 <xref ref="fig-diagram"/>。</p>

4. 文档划分

PreTeXt 支持多种文档类型和划分方式：

<!-- 书籍 -->
<book>
  <frontmatter>...</frontmatter>
  <part>
    <chapter>...</chapter>
    <chapter>
      <section>...</section>
      <section>
        <subsection>...</subsection>
      </section>
    </chapter>
  </part>
  <backmatter>...</backmatter>
</book>

<!-- 文章（无章节划分） -->
<article>
  <section>...</section>
  <section>...</section>
</article>

术语表

术语 说明
.ptx 文件 PreTeXt 源文件，本质是 XML
Schema RELAX-NG 模式定义，规定合法的文档结构
XSLT 转换语言，将 XML 转为输出格式
project.ptx 项目配置文件（注意: 不是源文件）
构建 (Build) 将源文件转换为输出格式的过程
生成 (Generate) 生成图片等资源的过程

四、功能详解

4.1 段落与文本

<!-- 基本段落 -->
<p>这是一个普通段落。</p>

<!-- 强调 -->
<p>这是<em>强调文本</em>和<alert>警告文本</alert>。</p>

<!-- 引用 -->
<blockquote>
  <p>数学是科学的女王。</p>
  <attribution>— 卡尔·弗里德里希·高斯</attribution>
</blockquote>

<!-- 列表 -->
<ol>
  <li>第一项</li>
  <li>第二项
    <ol>
      <li>嵌套项</li>
    </ol>
  </li>
</ol>

<ul>
  <li>无序列表项</li>
</ul>

<!-- 定义列表 -->
<dl>
  <li>
    <title>导数</title>
    <p>函数在某一点的瞬时变化率。</p>
  </li>
</dl>

4.2 数学环境

<!-- 定理 -->
<theorem xml:id="thm-fermat">
  <title>费马大定理</title>
  <creator>皮埃尔·德·费马</creator>
  <statement>
    <p>当整数 <m>n > 2</m> 时，不存在正整数 <m>x, y, z</m>
      使得 <m>x^n + y^n = z^n</m>。</p>
  </statement>
</theorem>

<!-- 证明 -->
<proof>
  <p>证明过程省略（Andrew Wiles, 1994）。</p>
</proof>

<!-- 定义 -->
<definition xml:id="def-continuity">
  <title>连续性</title>
  <statement>
    <p>函数 <m>f</m> 在点 <m>a</m> 连续，当且仅当
      <me>\lim_{x \to a} f(x) = f(a)</me></p>
  </statement>
</definition>

<!-- 引理、推论、命题 -->
<lemma xml:id="lem-helper">
  <statement><p>辅助引理内容</p></statement>
</lemma>

<corollary xml:id="cor-main">
  <statement><p>推论内容</p></statement>
</corollary>

<axiom xml:id="ax-field">
  <statement><p>域公理</p></statement>
</axiom>

4.3 练习系统

PreTeXt 的练习系统支持分阶段提示，适合教学：

<!-- 基本练习 -->
<exercise xml:id="ex-basic">
  <statement>
    <p>计算 <m>\int_0^1 x^2 dx</m>。</p>
  </statement>
  <hint>
    <p>使用幂函数积分公式。</p>
  </hint>
  <answer>
    <p><m>\frac{1}{3}</m></p>
  </answer>
  <solution>
    <p>
      <me>\int_0^1 x^2 dx = \frac{x^3}{3}\Big|_0^1 = \frac{1}{3}</me>
    </p>
  </solution>
</exercise>

<!-- WeBWorK 在线练习 -->
<exercise xml:id="ex-webwork">
  <title>在线练习</title>
  <webwork source="Library/ma123DB/set2/srw4_8_45.pg">
    <statement>
      <p>这道题目将通过 WeBWorK 系统在线评分。</p>
    </statement>
  </webwork>
</exercise>

4.4 图片和图形

<!-- 静态图片 -->
<figure xml:id="fig-graph">
  <caption>函数图像</caption>
  <image source="images/graph.png" width="60%"/>
</figure>

<!-- 使用 TikZ/PGF 绘图 -->
<figure xml:id="fig-tikz">
  <caption>TikZ 绘图</caption>
  <image>
    <latex-image>
      \begin{tikzpicture}
        \draw (0,0) circle (1);
        \draw (0,0) -- (1,0);
        \draw (0,0) -- (0.5,0.866);
      \end{tikzpicture}
    </latex-image>
  </image>
</figure>

<!-- 使用 Sage 生成图片 -->
<figure xml:id="fig-sage">
  <caption>Sage 绘图</caption>
  <sageplot>
    plot(sin(x), (x, -pi, pi), color='blue')
  </sageplot>
</figure>

<!-- 交互式图形 -->
<figure xml:id="fig-interactive">
  <caption>可交互的图形</caption>
  <interactive xml:id="int-geogebra" platform="geogebra">
    <slate xml:id="geogebra-slate" surface="geogebra"/>
  </interactive>
</figure>

4.5 程序代码

<!-- 代码块 -->
<listing xml:id="lst-python">
  <caption>Python 示例</caption>
  <input xml:id="lst-python-input">
    <cline>def fibonacci(n):</cline>
    <cline>    if n &lt;= 1:</cline>
    <cline>        return n</cline>
    <cline>    return fibonacci(n-1) + fibonacci(n-2)</cline>
  </input>
</listing>

<!-- 行内代码 -->
<p>使用 <c>print("Hello")</c> 输出文字。</p>

<!-- Sage Cell 可执行代码 -->
<sage xml:id="sage-example">
  <input>
    factor(x^2 - 1)
  </input>
</sage>

4.6 表格

<table xml:id="tbl-comparison">
  <title>方法对比</title>
  <caption>三种数值方法的精度对比</caption>
  <tabular>
    <col halign="left"/>
    <col halign="center"/>
    <col halign="center"/>
    <col halign="center"/>
    <thead>
      <row>
        <cell>方法</cell>
        <cell><m>n=10</m></cell>
        <cell><m>n=100</m></cell>
        <cell><m>n=1000</m></cell>
      </row>
    </thead>
    <tbody>
      <row>
        <cell>梯形法</cell>
        <cell><m>0.3324</m></cell>
        <cell><m>0.3333</m></cell>
        <cell><m>0.3333</m></cell>
      </row>
      <row>
        <cell>Simpson 法</cell>
        <cell><m>0.3333</m></cell>
        <cell><m>0.3333</m></cell>
        <cell><m>0.3333</m></cell>
      </row>
    </tbody>
  </tabular>
</table>

4.7 参考文献与引用

<!-- 在 backmatter 中定义参考文献 -->
<backmatter>
  <references>
    <title>参考文献</title>
    <biblio type="book" xml:id="bib-spivak">
      <author><personname>Michael Spivak</personname></author>
      <title>Calculus</title>
      <year>2006</year>
      <publisher>Publish or Perish</publisher>
    </biblio>
    <biblio type="article" xml:id="bib-wiles">
      <author><personname>Andrew Wiles</personname></author>
      <title>Modular elliptic curves and Fermat's Last Theorem</title>
      <year>1995</year>
      <journal>Annals of Mathematics</journal>
    </biblio>
  </references>
</backmatter>

<!-- 在正文中引用 -->
<p>参见 <xref ref="bib-spivak"/> 和 <xref ref="bib-wiles"/>。</p>

五、CLI 工具详解

常用命令

# 项目管理
pretext new "项目名称"          # 创建新项目（模板: book, article, course, demo, hello, slideshow）
pretext init                    # 在当前目录初始化项目文件
pretext update                  # 更新项目文件以匹配当前 CLI 版本

# 构建（完整支持格式: html, pdf, latex, epub, kindle, braille, revealjs, webwork, custom）
pretext build html              # 构建 HTML
pretext build pdf               # 构建 PDF
pretext build epub              # 构建 EPUB
pretext build latex             # 生成 LaTeX 源文件
pretext build revealjs          # 构建 RevealJS 幻灯片
pretext build --clean           # 清理后重新构建
pretext build -g html           # 构建前自动生成资源

# 资源生成
pretext generate                # 生成所有资源（图片、交互元素等）
pretext generate -x sec-id      # 只生成指定 xml:id 的资源
pretext generate -q             # 只生成有变化的资源
pretext generate --all-formats  # 为所有格式生成资源

# 预览
pretext view html               # 在浏览器中预览 HTML（默认端口 8128）
pretext view html -p 3000       # 指定端口预览
pretext view -b html            # 预览前自动构建
pretext view -s                 # 停止预览服务器

# 部署
pretext deploy                  # 部署到 GitHub Pages
pretext deploy --no-push        # 只准备部署，不推送

# 转换
pretext import paper.tex        # 实验性: LaTeX → PreTeXt 转换

# 验证与诊断
pretext validate                # 验证源文件是否符合 Schema
pretext support                 # 输出诊断信息用于寻求支持

# 其他
pretext --help                  # 帮助
pretext --version               # 版本信息
pretext -t                      # 列出所有构建目标

project.ptx 配置文件

<?xml version="1.0" encoding="utf-8"?>
<pretext-project>
  <title>我的教材</title>

  <source>
    <directory>source</directory>
    <main>main.ptx</main>
  </source>

  <targets>
    <target name="html" format="html">
      <output-directory>output/html</output-directory>
    </target>
    <target name="pdf" format="pdf">
      <output-directory>output/pdf</output-directory>
    </target>
  </targets>

  <assets>
    <directory>assets</directory>
  </assets>
</pretext-project>

典型工作流

1. 创建项目    pretext new "我的数学书"
2. 编写内容    编辑 source/main.ptx
3. 验证结构    pretext validate
4. 构建 HTML   pretext build html
5. 预览结果    pretext view html
6. 迭代修改    回到第2步
7. 生成图片    pretext generate
8. 构建 PDF    pretext build pdf
9. 部署上线    pretext deploy（部署到 GitHub Pages）

项目模板

pretext new 支持多种模板：

模板 说明
book（默认） 完整书籍模板
article 短文/文章模板
course 课程模板
demo 功能演示模板
hello 最小 Hello World 模板
slideshow 幻灯片模板 
pretext new "我的文章"        # 默认 book 模板
pretext new "课件" article    # 使用 article 模板
pretext new "demo" demo       # 功能演示

六、进阶主题

6.1 资产生成详解

pretext generate 支持以下资产类型：

资产类型 说明 适用格式
webwork WeBWorK 在线练习 所有格式
latex-image TikZ/PGF 绘图 HTML, EPUB, Braille, RevealJS
sageplot Sage 数学绘图 所有格式
asymptote Asymptote 3D 图形 所有格式
prefigure Prefigure 图形 HTML, PDF, LaTeX, RevealJS
youtube YouTube 视频缩略图 PDF, LaTeX, EPUB, Kindle, Braille
codelens 代码步进展示 所有格式
interactive 交互元素静态替代 PDF, LaTeX, EPUB, Kindle, Braille
mermaid Mermaid 流程图 PDF, LaTeX, EPUB, Kindle
qrcode 二维码 PDF, LaTeX, EPUB, Kindle 
# 常用命令
pretext generate                # 生成所有资源
pretext generate -q             # 只生成有变化的（增量）
pretext generate --clean        # 清除后重新生成
pretext generate -f             # 强制重新生成

6.2 自定义样式

PreTeXt 支持通过 CSS 自定义 HTML 输出样式：

publication/
└── custom.css

在 project.ptx 中引用：

<targets>
  <target name="html" format="html">
    <output-directory>output/html</output-directory>
    <extra-css>publication/custom.css</extra-css>
  </target>
</pretext-project>

6.3 Sage Cell 集成

Sage Cell 允许读者在浏览器中直接执行代码：

<sage xml:id="sage-demo">
  <input>
    # 读者可以直接运行这段代码
    var('x')
    f = x^3 - 3*x + 1
    plot(f, (x, -2, 2), color='red')
  </input>
</sage>

HTML 输出会自动嵌入 Sage Cell 服务器，读者点击即可运行。

6.4 多文件项目

大型项目可以拆分为多个文件：

source/
├── main.ptx           # 主文件，包含 <pretext> 根元素
├── chapter1.ptx       # 第一章
├── chapter2.ptx       # 第二章
├── exercises.ptx      # 练习题
└── images/            # 图片资源

在主文件中使用 xi:include 引入：

<?xml version="1.0" encoding="utf-8"?>
<pretext xmlns:xi="http://www.w3.org/2001/XInclude">
  <book xml:id="my-book">
    <title>我的教材</title>
    <xi:include href="chapter1.ptx"/>
    <xi:include href="chapter2.ptx"/>
  </book>
</pretext>

6.5 国际化支持

PreTeXt 支持多语言文档：

<book xml:lang="zh-CN">
  <title>中文数学教材</title>
  ...
</book>

6.6 部署到 Runestone

Runestone 平台提供免费的交互式教材托管：

# 构建 Runestone 兼容格式
pretext build runestone

# 使用 runestone 命令部署
# （需要 Runestone 账号）

七、常见问题

Q1: PreTeXt 和 MathBook XML 是什么关系？

MathBook XML 是 PreTeXt 的前身。2018 年项目更名为 PreTeXt，以反映其超越数学领域的应用。两者是同一个项目。

Q2: 我必须用 XML 吗？能用 Markdown 吗？

PreTeXt 必须使用 XML 格式。XML 的严格结构是 PreTeXt 实现多格式输出和语义标记的基础。Markdown 太过松散，无法表达定理、证明等学术结构。

Q3: 学习 PreTeXt 需要先学 LaTeX 吗？

不需要。但如果你需要在文档中使用数学公式，需要了解 LaTeX 数学语法（这是几乎所有数学排版系统共用的）。PreTeXt 的文档结构本身与 LaTeX 无关。

Q4: PreTeXt 输出的 PDF 质量如何？

非常好。PreTeXt 实际上是通过 XSLT 将 XML 转换为 LaTeX，然后用 TeXLive 编译为 PDF。因此 PDF 输出继承了 LaTeX 的高质量排版。

Q5: 构建时报 Schema 验证错误怎么办？

# 使用 validate 命令检查
pretext validate

# 常见错误:
# 1. 标签未闭合 → 检查 XML 结构
# 2. 嵌套层次错误 → 查阅文档确认允许的嵌套关系
# 3. 属性值缺失 → 检查必要属性（如 xml:id）

Q6: 如何处理中文内容？

<!-- 在文档根元素指定语言 -->
<book xml:lang="zh-CN">

<!-- PDF 输出可能需要配置中文字体 -->
<!-- 在 project.ptx 中配置 XeLaTeX 选项 -->

Q7: 能否将已有的 LaTeX 文档转换为 PreTeXt？

PreTeXt CLI 提供了实验性的 LaTeX 导入功能：

pretext import paper.tex -o output.ptx

但由于 LaTeX 的自由度很高，自动转换不可能完美。建议用于快速起步，然后手动调整。

Q8: 多人协作怎么管理？

推荐使用 Git 进行版本控制： - .ptx 文件是纯文本，天然适合 Git - 使用 XInclude 拆分文件，每人负责不同章节 - GitHub/GitLab 提供 PR 审查流程

八、参考资料

官方资源

  • 官方网站: https://pretextbook.org
  • GitHub 仓库: https://github.com/PreTeXtBook/pretext
  • CLI 文档: https://github.com/PreTeXtBook/pretext-cli
  • 项目目录: https://pretextbook.org/catalog.html

社区资源

  • PreTeXt Google Group: 主要的社区讨论平台
  • PreTeXt Discord: 实时交流
  • MAA（美国数学协会）: PreTeXt 的主要推广组织

学习资源

  • PreTeXt Guide（权威文档）: 包含 For Authors, Basics Reference, For Publishers, For Developers 等章节
  • PreTeXt 示例项目: GitHub 仓库中的 examples/ 目录（sample article 包含"每种元素的示例"）
  • "Git for Authors" 书籍: Rob Beezer 和 David Farmer 合著，教授作者使用 Git 管理手稿
  • Runestone Academy: 大量使用 PreTeXt 的在线教材

相关工具

  • VS Code PreTeXt 扩展: 编辑和预览
  • oXygen XML Editor: 商业 XML 编辑器，对 RELAX-NG 支持优秀
  • SageMath: PreTeXt 集成的计算系统

学习路线图

第1周: 基础入门
├── 安装环境和 CLI
├── 创建第一个项目
├── 理解 XML 基本结构
└── 成功构建 HTML 和 PDF

第2周: 文档结构
├── 学习章节划分（chapter/section/subsection）
├── 掌握段落、列表、引用
├── 练习交叉引用系统
└── 编写一个完整的章节

第3周: 数学排版
├── 行内和行间公式
├── 定理、证明、定义环境
├── 练习系统（hint/answer/solution）
└── 编写一份包含完整数学内容的章节

第4周: 高级功能
├── 图片和图形（TikZ、SagePlot）
├── 程序代码展示
├── 交互式元素（Sage Cell）
└── 表格和参考文献

第5周+: 项目实战
├── 多文件项目管理
├── 自定义样式
├── 部署和发布
└── 贡献到 PreTeXt 社区