# SageTeXを使う

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

## 具体例

ここでは，ごく簡単な例題を通してSageTeXの利用手順を紹介する． 完全な解説ドキュメントと例題ファイルは，ディレクトリ `SAGE_ROOT/local/share/doc/sagetex` に置いてある． `SAGE_ROOT/local/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/local/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/local/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/local/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/local/share/texmf/` 内の `tex/` ディレクトリをホームディレクトリの `texmf` にコピーするには

      cp -R SAGE_ROOT/local/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/local/share/doc/sagetex/sagetex.pdf` に配置されていることに触れておきたい． 同じディレクトリには例題ファイルと，これをLaTeXとSageTeXによってすでに組版処理した結果も用意されている(`example.tex` と `example.pdf` を参照)． これらのファイルは SageTeX bitbucket ページ からダンロードすることもできる．

### 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から援用することはサポート対象外になる．