PreTeXtual: 用于PreTeXt的Sublime Text包

PreTeXtual是一个为使用PreTeXt（以前称为MathBook XML）的作者设计的Sublime Text 3包。其中一部分，特别是Vagrant构建系统，是实验性的，可能表现不佳。

该包受到出色的LaTeXTools包的启发，我多年来一直非常喜欢这个包。我非常自由地从LaTeXTools代码库中借用代码来实现我认为对MBX作者最有用的功能。请告诉我您发现的任何错误或您希望包含的任何功能。

截至版本0.5.0，不再支持Sublime Text 2。

• 安装
• 自动构建系统的额外设置
  • 继续之前请阅读
  • 启用VT-X虚拟化
  • 安装其它必需的软件
• 自动构建系统的概览
  • 初始化您的设置
  • 安装Vagrant虚拟机镜像
  • 激活Vagrant虚拟机镜像
  • 编译到HTML或PDF
  • 当编译失败时
  • 构建图像
  • 添加新的项目
  • 保持PreTeXt更新
  • 保持Vagrant虚拟机镜像更新
  • 手动编辑设置
    • 可用的设置
  • 故障排除
  • 未来的计划
  • 结论
• 快捷键
• 用法
• 已知问题

安装

注意：我们假设您熟悉通过命令面板运行Sublime Text命令。要打开面板，请按Ctrl+p（在OS X上为Cmd+p）。然后开始键入您想要过滤结果列表的命令名称。

建议通过Package Control安装PreTeXtual。如果您尚未安装Package Control，应首先进行安装（然后重启Sublime Text）。

在安装Package Control后，通过命令面板中的安装包命令搜索PreTeXtual包，并从快速面板中选择安装。这种安装方法允许Package Control自动更新您的安装并显示相应的发行说明。

您也可以通过git安装PreTeXtual。切换到您的Package文件夹中。要找到Package文件夹，请从首选项菜单中选择浏览包（从Mac OS X上的Sublime Text 3菜单中）。确保您在Package文件夹中，而不是Packages/User文件夹中。

然后，运行

git clone https://github.com/daverosoff/PreTeXtual.git

并重新启动Sublime Text（可能不需要）。

自动构建系统的额外设置

PreTeXtual现在附带可以处理您的PreTeXt源（生成HTML或LaTeX）并构建latex-image图像为所有图像格式的构建系统。结果是可供浏览器预览（HTML）或编译为PDF（LaTeX）的输出。所有这些都可以通过命令面板完成，如果您仔细按照以下说明操作。

继续之前请阅读

构建系统也针对入门用户，他们可能希望尽快开始而不用太过费心于配置或学习太多。所以目前这里没有描述任何一个可能的配置。PreTeXtual可以比这里描述的更灵活地完成事情，但为了简单起见，这里省略了详细信息。

构建系统仅面向Windows用户，因为与Linux或Mac OS相比，在Windows上安装PreTeXt要困难得多且繁琐。截至本版本，它仅在Windows 10上成功使用过。欢迎Windows 7用户尝试按照说明操作，但Windows 7似乎在安装当前版本的Vagrant时遇到一些困难。以下将详细说明。未来对Windows 7的支持将会得到更热烈的期望。

如果您的Windows 7是32位的，您很可能无法使用这个版本PreTeXtual的构建系统。如果您需要32位支持，请打开一个问题。如果在需求足够时，可以创建兼容的Vagrant箱。（但是您仍然需要使用Vagrant，正如上面所述，它可能不会总是与Windows 7和谐相处。）

其他操作系统的用户在未手动编辑一些包资源的情况下，找不到这个版本中的构建系统是有用的。欢迎使用有关如何完成此操作的问题在此打开问题。未来版本将支持不使用Vagrant使用构建系统，这是任何可能想要为了方便使用构建系统的Mac OS或Linux用户的首选。使用自定义样式表（“薄xsl”）的用户也将受益。

在继续安装过程中，访问浏览器中的这个README会很好，这样您可以在Sublime Text和其他程序中做事情时跟进。

在开始安装说明之前的一个额外说明：一旦您的项目成熟，您很可能会超过当前形式下的构建系统。目前的作者建议使用虚拟机来继续您的PreTeXt工作，但在pretext-support Google群组上有几种不同的解决方案，都可以讨论。

启用VT-X虚拟化

这是最难的一步，遗憾的是对于当前版本的PreTeXtual而言却是必要的。如果东西没按预期工作，您随时可以跳过它，稍后再回来。

严格遵循以下链接中的说明！这样做可能会真正搞乱您的系统。在您遇到真正困扰或感到害怕时，您始终可以使用“退出不保存”选项。

Windows用户需要按照以下说明进行操作（参考这里找到的说明中的第4步）。

1. 开机并打开BIOS（按照第1步操作）。通常可以通过按下删除键、F1键或Alt和F4键来打开，具体取决于您的系统。可能需要多次尝试。我通常第一次并不能成功。
2. 打开“处理器”子菜单。处理器设置菜单可能隐藏在“芯片组”、“高级CPU配置”或“南桥”菜单中。
3. 根据处理器品牌启用“Intel虚拟化技术”（也称为“Intel VT”）或“AMD-V”。虚拟化扩展可能被标记为“虚拟化扩展”、“Vanderpool”或其他名称，具体取决于原始设备和系统BIOS。
4. 如果可用，启用“Intel VTd”或“AMD IOMMU”。
5. 选择“保存并退出”。

安装其它必需的软件

请注意，从现在起整个安装过程均在https://mathbook.pugetsound.edu/doc/上的视频中进行了记录。

目前，构建系统需要使用其他两个应用程序：Virtualbox和Vagrant。将它们安装在您的计算机上。在需要做出决定时，随时接受默认设置。如果不选择默认值，将破坏PreTeXtual构建系统。

1. 在Sublime Text中，使用Package Control安装SideBarEnhancements包和Vagrant包。
2. 下载Virtualbox
3. 下载Vagrant

自动构建系统的概览

初始化您的设置

目前，PreTeXtual构建系统都使用Vagrant虚拟机来执行PTX文档生成过程的XSL处理和图像构建步骤。如果您不想使用Vagrant，那么这个版本的PreTeXtual构建系统将无法为您工作。

您需要以特定方式组织项目，以便PreTeXtual能够看到和管理它们。特别是，您必须创建一个名为C:\PreTeXt（它必须位于C:驱动器上）的文件夹。这个文件夹应该包含一个子文件夹来让您工作的每个写作项目。在进行下一步之前请设置好。

注意：剩余的步骤将花费相当长的时间，根据您的选择，可能长达两小时。

按照上述方式设置好文件夹后，打开Sublime Text窗口，并运行命令（从命令面板）“初始化PreTeXt Vagrant”。然后按照提示操作。每个位于C:\PreTeXt下一层的文件夹都将被识别为一个写作项目。这些项目将被添加到PreTeXtual简单的项目管理系统中。您可以在用户设置中为每个项目存储一些选项。特别是，您需要输入每个的根文件路径。PreTeXt项目的根文件是包含<mathbook> XML元素的文件。您需要使用双反斜杠\\而不是单反斜杠\来输入路径。一个典型的路径可能如下所示

C:\\PreTeXt\\AATA\\src\\aata.xml

警告。尽管Windows通常不太关心路径中的大小写，但PreTeXtual不同。您必须以正确的首字母大小写输入路径名称中的所有字母，否则事情可能不会按预期工作。

您可以稍后通过直接编辑设置文件来输入路径。

安装Vagrant虚拟机镜像

注意：即使您已经以其他方式安装了PreTeXt，这一步也是必需的。

根据上述说明完成了项目导入后，您将看到一个带有多个选项的菜单。大多数人将想要“PreTeXt”或“PreTeXt-lite”。如果您需要Sage或Asymptote，请选择“PreTeXt”。如果您需要完整的LaTeX安装但不需要Sage或Asymptote，请选择“PreTeXt-lite”。如果您只需要处理HTML，您可以尝试“PreTeXt-barebones”（不推荐）。最后一个选项“PreTeXt-no-images”仅用于测试。

完整的“PreTeXt”选项可能需要45到60分钟的下载和安装时间，在慢速连接下可能需要更长的时间。其他操作所需时间更短，但即使是裸骨选项也可能需要10到15分钟。遗憾的是，目前PreTeXtual无法提供任何进度条或反馈。Sublime Text窗口甚至可能会似乎挂起，标题栏中出现“(没有响应)”信息。请不要担心！

激活Vagrant虚拟机镜像

注意。每次重启后，首次开始运行PreTeXt项目时，请执行此步骤。

在新打开的Sublime Text窗口中，使用“打开文件夹”命令打开您的整个C:\PreTeXt文件夹。您的所有项目都应在侧边栏中显示。然后使用命令调色板运行命令vagrant up。在状态栏底部消失“正在运行Vagrant……”文本之前继续（可能需要一分钟左右）。或者，您也可以从菜单中选择“查看/显示控制台”，以检查此命令的进度，这将激活您已安装PreTeXt的虚拟机。

编译到HTML或PDF

现在开始有趣的部分了。在现有的写作项目中，打开任意的PreTeXt文件。请确保“PreTeXt”显示在屏幕的右上角。一些命令只能在PreTeXt模式下使用（由PreTeXtual包提供）。如果您的源文件以.xml结尾，而不是以.ptx或.mbx结尾，您需要做一些配置（使用PreTeXtual: Set PreTeXt File Exts命令，见下文）。

打开PreTeXt文件后，通过按Ctrl+Shift+B键调出构建菜单。从菜单中选择“将PreTeXt转换为HTML”，当出现处理通知时，点击确定。如果您正在观察侧边栏，将看到在您的src文件夹旁边出现了output文件夹。在侧边栏中展开它，您可以观察生成的HTML文件。构建完成后，Sublime Text应会通过对话框提醒您。

注意。对话框并不大，也不是强制性的，但它们会阻止Sublime Text继续运行。如果您认为您的编辑器崩溃了，请首先检查是否有对话框可能被另一个窗口遮挡。

打开output\html文件夹，在其中一个HTML文件上单击右键。选择“在浏览器中打开”。惊叹于这个过程的相对简单性。

要转换为LaTeX，您可以从菜单中选择“将PreTeXt转换为LaTeX”。为了转换为PDF，我建议您使用出色的LaTeXtools包，PreTeXtual应对此感激不尽。PreTeXtual的未来版本可能支持在Sublime Text中直接编译，而不使用LaTeXtools。要执行此步骤，需要在您的计算机上安装LaTeX，但此处没有对其进行文档化。

当编译失败时

PreTeXtual目前还不够智能，无法意识到出现问题时。您会注意到输出并未出现，或没有更改；一个非常快速的“构建完成”对话框通常也表明有错误。为了查看PreTeXt在处理您的源文件时生成的消息，请使用Sublime Text控制台：在编译前后从视图菜单中选择显示控制台。

构建图像

注意。此部分构建系统可能仍然有些不稳定。此外，如果您在上述选择中选择了pretext-barebones或pretext-no-images，它将无法正常工作。对较长的文档来说，它可能会非常耗时。最后，一些Asymptote 3D图像尚不支持，并可能引发停止图像构建过程的异常。

注意。尚不支持包含非源生成的图像。如果您急需此功能，请打开一个问题。

构建镜像应该像处理成HTML或LaTeX一样简单。使用 Ctrl+Shift+B 菜单选择“构建镜像”命令（如果您有一个大型项目，这可能需要一段时间）。当图像生成时关闭出现的对话框，如果Sublime Text似乎挂起或无响应，请不要惊慌！只需等待！在“PreTeXtual构建例程结束”的最终消息之后，您可以在浏览器中刷新您的HTML输出以检查图像是否出现。它们现在也将可用于LaTeX编译。

这完成了对构建系统的巡览。在关闭系统之前，在命令提示符中运行 vagrant suspend。这将以非破坏性方式暂停虚拟机。如果没有使用 vagrant suspend 关闭系统，Windows可能会抱怨阻止您关闭计算机——实际上，它可能仍然会这么做，但强制关闭不会给虚拟机带来任何问题（如果您需要，可以简单地将其删除并创建一个新的）。

注意。在运行 vagrant suspend 几分钟后关闭，您应该在关闭时不会收到来自Windows的错误。

添加新的项目

当前，没有单独的命令来添加项目。最简单的方法是手动编辑您的设置文件，如下所述。

保持PreTeXt更新

PreTeXt正在积极开发，频繁更改。为了保持您的安装最新，您应每隔几周更新一次。这可能需要您对源代码进行一些更改。

从命令面板运行 PreTeXtual: 更新PreTeXt 命令。如果不可用，请尝试保存一个空文件，并以 .ptx 扩展名保存，然后在此文件中再次尝试。您可能会看到一个新窗口打开，其中包含一些与 git 相关的象形文字。只需等待它关闭即可。一切完成！

保持Vagrant虚拟机镜像更新

尽管可能永远不需要，但保留您的Vagrant箱子更新（新版本在每个日历月的第一个星期推出）可能是一个好主意。更新它的最简单方式是从命令面板运行 Vagrant: Destroy && Up 命令。您还可以从任何命令提示符中运行 vagrant box update 命令（请确保先切换到 C:\PreTeXt 文件夹）。

手动编辑设置

所有PreTeXtual信息都存储在用户设置文件中的 pretext_projects 设置中。要编辑它，从Sublime Text 3菜单选择“首选项/设置”。将出现一个带有两个窗格的新Sublime Text窗口。左侧仅用于参考，不应编辑。在右侧，您应该能够找到 pretext_projects 设置。您可以更改值并以您希望的任何方式保存文件。

可用的设置

1. name：每个项目都有一个内部ID，称为name。默认情况下，它与项目所在目录的名称相同。
2. path：每个项目都知道其目录的路径。您需要转义反斜杠（输入每个反斜杠作为 \\）。
3. root_file：每个项目都知道其根文件的绝对路径。
4. xinclude：（默认：True）如果您出于某种原因想要禁用xinclude行为，将该值设置为false（注意：不要加引号）。

5. stringparam：如果您需要一些自定义字符串参数，请在此处作为键值对的字典/散列输入它们

   "stringparam": {
     "html.css.file": "https://www.my.site/path/to/my.css",
     "latex.font.size": "20pt"
   }
   

6. （仅限专家）还有一些其他设置，PreTeXt可以识别但尚未在此处文档化的设置。检查文件beta_process.py了解更多详情。

故障排除

如之前所述，该系统仍然是实验性的，尽管已经进行了一定程度的测试。如果遇到问题或者事情没有按预期工作，可能需要寻求一些帮助，但首先应该尝试使用Sublime Text控制台查看发生了什么。通过从Sublime Text菜单中选择视图/显示控制台来启用控制台。将光标放入控制台并按下Esc或使用视图/隐藏控制台可以关闭控制台。控制台会实时更新Sublime Text正在做什么。特别是，如果PreTeXtual抛出了作者未预料到的错误，你将能在控制台看到错误信息。这些信息将有助于调试你的情况。

您可以通过将光标放入控制台并按Esc键，或者通过使用视图/隐藏控制台来关闭控制台。

未来的计划

我们希望支持为视频和交互式内容生成缩略图/静态图像。也许还可以提供一些支持使用WeBWorK/MyOpenMath问题编译文档的功能，尽管可能会出现这种情况：这些功能的-heavy食用油意味着您的项目“超出了”Vagrant构建系统。在这种情况下，您最好采用另一种使用PreTeXt的方法。

Vagrant构建系统的文档以及尤其是当项目足够成熟/先进时的“毕业”过程仍然不够完善。我们选择将此文档与当前文档以及视频演示一同发布，以加快启动过程。作者正在积极编写文档并欢迎您的贡献。

结论

这是关于构建系统的文档章节的结束。感谢您阅读，并将任何问题发送到pretext-support Google群组

https://groups.google.com/forum/#!forum/pretext-support

或在此处创建问题：

https://github.com/daverosoff/PreTeXtual/issues

本文件的其余部分涉及PreTeXtual包的其他功能。

快捷键

PreTeXtual受到LaTeXTools的启发，就像该包一样使用Ctrl+l前缀执行许多命令。默认情况下，将“扩展选择到行”命令绑定到Ctrl+l。PreTeXtual将此命令重新绑定到Ctrl+l, Ctrl+l。请注意，这是一个由两个单独按键组合组成的快捷键。大多数PreTeXtual快捷键都是这种情况。

用法

您可以通过启用PreTeXt语法来激活包功能。语法定义会在查找.ptx或旧的.mbx文件扩展名时搜索。如果您的PreTeXt文件以.xml结尾（或别的什么），您有以下几种选择。

1. 使用首选项菜单或命令调色板运行命令设置PreTeXt文件扩展名，并使用输入面板将.xml或其他您选择的扩展名添加到以逗号分隔的列表中。Sublime将首先查找项目设置文件，然后在没有找到时更新用户首选项。如果您有多个PreTeXt项目，或者如果您编辑的XML除了PreTeXt之外，最好开始使用Sublime Text项目，这样就可以为 项目特定的设置。

2. 您可以通过命令调色板手动启用语法。要手动启用，请打开一个PreTeXt文件，并按Ctrl+Shift+P（在OS X上是Cmd+Shift+P），输入ptx。从选项列表中选择设置语法：PreTeXt。

如果您的状态栏可见（命令调色板：切换状态栏），应看到下角的文本PreTeXt。请原谅这张仍然显示旧名称PreTeXt的图片。

以下是一个（非详尽）的功能列表。

1. 新功能 0.6.0：包含一个与Vagrant虚拟机管理软件的广泛接口，使Sublime Text 3更像是一个PreTeXt的API。有关更多信息，请参阅README的相关部分。

2. 如果在您的PreTeXt文件中有些细分（有xml:id），按Ctrl+R（在OS X上是Cmd+R）以运行转到符号命令。您将看到显示所有可用部分的面板。选择一个即可跳转到活动视图中。此工具不支持没有xml:id属性的细分。

1. 将整个源代码文件夹作为一个项目打开，然后在项目中使用“转到符号”功能（Ctrl+Shift+R/Cmd+Shift+R）查看项目中所有PreTeXt文件的所有xml:id（必须使用.mbx或.ptx扩展名，才能成功进行索引）。

2. 尝试输入<xref ref="（交叉引用的开始）。Sublime Text应该会显示一个面板，其中包含所有xml:id值及其对应的元素。选择一个，将其插入到插入符处，并关闭标签。或者，输入ref并按Tab激活片段。然后按Ctrl+L, X或Ctrl+L, Ctrl+Space以显示完成菜单。有几种ref片段的变体，分别是refa、refp和refpa。

1. 如果您设置了一个PreTeXt根文件，那么如上所述的ref完成将会递归地通过所有xi:includes从指定的根文件开始搜索xml:id。从“首选项”菜单或命令面板中运行“设置PreTeXt根文件”命令。请确保使用设置的绝对路径名称，以及斜杠（是的，Windows也适用）。

2. 输入chp、sec、ssec或sssec并按Tab激活细分片段。提供一个空的title元素，并将光标定位在其中。您在标题中输入时，细分对应的xml:id字段会用相似文本自动填充，以镜像输入的标题文本。

已知问题

• build系统还有一些边缘情况和错误需要在下个版本中修复。
• 根文件检测不明确。有一个系统级的PreTeXt根文件用于生成符号列表，但它被构建系统忽略。他们使用完全不同的设置方案来查找项目的根文件。文档并未对此进行充分说明。
• ref片段没有弹出快速面板。它应该这样做吗？
• 一些片段可以改进。
• 符号查找可以改进。