.. _sec-sagetex: =============== SageTeXを使う =============== SageTeXパッケージを使うと，Sageによる処理結果をLaTeX文書に埋め込むことができるようになる． 利用するためには，まずSageTeXを「インストール」しておかなければならない(:ref:`sec-sagetex_install` 節を参照)． 具体例 ======= ここでは，ごく簡単な例題を通してSageTeXの利用手順を紹介する． 完全な解説ドキュメントと例題ファイルは，ディレクトリ ``SAGE_ROOT/local/share/doc/sagetex`` に置いてある． ``SAGE_ROOT/local/share/texmf/tex/latex/sagetex`` にあるPythonスクリプトは何か役に立つ場面があるはずだ． 以上の ``SAGE_ROOT`` は，Sageをインストールしたディレクトリである． SageTeXの動作を体験するために，まずSageTeXのインストール手続き(:ref:`sec-sagetex_install` 節)を実行し， 以下のテキストを ``st_example.tex`` などという名前で保存しておいてほしい: .. warning:: このテキストを "live"ヘルプから表示すると命令未定義エラーになる． 正常に表示するためには "static"ヘルプで表示すること． .. 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は以下のような文句をつけてくるだろう: :: 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のドキュメントを読むことを強くお勧めする． .. _sec-sagetex_install: 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_installation_multiuser: - 複数ユーザに対応するシステムでは，以上の手続きを変更して ``sagetex.sty`` を公開運用中のTeXディレクトリにコピーすればよい． おそらく一番賢いコピー先は ``TEXMFHOME`` ディレクトリではなく，コマンド :: kpsewhich -var-value=TEXMFLOCAL の実行結果に従うことだろう．出力は ``/usr/local/share/texmf`` のようになるはずで， 上と同じように ``tex`` ディレクトリを ``TEXMFLOCAL`` ディレクトリ内にコピーする． ついでTeXのパッケージデータベースを更新しなければならないが，これは簡単で，ルート権限で :: texhash TEXMFLOCAL と実行すればよい．ただし ``TEXMFLOCAL`` を現実に合わせて変更するのは先と同じだ． これでシステムの全ユーザはSageTeXパッケージへアクセス可能になり，Sageが利用できればSageTeXも使えるようになる． .. warning:: 肝心なのは，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から援用することはサポート対象外になる．