PreTeXt 调研报告

一、项目概述

基本信息

一句话介绍

PreTeXt 是一个基于 XML 的学术文档创作与出版系统，专为数学、科学、工程等 STEM 学科设计，支持从单一源文件生成 HTML、PDF、EPUB、Jupyter Notebook、Braille 等多种输出格式。

发展历程

• 2013 年: 项目由 Rob Beezer（华盛顿大学数学系教授）创建，最初名为 "MathBook XML"
• 早期阶段: 专注于数学教材的 XML 标记语言设计，核心是 RELAX-NG 模式定义
• 2017 年: 更名为 PreTeXt（从 MathBook XML 改名），强调其超越数学的通用学术出版能力
• 早期版本: v0.01 (2014/04/30), v0.02 (2015/03/18), v0.03 (2016/04/23) 均以 MathBook XML 名称发布
• 2019-2021 年: 开发 Python CLI 工具（pretext 包），简化构建流程
• 2022-2024 年: 生态持续扩展——VS Code 扩展、Runestone 交互平台集成、EPUB 输出
• 2025-2026 年: 持续活跃开发，已有 80+ 本教材使用 PreTeXt 发布

二、核心功能

功能概览

核心功能详解

1. 单源多格式发布

PreTeXt 的核心设计理念：写一次，到处发布。

          ┌──→ HTML（在线阅读，交互式）
          │
          ├──→ PDF（印刷版，LaTeX 驱动）
          │
          ├──→ LaTeX 源文件（中间产物）
          │
XML 源 ──→├──→ EPUB / Kindle（电子书）
          │
          ├──→ Jupyter Notebook（可执行计算）
          │
          ├──→ RevealJS 幻灯片
          │
          ├──→ Braille（盲文输出）
          │
          ├──→ WeBWorK（在线作业）
          │
          └──→ Custom（自定义格式）

这种能力通过 XSLT 转换实现——仓库中 XSLT 代码占 75.6%，是整个系统的技术核心。

2. 学术文档标记语言

PreTeXt 定义了一套完整的 XML 词汇表，涵盖学术文档的所有结构元素：

<pretext>
  <book xml:id="my-book">
    <title>我的数学教材</title>
    <frontmatter>
      <preface>前言内容</preface>
    </frontmatter>
    <chapter xml:id="ch-intro">
      <title>引言</title>
      <section xml:id="sec-basics">
        <title>基本概念</title>
        <p>这是一个段落，可以包含
          <m>x^2 + y^2 = r^2</m> 这样的数学公式。
        </p>
        <theorem xml:id="thm-pythagorean">
          <title>勾股定理</title>
          <statement>
            <p>直角三角形中，<m>a^2 + b^2 = c^2</m>。</p>
          </statement>
          <proof>
            <p>证明过程...</p>
          </proof>
        </theorem>
      </section>
    </chapter>
  </book>
</pretext>

关键标记元素包括： - 文档结构: <book>, <article>, <chapter>, <section>, <subsection> - 数学内容: <m> (行内), <me> (行间公式), <men> (编号公式) - 证明结构: <theorem>, <proof>, <lemma>, <corollary> - 练习系统: <exercise>, <hint>, <answer>, <solution> - 交叉引用: <xref> 自动生成编号和链接 - 多媒体: <image>, <video>, <audio>, <interactive> - 程序代码: <cd>, <cline> 支持语法高亮

3. 交互式元素

PreTeXt 原生支持多种交互组件，无需额外配置：

4. 无障碍设计

无障碍访问是 PreTeXt 的核心设计原则（第 11 条指导原则）： - HTML 输出完全支持屏幕阅读器 - 数学公式使用 MathJax 渲染，可被辅助技术读取 - 文档结构语义化，导航清晰 - 盲文输出是原生支持的格式

三、安装配置

环境要求

安装方式

# 安装 PreTeXt CLI（当前版本 2.37.2）
python -m pip install --user pretext

# 验证安装
pretext --version

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

# 查看帮助
pretext --help

升级

# 方法1: pip 升级
python -m pip install --user --upgrade pretext

# 方法2: 使用内置升级命令
pretext upgrade

四、架构设计

整体架构

┌──────────────────────────────────────────────────────────────┐
│                      PreTeXt 系统架构                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐     ┌─────────────┐     ┌──────────────┐  │
│  │   Author     │     │   RELAX-NG  │     │    XSLT      │  │
│  │   XML 源文件 │────→│   Schema    │     │   转换引擎   │  │
│  │   (.ptx)    │     │   (验证器)   │     │              │  │
│  └─────────────┘     └─────────────┘     └──────┬───────┘  │
│                                                  │           │
│                              ┌───────────────────┼───────┐  │
│                              │                   │       │  │
│                              ▼                   ▼       ▼  │
│                        ┌─────────┐         ┌────────┐ ┌──┐ │
│                        │  HTML   │         │  PDF   │ │..│ │
│                        │  输出   │         │  输出  │ │  │ │
│                        └────┬────┘         └────────┘ └──┘ │
│                             │                               │
│                    ┌────────┼────────┐                      │
│                    ▼        ▼        ▼                      │
│              ┌────────┐┌────────┐┌────────┐                │
│              │ MathJax││  CSS   ││  JS    │                │
│              │ 数学渲染││ 样式表 ││交互组件│                │
│              └────────┘└────────┘└────────┘                │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                  PreTeXt CLI (Python)                  │ │
│  │     项目管理 │ 构建命令 │ 资产生成 │ 部署支持          │ │
│  └────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

核心模块

PreTeXt 采用双组件架构：

1. RELAX-NG Schema（模式定义）

位于 schema/ 目录，是 PreTeXt 的心脏。定义了所有合法的 XML 元素和属性，确保文档结构正确。

2. XSLT 转换引擎（格式转换）

位于 xsl/ 目录，占代码库 75.6%。负责将 XML 源文件转换为各种输出格式： - pretext-html.xsl → HTML 输出 - pretext-latex.xsl → LaTeX/PDF 输出 - pretext-epub.xsl → EPUB 输出 - 其他格式转换表

3. PreTeXt CLI（命令行工具）

独立的 Python 包（v2.37.2），提供项目管理、构建、生成等功能。通过 pip install pretext 安装。

CLI 内部结构: - pretext/cli.py — Click 框架的 CLI 入口 - pretext/project.py — 项目模型（基于 pydantic-xml 解析 project.ptx） - pretext/constants.py — 格式、资源、常量定义 - pretext/core/ — 预取的核心 XSLT 引擎副本 - pretext/server.py — 本地 HTTP 预览服务器 - pretext/plastex.py — LaTeX → PreTeXt 转换（实验性）

核心依赖: lxml, requests, GitPython, click, PyPDF2, pyMuPDF, playwright, pydantic-xml, qrcode, plastex, jinja2

4. 前端资源

• css/ - HTML 输出的样式表
• js/ - JavaScript 交互组件
• scss/ - SCSS 源文件

数据流（构建管线）

1. 解析 project.ptx 配置
       │
       ▼
2. （可选）生成资源（图片、交互元素等）
       │
       ▼
3. Schema 验证 XML 合法性
       │
       ▼
4. XSLT 转换为目标格式
       │
       ├→ HTML: MathJax 渲染公式 + CSS 样式 + JS 交互
       ├→ PDF:  LaTeX 中间文件 → XeLaTeX 编译
       ├→ EPUB: EPUB 容器打包
       └→ 其他格式...
       │
       ▼
5. 输出到配置的目录
       │
       ▼
6. （可选）本地预览服务 或 部署到 GitHub Pages

资产生成（Asset Generation）

PreTeXt 自动从 XML 源文件中生成多种类型的资源：

五、使用场景

适用场景

不适用场景

• 需要 WYSIWYG 编辑的场景（PreTeXt 是纯标记语言）
• 非学术性文档（小说、博客等不适合）
• 快速原型/草稿（XML 标记较重）
• 对排版有极致精确控制需求的场景（应使用 LaTeX）

典型案例

根据 PreTeXt 官方目录（pretextbook.org/catalog），已有 80 个项目使用 PreTeXt：

许可证分布: 46 CC（知识共享）、24 GFDL（GNU 自由文档）、10 All Rights Reserved

知名教材: - Active Calculus —广泛使用的微积分教材 - Understanding Linear Algebra — 线性代数教材 - Abstract Algebra: Theory and Applications — 抽象代数经典 - Mathematical Reasoning: Writing and Proof — 数学推理 - ORCCA — Open Resources for Community College Algebra

六、最佳实践

推荐做法

1. 使用版本控制: 将 .ptx 文件纳入 Git 管理
2. 善用 CLI 工具: 使用 pretext 命令管理项目，不要手动运行 XSLT
3. 遵循 Schema: 用支持 XML 的编辑器（VS Code + 扩展）获得自动补全
4. 渐进式编写: 先搭好文档结构，再填充内容
5. 利用交互元素: 对于数学教材，Sage Cell 和 WeBWorK 能极大提升教学效果
6. 定期构建检查: 每完成一个章节就构建一次，及早发现结构问题

避坑指南

1. 不要手动修改生成文件: HTML/PDF 是自动生成的，修改后会被覆盖
2. 注意 XML 语法: XML 比 LaTeX 更严格，标签必须闭合，大小写敏感
3. 公式用 LaTeX 语法: 在 <m> 和 <me> 中使用 LaTeX 数学语法，不要用 Unicode 字符
4. 不要过度嵌套: PreTeXt 有明确的文档结构层次，不要随意嵌套
5. 图片资源管理: 使用 pretext generate 管理图片资源，不要手动复制

七、对比分析

PreTeXt vs LaTeX

PreTeXt vs AsciiDoc

PreTeXt vs Markdown + MathJax

PreTeXt vs Bookdown / Quarto

选型建议

• 选择 PreTeXt: 编写数学/STEM 教材，需要多格式输出，关注无障碍
• 选择 LaTeX: 写研究论文，需要精确排版控制，已有 LaTeX 经验
• 选择 AsciiDoc: 写技术文档、手册，不需要复杂数学
• 选择 Markdown: 简单文档、博客，快速上手优先
• 选择 Bookdown/Quarto: 数据科学内容，需要代码执行（R/Python/Julia），重视可重复研究

八、总结

优势

1. 单源多格式: 一次编写，多种输出，极大地降低了多格式出版的成本
2. 学术语义: 标记语言直接表达学术概念（定理、证明、练习），不是格式指令
3. 无障碍优先: 从设计之初就是核心原则，不是事后补充
4. 交互式教学: 原生集成 Sage、WeBWorK 等教学工具，在线教育体验优秀
5. 开放生态: GPL 协议，80+ 实际项目，活跃的社区
6. 数学排版: 继承 LaTeX 的数学排版优势，同时获得现代 Web 能力

劣势

1. 学习曲线: XML 语法 + PreTeXt 词汇表，对 LaTeX 用户需要适应
2. XML 冗长: 相比 Markdown/AsciiDoc，标记较为冗长
3. 生态规模: 相比 LaTeX 40 年的积累，PreTeXt 生态仍在成长
4. 工具链依赖: PDF 输出需要 TeXLive，完整功能依赖较多外部工具
5. 编辑器支持: 不如 LaTeX 那样有广泛的编辑器支持
6. 社区规模: 334 Stars，74 贡献者，相比主流项目较小

最终建议

PreTeXt 是一个非常专注和专业的工具——它不试图成为通用文档系统，而是精确地服务于学术出版（尤其是数学教育）这个细分领域。在这个领域内，它是目前最优秀的解决方案之一：

• 推荐使用: 正在编写数学/STEM 教材、需要多格式输出、关注 OER 和无障碍的教育工作者
• 谨慎考虑: 非 STEM 文档、已有大量 LaTeX 积累的团队、需要快速上手的场景
• 值得关注: 即使当前不使用，PreTeXt 代表的"语义标记 + 多格式发布"理念值得所有技术作者学习

参考资料

• GitHub 仓库: https://github.com/PreTeXtBook/pretext
• 官方网站: https://pretextbook.org
• PreTeXt CLI: https://github.com/PreTeXtBook/pretext-cli
• VS Code 扩展: https://marketplace.visualstudio.com/items?itemName=pretext-tools.pretext-tools
• 项目目录: https://pretextbook.org/catalog.html
• 文档指南: https://pretextbook.org/doc.html
• Runestone 交互平台: https://runestone.academy