使用 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 的安装位置,TEXMFHOMEkpsewhich 命令的结果。

    如果你升级了 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.texexample.pdf, 这是使用 LaTeX 和 Sage 对该文件进行排版的预生成结果。 你也可以从 SageTeX 页面 获取这些文件。

SageTeX 与 TeXLive

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

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