.. _sec-sagetex:
************
使用 SageTeX
************
SageTeX 包允许你将 Sage 计算结果嵌入到 LaTeX 文档中。
要使用它，需要先“安装”它（请参阅 :ref:`sec-sagetex_install`）。
示例
----
以下是一个非常简短的 SageTeX 使用示例。
完整文档可以在 :file:`SAGE_ROOT/venv/share/doc/sagetex` 中找到，
其中 ``SAGE_ROOT`` 是 Sage 安装目录。该目录包含文档和示例文件。
请参阅 :file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex` 以获取一些可能有用的 Python 脚本。
想要了解 SageTeX 的工作原理，请按照 SageTeX 的安装说明（在 :ref:`sec-sagetex_install` 中）操作，
并将以下文本复制到一个名为 ``st_example.tex`` 的文件中：
.. warning::
如果你在“实时”帮助中查看此内容，下面的文本会有几个未知控制序列的错误。
请使用静态版查看正确的文本。
.. code-block:: latex
\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 会有一些警告，其中包括：
.. CODE-BLOCK:: text
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 的文档 :file:`SAGE_ROOT/venv/share/doc/sagetex`。
.. _sec-sagetex_install:
让 TeX 识别 SageTeX
-------------------
Sage 基本上是自包含的，但某些部分需要进行一些干预才能正常工作。SageTeX 就是其中之一。
SageTeX 包允许在 LaTeX 文档中嵌入来自 Sage 的计算和绘图。
Sage 中默认安装了 SageTeX，但要在 LaTeX 文档中使用 SageTeX，你需要先让 TeX 识别它。
关键在于 TeX 需要能够找到 sagetex.sty，
该文件位于 :file:`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，可以这样做：
.. code-block:: console
$ 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`` 目录以寻找包。
要确切了解这个目录的位置，请在命令行种执行以下操作：
.. code-block:: console
$ kpsewhich -var-value=TEXMFHOME
这将打印出一个目录，例如 ``/home/drake/texmf`` 或 ``/Users/drake/Library/texmf``。
使用如下命令将 :file:`SAGE_ROOT/venv/share/texmf/` 中的 ``tex/`` 目录复制到主目录的 ``texmf`` 目录：
.. code-block:: console
$ cp -R SAGE_ROOT/venv/share/texmf/tex TEXMFHOME
其中 ``SAGE_ROOT`` 仍然是 Sage 的安装位置，``TEXMFHOME`` 是 ``kpsewhich`` 命令的结果。
如果你升级了 Sage 并发现 SageTeX 无法工作，
可以简单地重复上述步骤以确保 SageTeX 的 Sage 部分和 TeX 部分再次同步。
.. _sagetex_installation_multiuser:
- 对于多用户系统上的安装，只需适当修改上述指令，将 ``sagetex.sty`` 复制到系统范围的 TeX 目录中。
最好的选择可能是使用以下结果，而不是 ``TEXMFHOME`` 目录：
.. code-block:: console
$ kpsewhich -var-value=TEXMFLOCAL
这很可能会产生类似于 ``/usr/local/share/texmf`` 的结果。
按照上述方式将 ``tex`` 目录复制到 ``TEXMFLOCAL`` 目录中。
现在需要通过运行以下命令更新 TeX 的包数据库：
.. code-block:: console
$ texhash TEXMFLOCAL
以 root 身份，适当替换 ``TEXMFLOCAL``。
现在系统中所有用户都可以访问 LaTeX 包，如果他们也能运行 Sage，他们就可以使用 SageTeX。
.. warning::
确保 LaTeX 在排版文档时使用的 ``sagetex.sty`` 文件与 SageTeX 使用的版本匹配，
这一点至关重要。如果你升级了 Sage，应该删除所有旧版本的 ``sagetex.sty``。
由于此问题，我们建议将 SageTeX 文件复制到主目录的 texmf 目录中（上述第 3 种方法）。
这样，升级 Sage 时，仅需做一件事（复制目录）即可确保 SageTeX 正常工作。
SageTeX 文档
------------
虽然这不严格属于安装的一部分，但值得在此提及的是，
SageTeX 的文档维护在 :file:`SAGE_ROOT/venv/share/doc/sagetex/sagetex.pdf`。
同一目录中还有一个示例文件 -- 请参见 ``example.tex`` 和 ``example.pdf``，
这是使用 LaTeX 和 Sage 对该文件进行排版的预生成结果。
你也可以从 `SageTeX 页面 <https://github.com/sagemath/sagetex>`_ 获取这些文件。
SageTeX 与 TeXLive
------------------
一个潜在的令人困惑的问题是流行的 TeX 发行版 `TeXLive <http://www.tug.org/texlive/>`_ 包含 SageTeX。
虽然看起来很方便，但对于 SageTeX 而言，确保 Sage 部分和 LaTeX 部分同步是非常重要的 -- 在这种情况下，
这就成为了一个问题，因为由操作系统发行版或软件包管理器提供的 TeXLive 可能与官方 TeXLive 分发版本不同步，
而后者也可能与当前的 SageTeX 版本不同步。
因此，*强烈建议* 你始终按照上面的说明，从 Sage 安装 SageTeX 的 LaTeX 部分。
上述说明将确保 SageTeX 的两个部分兼容并正常工作。
