SageTeXを使う#

SageTeXパッケージを使うと，Sageによる処理結果をLaTeX文書に埋め込むことができるようになる．利用するためには，まずSageTeXを「インストール」しておかなければならない(TeXにSageTeXの存在を教える節を参照)．

具体例#

ここでは，ごく簡単な例題を通してSageTeXの利用手順を紹介する．完全な解説ドキュメントと例題ファイルは，ディレクトリ SAGE_ROOT/venv/share/doc/sagetex に置いてある． SAGE_ROOT/venv/share/texmf/tex/latex/sagetex にあるPythonスクリプトは何か役に立つ場面があるはずだ．以上の SAGE_ROOT は，Sageをインストールしたディレクトリである．

SageTeXの動作を体験するために，まずSageTeXのインストール手続き(TeXにSageTeXの存在を教える節)を実行し，以下のテキストを st_example.tex などという名前で保存しておいてほしい:

警告

このテキストを "live"ヘルプから表示すると命令未定義エラーになる．正常に表示するためには "static"ヘルプで表示すること．

\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.sage というファイルが出来ていることだ．これは st_example.tex の処理畤に生成されたSageスクリプトで，上で見たLaTeX処理時のメッセージは，この st_example.sage をSageで実行せよという内容である．その通り実行すると st_example.tex を再びLaTeXで処理せよと告げられるが，その前に新しいファイル st_example.sout が生成されていることに注意．このファイルにはSageの演算結果がLaTeXテキストに挿入して利用可能な形式で保存されている．プロット画像のEPSファイルを含むディレクトリも新規作成されている．ここでLaTeX処理を実行すると，Sageの演算結果とプロットの全てがLaTeX文書に収められることになる．

上の処理に用いられた各マクロの内容はごく簡単に理解できる． sageblock 環境はSageコードを入力通りに組版し，ユーザーがSageを動かすとそのコードを実行する． \sage{foo} とすると， Sage上で latex(foo) を実行したのと同じ結果がLaTeX文書に挿入される．プロット命令はやや複雑だが，もっとも単純な場合である \sageplot{foo} は foo.save('filename.eps') を実行して得られた画像を文書へ挿入する役割を果たす．

要するに，必要な作業は以下の三段階になる:

LaTeXで .texファイルを処理
生成された .sageファイルをSageで実行
LaTeXで .texファイルを再処理

作業中にLaTeX文書内のSageコマンドを変更しない場合，Sageによる処理は省略することができる．

SageTeXは到底以上で語り尽せるものでなく，SageとLaTeXは共に複雑で強力なツールだ． SAGE_ROOT/venv/share/doc/sagetex にあるSageTeXのドキュメントを読むことを強くお勧めする．

TeXにSageTeXの存在を教える#

Sageはおおむね自己完結的なシステムなのだが，正しく機能するために外部ツールの介入を要する部分があることも確かだ． SageTeXもそうした部分の一つである．

SageTeXパッケージを使えばSageによる演算やプロットをLaTeX文書に埋め込むことが可能になる． SageTeXはデフォルトでSageにインストールされるが，LaTeX文書で利用する前に，運用しているTeXシステムへSageTeXの存在を教えておかねばならない．

鍵になるのは， TeXが sagetex.sty を発見できるかどうかである．この sagetex.sty は， SAGE_ROOT をSageがビルトあるいはインストールされたディレクトリとすると， SAGE_ROOT/venv/share/texmf/tex/latex/sagetex/ に置かれているはずだ． TeXが sagetex.sty を読めるようにしてやらなければ，SageTeXも動作できないのである．これを実現するには何通りかのやり方がある．

第一の，かつ一番簡単な方法は， sagetex.sty を作成すべきLaTeX文書と同じディレクトリ内にコピーしておくことである． TeXは組版処理の際に現ディレクトリを必ずサーチするから，この方法は常に有効だ．

ただし，このやり方には二つのちょっとした問題点がある．一つ目は，このやり方では使用しているシステムが重複した sagetex.sty だらけになってしまうこと．二つ目の，もっと厄介な問題は，この状態でSageが更新されてSageTeXも新しいバージョンになった場合，SageTeXを構成するPythonコードやLaTeXコードとの食い違いが生じて実行時にエラーが発生しかねない点である．
第二の方法は，環境変数 TEXINPUTS を利用することである． bashシェルを使っているなら
```
export TEXINPUTS="SAGE_ROOT/venv/share/texmf//:"
```
と実行すればよい．ただし SAGE_ROOT はSageのインストール先ディレクトリである．上の実行例では，行末にスラッシュ2個とコロンを付け忘れないでいただきたい．実行後は，TeXと関連ツールがSageTeXスタイルファイルを見つけられるようになる．上のコマンド行を .bashrc に付加して保存しておけば設定を永続させることができる． bash以外のシェルを使っている場合， TEXINPUTS 変数を設定するためのコマンドも異なる可能性がある．設定法については，自分の使っているシェルのドキュメントを参照のこと．

この方法にも瑕はある．ユーザがTeXShopやKile，あるいはEmacs/AucTeXなどを使っている場合，必ずしも環境変数を認識してくれるとは限らないのである．これらのアプリケーションが常にシェル環境を通してLaTeXを起動するわけではないからだ．

インストール済みの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
```
と実行すればよい．ただし TEXMFLOCAL を現実に合わせて変更するのは先と同じだ．これでシステムの全ユーザはSageTeXパッケージへアクセス可能になり，Sageが利用できればSageTeXも使えるようになる．

警告

肝心なのは，LaTeXが組版処理時に使う sagetex.sty ファイルと，Sageが援用するSageTeXのバージョンが一致していることである． Sageを更新したら，あちこちに散らばった古いバージョンの sagetex.sty を面倒でも全て削除してやらなければいけない．

SageTeX関連ファイルをホームディレクトリの texmf ディレクトリ内にコピーしてしまうこと(先に紹介した第三の方法)をお勧めするのは，この面倒があるからである．第三の方法にしておけば，Sage更新後もSageTeXを正常に動作させるために必要な作業はディレクトリを一つコピーするだけになる．

SageTeXドキュメント#

厳密にはSageのインストール一式には含まれないものの，ここで SageTeXのドキュメントが SAGE_ROOT/venv/share/doc/sagetex/sagetex.pdf に配置されていることに触れておきたい．同じディレクトリには例題ファイルと，これをLaTeXとSageTeXによってすでに組版処理した結果も用意されている(example.tex と example.pdf を参照)．これらのファイルは SageTeX ページからダンロードすることもできる．

SageTeXとTeXLive#

混乱を招きかねない問題点の一つとして，人気あるTeXディストリビューション TeXLive 2009 にSageTeXが含まれている現実があげられる．これは有り難い感じがするかもしれないが，SageTeXに関して重要なのはSageとLaTeXの各要素が同期していることだ． SageとSageTeXは共に頻繁にアップデートされるがTeXLiveはそうではないから，その「同期」のところで問題が生じる．この文の執筆時点(2013年3月)では，多くのLinuxディストリビューションが新しいTeXLiveリリースに移行しつつある．しかし2009リリースもしぶとく生き残っていて，実はこれがSageTeXに関するバグレポートの主要な発生源になっているのだ．

このため 強く推奨 させていただきたいのは，SageTeXのLaTeX関連部分は以上で説明したやり方で常にSageからインストールすることである．上記の手順に従えば，SageTeXのSageおよびLaTeX対応部分の互換性が保証されるから，動作も正常に保たれる． SageTeXのLaTeX対応部分をTeXLiveから援用することはサポート対象外になる．