TeXworks

「写出 XeTeX 的人，接着写了一个几乎没有功能的编辑器。」TeXworks 就是从这里开始的。把 Unicode 和系统字体带进 TeX 之后，Jonathan Kew 转向了另一个问题：刚开始学 LaTeX 的人会在多少个地方迷路。他给 TUG 演讲起的标题是「TeXworks: lowering the barrier to entry」——降低入门门槛。所以 TeXworks 没有项目管理，没有构建脚本，侧边也没有文件树。一个窗口，一个按钮，只需要选一样东西：引擎。本页要讲的是：究竟哪些发行版真的捆绑了 TeXworks（答案取决于操作系统，而不少介绍都写错了）、如何改写它唯一的设置界面「排版工具」，以及 % !TeX root 这一行注释怎样顶替了项目管理。

TeXworks 出自 XeTeX 作者之手

TeXworks 的作者是 Jonathan Kew，也就是写出 XeTeX 的人。他的样板是 Richard Koch 的 TeXShop，长期以来 Mac 上的首选。Kew 认为 TeXShop 那种朴素的布局——一个窗口里源码与 PDF 并排——对初学者很受用，于是 TeXworks 把这种手感带到了 Windows 和 Linux 上。当时 Windows 上的集成环境，对第一次接触 LaTeX 的人来说按钮实在太多。Kew 的回答不是加功能，而是减少需要做的决定。

这种「少」是很具体的。打开 TeXworks，你看到的只有一块编辑区、工具栏上的引擎下拉框和旁边的绿色三角按钮，以及另一块显示 PDF 的面板。没有文件树，没有章节大纲，也没有构建配置文件。界面用 Qt 写成，在 Windows、macOS 和 Linux 上外观一致；许可证是 GPL v2，默认编码是 UTF-8。随身的工具也极简——命令补全、输入辅助、拼写检查。若这还不够，可以启用可选的 Lua 与 Python 脚本插件，加进自己的处理（它们是构建期选项，Lua 默认开启，Python 默认关闭）。版本号也值得一提：距首次发布十几年之后，它依然停在 0.6 系列，每年二月前后发一次小更新。一路加功能奔向 1.0，本来就不在计划之内。

哪些发行版捆绑了 TeXworks

在 Windows 上，你几乎肯定已经有它了：MiKTeX 的安装程序和 TeX Live 的 Windows 安装程序都会装上 TeXworks。而在 macOS 和 Linux 上，它不会随发行版一起来。 TeX Live 只提供 Windows 可执行文件，这不是猜测——TeX Live 自己的软件包账簿 texlive.tlpdb 里就是这么写的。texworks 包的说明是「TeX Live includes executables and support files only for Windows.」（TeX Live 只收录 Windows 的可执行文件和支持文件），而包住它的 collection-texworks，标题就是「TL includes only the Windows binary」。

# from texlive.tlpdb, the package database TeX Live installs from
name texworks
category TLCore
shortdesc friendly cross-platform front end
longdesc TeX Live includes executables and support files only for Windows.
postaction shortcut type=menu name="TeXworks editor" \
           cmd=TEXDIR/bin/windows/texworks.exe

混乱正是从这里开始的。TeX Live 里还附了一份简短说明 texmf-dist/doc/texworks/README，上面写着 TeX Live 收录 Windows 二进制、MacTeX 收录 macOS 二进制。可这份 README 写于 2009 年，而安装程序真正依据的是那本账簿。今天 MacTeX 提供的图形编辑器是 TeXShop，不是 TeXworks。在 Linux 上，TeXworks 与 TeX Live 本体完全分开，以发行版自己的 texworks 软件包形式提供。一句话：「TeXworks 随 TeX Live 一起来」这句话，只在 Windows 上成立。

排版下拉框与 Processing tools

TeXworks 关于「构建」的全部知识，都集中在工具栏左侧的一个下拉框里。选好引擎（pdfLaTeX、XeLaTeX、LuaLaTeX、ConTeXt 等），按旁边的绿色三角按钮或 Ctrl/Cmd-T，当前打开的文档就会被编译，PDF 预览随之出现。BibTeX、MakeIndex 这类辅助工具也早已登记好，所以一份普通文档不必打开任何设置就能走到 PDF。

这份清单可以自己改写。打开 Edit → Preferences → Typesetting 标签页，下半部分就是 Processing tools 列表，+ 添加，- 删除，Edit... 修改。一个工具只有四样东西：下拉框里显示的 Name、要启动的 Program、Arguments，以及 View PDF after running 复选框。这里最常见的翻车点在 Arguments：每行只写一个参数。它不是 shell 命令行，所以把 -interaction=nonstopmode %.tex 挤在一行里，整串会被当作单个参数传过去，引擎便会去找一个名字非常古怪的文件。

Arguments 里可以使用 TeXworks 的变量。最广为人知的是指向处理对象的 $fullname，但实际上一共有五个；能单独取出扩展名或目录，正是把经由 DVI 的流程和辅助工具写出来的关键。变量在工具启动前的一刻展开。

把 latexmk 登记成一个工具

TeXworks 缺的是一个决定「跑几遍」的脑子。交叉引用一直停在 ??、\tableofcontents 总慢一版——这些症状归根结底都是编译次数的问题，而 TeXworks 不会替你计数。于是惯常做法是把这个判断整个交给 latexmk，TeXworks 这边只保留一个调用它的工具。把 Program 设为 latexmk，Arguments 按下面每行一个填入，并勾上 View PDF after running。

-e
$pdflatex=q/pdflatex $synctexoption %O %S/
-pdf
$fullname

日文长期以来的定番路线是用 upLaTeX 排版，再用 dvipdfmx 生成 PDF。TeX Live 附带的 TeXworks 已内置了日文工具，但若要自己写一个，ptex2pdf 最省事，因为它把两段处理合成了一步。把 Program 设为 ptex2pdf，Arguments 如下（-l 选择 LaTeX 格式，-u 选择 upLaTeX，-ot 用于指定传给 TeX 的附加选项）。至于 latexmk 本身的细致配置，是另一页的主题，这里只讲怎么调用。

-l
-u
-ot
-kanji=utf8 -no-guess-input-enc $synctexoption
$fullname

把最常用的那个，设成 Typesetting 标签页顶部的默认排版引擎，此后新打开的文档都会用它处理。若某份文件需要别的引擎，下一节的魔法注释会覆盖这个默认值。

% !TeX root——顶替项目管理的那一行

一旦把文档按章拆成多个文件、再由父文件用 \input 或 \include 引入，TeXworks 没有「项目」这个容器就成了问题。在 chapter1.tex 打开的状态下排版，编译当然会失败，因为那个文件既没有 \documentclass 也没有 \begin{document}。换作别的编辑器，此时该建项目、登记主文档了；而 TeXworks 的回答是在文件开头写一行。

% !TeX root = main.tex

\chapter{Introduction}
The body of the chapter goes here.

在 TeX 看来，那不过是 % 之后的一句注释；但 TeXworks 会读取文件开头的若干行并据此改变行为。有了这一行，在编辑子文件时排版，TeXworks 就会转而编译父（根）文件。路径按相对于子文件的写法即可。妙处在于，这条信息写在文件里，而不是写在设置里：项目文件换台机器就会失效，而注释行会进入版本库，在合作者的机器上照样管用。这一写法源自 TeXShop，TeXworks 之外的编辑器也读同一行。

魔法注释还有别的。% !TeX program = ... 为该文档钉死所用引擎。要注意，这里填的不是可执行文件名，而是在 Preferences 里登记的工具 Name——不是 pdflatex，而是清单里显示的那个名字。旧写法 % !TeX TS-program = ... 含义相同。% !TeX encoding = ... 声明文件的字符编码，不过 TeXworks 默认就是 UTF-8，用 UTF-8 书写时通常用不上。把 % !TeX program 放在日文文档开头，即使忘了切换下拉框，跑的也是正确的引擎。

% !TeX program = upLaTeX (ptex2pdf)
% !TeX encoding = UTF-8
\documentclass{ujarticle}
\begin{document}
\input{chapter1}
\end{document}

TeXworks 与 TeXstudio 的区别，以及何时该换

差别不在功能多少，而在设计目标。TeXworks 优化的是「减少你会迷路的地方」，而 TeXstudio、Texmaker、Kile 优化的正相反：把你可能需要的一切都摆到手边。所以「TeXworks 功能少」是在描述它的设计，而不是在下评语；比较的正确坐标轴，是「眼下什么在耗掉你的时间」。当下面两条以上成立时，就该考虑换了。

• 文件越来越多，总在忘了写 % !TeX root 的子文件上绊倒。
• 开始使用文献数据库，花在另一个窗口里找 \cite 键名的时间越来越长。
• 构建已经不是跑一遍 pdfLaTeX 就够，Processing tools 列表被条目塞满了。
• 同一份稿子现在需要用不止一个引擎产出，比如 pdfLaTeX 和 LuaLaTeX 各来一份。

怎样读日志和中间文件

正因为屏幕上没有多余的东西，TeXworks 很适合用来养成读日志的习惯。排版之后的输出面板告诉你的不止是「有没有生成 PDF」：未解析的引用、找不到的宏包、加载失败的图片都会原样出现。像 ! Missing $ inserted 或 ! Undefined control sequence 这样的一行就是第一个错误，而紧随其下的行号才是真正的线索。TeXworks 的设计是让你去读，而不是替你停下，所以跳过这块面板等于丢掉它一半的价值。

• 引用一直是 ??，就用同一个工具再排版一次，让 .aux 更新（latexmk 工具会替你做这件事）。
• 只在大幅改动目录或参考文献之后才删掉 .aux、.toc 再重建。平时留着通常更快。
• 图片不出现时，把日志里的文件名和实际路径对照一遍。文件名里避免空格和非 ASCII 字符。
• Processing tools 挤满了，就把构建知识搬进 .latexmkrc，TeXworks 这边退回到只有一个 latexmk 工具。

SyncTeX 的设置（正向搜索与反向搜索）

TeXworks 内置了一个基于 Qt 与 Poppler 的 PDF 预览，因此不必另开外部阅读器，在同一个窗口里就能编辑与查看来回切换。正向搜索（从源码某处跳到 PDF 对应位置）是在源码上 Ctrl/Cmd-单击；反向搜索（从 PDF 回到源码对应行）是在预览上 Ctrl/Cmd-单击。不需要任何设置，因为自带工具的 Arguments 里本来就有 $synctexoption，正是它让引擎写出跳转所依赖的 .synctex.gz 对照表。如果自己写的工具同步失灵，先检查是不是漏了这个变量。SyncTeX 的内部机制由另一页专门讲述。