使用 SageTeX - Sage 教程

Skip to content
Back to top
View this page
Edit this page

# 使用 SageTeX

SageTeX 包允许你将 Sage 计算结果嵌入到 LaTeX 文档中。 要使用它，需要先“安装”它（请参阅 让 TeX 识别 SageTeX）。

## 示例

以下是一个非常简短的 SageTeX 使用示例。 完整文档可以在 `SAGE_ROOT/venv/share/doc/sagetex` 中找到， 其中 `SAGE_ROOT` 是 Sage 安装目录。该目录包含文档和示例文件。 请参阅 `SAGE_ROOT/venv/share/texmf/tex/latex/sagetex` 以获取一些可能有用的 Python 脚本。

想要了解 SageTeX 的工作原理，请按照 SageTeX 的安装说明（在 让 TeX 识别 SageTeX 中）操作， 并将以下文本复制到一个名为 `st_example.tex` 的文件中：

警告

如果你在“实时”帮助中查看此内容，下面的文本会有几个未知控制序列的错误。 请使用静态版查看正确的文本。

    \documentclass{article}
    \usepackage{sagetex}

    \begin{document}

    Using Sage\TeX, one can use Sage to compute things and put them into
    your \LaTeX{} document. For example, there are
    $\sage{number_of_partitions(1269)}$ integer partitions of $1269$.
    You don't need to compute the number yourself, or even cut and paste
    it from somewhere.

    Here's some Sage code:

    \begin{sageblock}
        f(x) = exp(x) * sin(2*x)
    \end{sageblock}

    The second derivative of $f$ is

    \[
      \frac{\mathrm{d}^{2}}{\mathrm{d}x^{2}} \sage{f(x)} =
      \sage{diff(f, x, 2)(x)}.
    \]

    Here's a plot of $f$ from $-1$ to $1$:

    \sageplot{plot(f, -1, 1)}

    \end{document}

像往常一样在 `st_example.tex` 上运行 LaTeX。请注意 LaTeX 会有一些警告，其中包括：

    Package sagetex Warning: Graphics file
    sage-plots-for-st_example.tex/plot-0.eps on page 1 does not exist. Plot
    command is on input line 25.

    Package sagetex Warning: There were undefined Sage formulas and/or
    plots. Run Sage on st_example.sagetex.sage, and then run LaTeX on
    st_example.tex again.

请注意，除了 LaTeX 产生的常规文件集合外，还有一个名为 `st_example.sagetex.sage` 的文件。 这是在 `st_example.tex` 上运行 LaTeX 时生成的 Sage 脚本。 警告信息告诉你在 `st_example.sagetex.sage` 上运行 Sage，请听从建议并进行操作。 它会告诉你再次在 `st_example.tex` 上运行 LaTeX，但在此之前， 请注意新文件 `st_example.sagetex.sout` 已被创建。该文件包含 Sage 计算结果， 可供 LaTeX 插入到你的文本中。还创建了一个包含 EPS 文件的新目录。再次运行 LaTeX， 你会看到 Sage 计算和绘图的所有内容已包含在你的文档中。

上面使用的各种宏应该很容易理解。`sageblock` 环境按原样排版你的代码， 并在运行 Sage 时执行代码。当你执行 `\sage{foo}` 时， 插入到文档中的结果就是在 Sage 内部运行 `latex(foo)` 得到的结果。 绘图命令稍微复杂一些，但在最简单形式下，`\sageplot{foo}` 插入的是由 `foo.save('filename.eps')` 得到的图像。

一般来说，操作步骤是：

> - 在 .tex 文件上运行 LaTeX；

> - 在生成的 .sage 文件上运行 Sage；

> - 再次运行 LaTeX。

如果文档中没有更改任何 Sage 命令，则可以省略运行 Sage。

SageTeX 还有很多内容，由于 Sage 和 LaTeX 都是复杂且强大的工具， 建议阅读 SageTeX 的文档 `SAGE_ROOT/venv/share/doc/sagetex`。

## 让 TeX 识别 SageTeX

Sage 基本上是自包含的，但某些部分需要进行一些干预才能正常工作。SageTeX 就是其中之一。

SageTeX 包允许在 LaTeX 文档中嵌入来自 Sage 的计算和绘图。 Sage 中默认安装了 SageTeX，但要在 LaTeX 文档中使用 SageTeX，你需要先让 TeX 识别它。

关键在于 TeX 需要能够找到 sagetex.sty， 该文件位于 `SAGE_ROOT/venv/share/texmf/tex/latex/sagetex/`， 其中 `SAGE_ROOT` 是你构建或安装 Sage 的目录。如果 TeX 能找到 `sagetex.sty`， 那么 SageTeX 就可以工作。有几种方法可以实现这一点。

- 第一种方法，也是最简单的方法是将 `sagetex.sty` 复制到与 LaTeX 文档相同的目录中。 在排版文档时，总会搜索当前目录，因此这种方法始终有效。

  但这种方法有两个小问题：首先，会在计算机上产生很多不必要的 `sagetex.sty` 拷贝。 其次，更严重的问题是，如果升级 Sage 并获得新版本的 SageTeX， Python 代码和 SageTeX 的 LaTeX 代码可能不再匹配，从而导致错误。

- 第二种方法是使用 `TEXMFLOCAL` 环境变量。如果你使用的是 bash shell，可以这样做：

      $ export TEXMFLOCAL=SAGE_ROOT/venv/share/texmf
      $ mktexlsr       # update kpathsea ls-R databases

  其中 `SAGE_ROOT` 是 Sage 安装位置。 之后，TeX 和相关程序将找到 SageTeX 样式文件。如果你想使这个更改持续生效， 可以将上述第一行添加到 `.bashrc` 文件中。如果你使用的是不同的 shell， 可能需要调整以上命令从而让环境变量可被识别；请查阅所用 shell 的文档以了解如何操作。

  如果你移动了 Sage 的安装目录或在新目录中安装了新版本， 需要用新的 `SAGE_ROOT` 更新上述命令。

- 让 TeX 识别 `sagetex.sty` 的第三种（也是最佳的）方法， 是将该文件复制到主目录中的一个方便的位置。 大多数 TeX 发行版会自动搜索主目录中的 `texmf` 目录以寻找包。 要确切了解这个目录的位置，请在命令行种执行以下操作：

      $ kpsewhich -var-value=TEXMFHOME

  这将打印出一个目录，例如 `/home/drake/texmf` 或 `/Users/drake/Library/texmf`。 使用如下命令将 `SAGE_ROOT/venv/share/texmf/` 中的 `tex/` 目录复制到主目录的 `texmf` 目录：

      $ cp -R SAGE_ROOT/venv/share/texmf/tex TEXMFHOME

  其中 `SAGE_ROOT` 仍然是 Sage 的安装位置，`TEXMFHOME` 是 `kpsewhich` 命令的结果。

  如果你升级了 Sage 并发现 SageTeX 无法工作， 可以简单地重复上述步骤以确保 SageTeX 的 Sage 部分和 TeX 部分再次同步。

- 对于多用户系统上的安装，只需适当修改上述指令，将 `sagetex.sty` 复制到系统范围的 TeX 目录中。 最好的选择可能是使用以下结果，而不是 `TEXMFHOME` 目录：

      $ kpsewhich -var-value=TEXMFLOCAL

  这很可能会产生类似于 `/usr/local/share/texmf` 的结果。 按照上述方式将 `tex` 目录复制到 `TEXMFLOCAL` 目录中。 现在需要通过运行以下命令更新 TeX 的包数据库：

      $ texhash TEXMFLOCAL

  以 root 身份，适当替换 `TEXMFLOCAL`。 现在系统中所有用户都可以访问 LaTeX 包，如果他们也能运行 Sage，他们就可以使用 SageTeX。

警告

确保 LaTeX 在排版文档时使用的 `sagetex.sty` 文件与 SageTeX 使用的版本匹配， 这一点至关重要。如果你升级了 Sage，应该删除所有旧版本的 `sagetex.sty`。

由于此问题，我们建议将 SageTeX 文件复制到主目录的 texmf 目录中（上述第 3 种方法）。 这样，升级 Sage 时，仅需做一件事（复制目录）即可确保 SageTeX 正常工作。

## SageTeX 文档

虽然这不严格属于安装的一部分，但值得在此提及的是， SageTeX 的文档维护在 `SAGE_ROOT/venv/share/doc/sagetex/sagetex.pdf`。 同一目录中还有一个示例文件 -- 请参见 `example.tex` 和 `example.pdf`， 这是使用 LaTeX 和 Sage 对该文件进行排版的预生成结果。 你也可以从 SageTeX 页面 获取这些文件。

## SageTeX 与 TeXLive

一个潜在的令人困惑的问题是流行的 TeX 发行版 TeXLive 包含 SageTeX。 虽然看起来很方便，但对于 SageTeX 而言，确保 Sage 部分和 LaTeX 部分同步是非常重要的 -- 在这种情况下， 这就成为了一个问题，因为由操作系统发行版或软件包管理器提供的 TeXLive 可能与官方 TeXLive 分发版本不同步， 而后者也可能与当前的 SageTeX 版本不同步。

因此，强烈建议 你始终按照上面的说明，从 Sage 安装 SageTeX 的 LaTeX 部分。 上述说明将确保 SageTeX 的两个部分兼容并正常工作。