TeX2img のコマンドライン版の使い方（旧版アーカイブ）
重要：以下の内容は古くなっています！(2015-08-13)
この記事は TeX2img CUI 版の下記バージョンに対応している。 最新版（Windows 版 1.5.6 及び Mac 版 1.9.8）とは仕様が大幅に異なるが、念のためアーカイブとして残しておくものである。最新記事はこちら。
TeX2img Windows 版 1.3.0 と Mac 版 1.8.6
このブログで何度も紹介してきた TeX2img であるが、今回の Windows 版 1.3.0 リリースで新たに CUI 版が追加された。そこで、Windows/Mac 両バージョンの CUI 版について使い方を解説する。ただし、既に GUI 版の使い方の記事を読んでいることを前提とする。また、どちらかというと初心者向けに書いた GUI 版の解説とは異なり、今回の CUI 版の解説は必要最小限にとどめることにする。
Windows 版 1.3.0 と Mac 版 1.8.6 での変更点（2014-11-22 記載）
- コンパイル回数推定機能
GUI 版にも関連するため、以前の記事に追記した。これにより相互参照（数式番号などを含む）が問題なく処理できるはずである。 - Windows 版 GUI でプログラムのパス指定への制限撤廃
従来 GUI ではプログラムをフルパスで指定する必要があったが、Windows 版に限り CUI と設定を連動させる都合でこの制約を撤廃した。システムで PATH さえ通っていれば正常に呼び出せるはずである。Mac 版の GUI は従来どおりフルパス指定を用いる必要がある。
Windows 版の更新履歴
- Win 1.3.1, 1.3.2 での仕様変更（2014-12-14, 2014-12-20 追記）
- プログラムのパス推定機能の強化（CUI でも初回起動時に推定）
- オプション指定方法の変更（TRUE/FALSE を撤廃してスマートに）
--batchの新設（1.3.1 では引数無し、1.3.2 で stop/nonstop 指定）
- Win 1.5.0 での仕様変更（2015-03-23 追記）
--imagemagickを廃止・--antialiasを追加--with-textを追加
- Win 1.5.2 での仕様変更（2015-06-07 追記）
--timeoutを追加（--batchに影響）
Mac 版の更新履歴
- Mac 1.8.6 から Mac 1.8.7 での仕様変更（2014-12-20 追記）
--previewを追加--kanjiの値から uptex を廃止し utf8 に統合
- Mac 1.8.7 から Mac 1.8.8.1 での仕様変更（2015-02-26 追記）
--dvipdfmx,--gsを追加--kanjiの値に no を新設
- Mac 1.8.8.1 から Mac 1.9.1 での仕様変更（2015-03-24 追記）
--delete-display-sizeを追加--create-outlineを廃止--with-textを追加（1.9.0 で新設した--text-pdfから改名）
初めに知っておくべきこと
最も重要な点は
Mac 版は GUI (TeX2img.app) と CUI (tex2img) が独立のバイナリである
Windows 版は GUI (TeX2img.exe) のラッパーとして CUI (TeX2imgc.exe) がある
ことである*1。したがって
- Mac 版は GUI の設定にかかわらず CUI のオプション指定のみで動作する（いくつかはデフォルトの値をもっている）。
- Windows 版は GUI の設定を引き継ぎ、明示的に CUI のオプションを付けたところだけ置き換わる。さらに、
--savesettingsとすれば CUI から GUI の設定を上書き保存することができる。
この点を押さえておけば、あとは CUI のオプションを GUI のオプションに対応付けるだけで理解できるはずであろう。
実行コマンドは
となっているので、この記事では以下 tex2img(c) と書くことで統一する。また、オプションについて Windows 版ではいくつかの記法が可能であり、例えば
--option VALUE--option=VALUE-option VALUE/option VALUE
などは全て受け付けてくれる。Mac 版に合わせるため以下では --option VALUE で統一する。
試しに使ってみる
まずはヘルプを読むべきであろう。ここにすべての引数とオプションが書かれている。
tex2img(c) --help
と入力すれば、以下のようなヘルプドキュメントが表示される。
Windows 版 1.3.0：
使い方：TeX2imgc.exe [Options] Input Output /platex <VAL> platex のパス /dvipdfmx <VAL> dvpdfmx のパス /gs <VAL> Ghostscript のパス /gsdevice <VAL> Ghostscript の device の値（epswrite/eps2write） /exit 設定の保存のみを行い終了する． /savesettings 設定の保存を行う /resolution <VAL> 解像度レベル /left-margin <VAL> 左余白 /right-margin <VAL> 右余白 /top-margin <VAL> 上余白 /bottom-margin <VAL> 下余白 /unit <VAL> 余白の単位（bp/px） /kanji <VAL> 文字コードの指定（utf8/sjis/jis/euc/no) /ignore-errors <VAL> 少々のエラーは無視する（true/false） /low-resolution <VAL> 低解像度で処理する（true/false） /quiet Quiet モード /no-delete <VAL> 一時ファイルを削除しない（true/false） /num <VAL> LaTeX ソースコンパイルの（最大）回数 /guess-compile <VAL> LaTeX ソースコンパイル回数を推定（true/false） /imagemagick <VAL> ImageMagick を使う（true/false） /transparent <VAL> 透過 PNG を作る（true/false） /preview 生成されたファイルを開く /help このメッセージを表示する /version バージョン情報を表示する
Windows 版 1.5.2（1.5.5 まで同じ）：
使い方：TeX2imgc.exe [Options] Input Output /platex=<VAL> platex のパス /dvipdfmx=<VAL> dvipdfmx のパス /gs=<VAL> Ghostscript のパス /gsdevice=<VAL> Ghostscript の device の値（epswrite/eps2write） /kanji=<VAL> 文字コードの指定（utf8/sjis/jis/euc/no) /num=<VAL> LaTeX ソースコンパイルの（最大）回数 /guess-compile[-] LaTeX ソースコンパイル回数を推定 /resolution=<VAL> 解像度レベル /left-margin=<VAL> 左余白 /right-margin=<VAL> 右余白 /top-margin=<VAL> 上余白 /bottom-margin=<VAL> 下余白 /unit=<VAL> 余白の単位（bp/px） /transparent[-] 透過 PNG /with-text[-] PDF のテキスト情報を保持 /delete-display-size[-] SVG の表示寸法を削除 /antialias[-] アンチエイリアス処理 /low-resolution[-] 低解像度で処理 /ignore-errors[-] 少々のエラーは無視 /no-delete[-] 一時ファイルを削除しない /preview 生成されたファイルを開く /no-embed-source[-] ソース情報を生成ファイルに保存しない /savesettings 設定の保存を行う /quiet Quiet モード /timeout=<VAL> タイムアウト時間を設定（秒） /batch=<VAL> Batch モード（stop/nonstop） /exit 設定の保存のみを行い終了する /help このメッセージを表示する /version バージョン情報を表示する
Mac 版 1.8.6：
Usage: tex2img [options] InputTeXFile OutputFile
Arguments:
InputTeXFile : path of TeX source file
OutputFile : path of output file (extension: eps/png/jpg/pdf)
Options:
--compiler COMPILER : set compiler (default: platex)
--guess-compile : guess the appropriate number of compilation
--num NUMBER : set the (maximal) number of compilation
--resolution RESOLUTION : set resolution level (default: 15)
--left-margin MARGIN : set left margin (default: 0)
--right-margin MARGIN : set right margin (default: 0)
--top-margin MARGIN : set top margin (default: 0)
--bottom-margin MARGIN : set bottom margin (default: 0)
--unit UNIT : set the unit of margins to "px" or "bp" (default: px) (*bp is always used for EPS/PDF)
--create-outline : outline text in PDF
--transparent : generate transparent PNG file
--quick : convert in a speed priority mode
--kanji ENCODING : set Japanese encoding (sjis|jis|euc|utf8|uptex) (default: utf8)
--ignore-errors : force converting by ignoring nonfatal errors
--utf-export : substitute \UTF{xxxx} for non-JIS X 0208 characters
--quiet : do not output logs or messages
--no-delete : do not delete temporary files (for debug)
--version : display version info
--help : display this message
Mac 版 1.9.1（1.9.4 まで同じ）：
Usage: tex2img [options] InputTeXFile OutputFile
Arguments:
InputTeXFile : path of TeX source file
OutputFile : path of output file (extension: eps/pdf/svg/jpg/png/gif/tiff/bmp)
Options:
--compiler COMPILER : set compiler (default: platex)
--guess-compile : guess the appropriate number of compilation
--num NUMBER : set the (maximal) number of compilation
--dvipdfmx DVIPDFMX : set dvipdfmx (default: dvipdfmx)
--gs GS : set ghostscript (default: gs)
--resolution RESOLUTION : set resolution level (default: 15)
--left-margin MARGIN : set the left margin (default: 0)
--right-margin MARGIN : set the right margin (default: 0)
--top-margin MARGIN : set the top margin (default: 0)
--bottom-margin MARGIN : set the bottom margin (default: 0)
--unit UNIT : set the unit of margins to "px" or "bp" (default: px) (*bp is always used for EPS/PDF/SVG)
--with-text : generate text-embedded PDF files
--transparent : generate transparent images (for PNG/GIF/TIFF)
--delete-display-size : delete width and height attributes of SVG files
--no-embed-source : do not embed the source in image files
--quick : convert in a speed priority mode
--kanji ENCODING : set Japanese encoding (no|utf8|sjis|jis|euc) (default: no)
--ignore-errors : force conversion by ignoring nonfatal errors
--utf-export : substitute \UTF{xxxx} for non-JIS X 0208 characters
--quiet : do not output logs or messages
--no-delete : do not delete temporary files (for debug)
--preview : open the generated files
--version : display version info
--help : display this message
これを見ればオプションについてだいたいわかるはずである。まずはオプション無しで PNG 形式の画像を出力してみよう。TeX ソース（input.tex とする）があるディレクトリに移動 (cd) し
tex2img(c) input.tex output.png
のように入力すると、PNG 画像が生成するはずである。上に余白を付けたい場合は
tex2img(c) --top-margin 10 input.tex output.png
と入力すると、上に（デフォルトなら）10px の余白が付いているはずである。
各オプションの対応付け
以下では Windows 版と Mac 版の相違点を含めてメモを残しておこうと思う。
プログラムの指定
Win： --platex PATH, --dvipdfmx PATH, --gs PATH, --gsdevice DEVICE
Mac： --compiler PATH, --dvipdfmx PATH, --gs PATH
Windows/Mac 版ともに、LaTeX, dvipdfmx, gs の実行ファイル名を指定できる（Mac 版の --dvipdfmx, --gsは 1.8.8 で新設）。Windows 版では gs のデバイス名 (epswrite/eps2write) も引数付オプションで指定できる*2。最もよく使うのは LaTeX コンパイルエンジンを指定する際であろう。デフォルトは platex なので、例えば
- Windows 版では
--platex uplatexまたは--platex pdflatex - Mac 版では
--compiler uplatexまたは--compiler pdflatex
などのように利用する。
設定の保存と終了
Win： --savesettings, --exit
Mac： 該当無し
繰り返しになるが、Windows 版の CUI は設定を GUI と共有する。CUI から設定ファイルを上書き保存したい場合は、--savesettings を付けることになる（デフォルトは非保存）。なお、Windows 版は設定上書きだけのために CUI 版を起動するという作業も可能となっているが、この場合は入出力ファイルが存在しないというメッセージが出る。これが嫌いなら --exit を付けるとよいだろう。
エンコーディング指定
Win/Mac 共通： --kanji ENCODING
入力ファイルのエンコーディング指定である。ENCODING は utf8/sjis/jis/euc/no から選択する（no は「指定しない」に対応；Mac 版 1.8.6 までは utf8/sjis/jis/euc/uptex から選択、1.8.7 では utf8/sjis/jis/euc から選択）。
Windows 版の no に関しては補足しておく必要があるだろう。GUI を見ればわかるとおり、「指定しない」には2種類ある。この違いについては GUI 版の解説に書いたが、既存のソースファイルを読み込むだけの CUI（および GUI で「TeX ソースファイルを読み込む」とした場合）では両者に差はない。したがって、CUI の --savesettings で GUI の設定を上書きする場合の対応付けとしては
- 保存されている設定が「指定しない（入力 Shift_JIS）」の状態で
--kanji noとした場合は、設定を変更せず保持 - その他の状態で
--kanji noとした場合は、「指定しない（入力 UTF-8）」として処理
することになっている。
コンパイル回数設定
Win/Mac 共通： --guess-compile, --num NUMBER
コンパイル回数を推定するか否か、また最大コンパイル回数（推定を行わない場合は単なるコンパイル回数）を指定する（Win 1.3.0 は TRUEFALSE あり）。ちなみに Mac 版 CUI の --num のデフォルト値は
--guess-compileが ON のときは 3--guess-compileが OFF のときは 1
である。
出力画像の解像度と余白
Win/Mac 共通： --resolution NUMBER, --left-margin NUMBER, --right-margin NUMBER, --top-margin NUMBER, --bottom-margin NUMBER, --unit UNIT
解像度指定と余白指定、それに余白単位指定 (px/bp) である。
アンチエイリアスの有無（旧：ImageMagick を使うか否か）
Win 1.5.0 以降： --antialias
Win 1.4.0 以前： --imagemagick
Mac： 該当無し
Windows 版でアンチエイリアスを有効にする場合に使う。Windows 版 1.4.0 以前は追加インストールの ImageMagick を利用して高品質な PNG/JPEG 画像を得るスキームがあったが、1.5.0 で ImageMagick に依存せず Ghostscript のみでアンチエイリアスを行うことになったことに合わせ、オプション名を変更した（Win 1.3.0 は TRUEFALSE あり）。
透過処理の有無
Win/Mac 共通： --transparent
PNG/GIF/TIFF 出力で透過処理を行う（GIF/TIFF は Mac 1.9.0 以降；Win 1.3.0 は TRUEFALSE あり）。
PDF でテキスト保持
Win/Mac 共通： --with-text
PDF 出力で文字をアウトライン化せずにテキストを保持する（Win 1.5.0 と Mac 1.9.1 で新設；Mac 1.9.0 ではオプション名が --text-pdf だった）。なお Mac 版 1.8.9 以前ではデフォルトがテキスト保持で、アウトライン化したい場合に --create-outline を付けるという仕様であった（下記参照）。
PDF をアウトライン化【廃止済み】
Win： 該当無し
Mac 1.8.9 以前： --create-outline
Mac 版 1.8.9 以前はデフォルトが PDF 出力時にテキストを保持していた。このため、文字をアウトライン化する場合に --create-outline を付ける必要があった（Windows 版には PDF でテキスト保持というスキームがなかったため、デフォルトでアウトライン化に固定）。これは上記の「PDF テキスト保持」オプションの実装で廃止された。
SVG で寸法情報削除
Win/Mac 共通： --delete-display-size
SVG の寸法情報である width, height を削除する（Win 1.5.0 と Mac 1.9.0 で新設）。
出力画像へのソース埋め込みの無効化
Win/Mac 共通： --no-embed-source
出力画像の拡張属性として TeX ソースを埋め込む機能が標準で有効であるが、これをキャンセルする場合に用いる（Win 1.4.0 と Mac 1.8.8.1 で新設）。特に GUI を使わずに CUI のみで作業するユーザにとってはソース保持にメリットがないので、そうした場合に使うとよいかもしれない。
Ghostscript のエラー回避
Win： --low-resolution
Mac： --quick
それぞれ GUI の「低解像度で処理」と「速度優先モード」である。Ghostscript が VMerror を起こす場合に有効にすればエラーを回避できる（Win 1.3.0 は TRUEFALSE あり）。
コンパイルのエラー無視
Win/Mac 共通： --ignore-errors
「少々のエラーは無視する」である（Win 1.3.0 は TRUEFALSE あり）。
デバッグ用オプション
Win/Mac 共通： --no-delete
デバッグに有用な「一時ファイルを削除しない」である（Win 1.3.0 は TRUEFALSE あり）。
環境依存文字の置換
Win： 該当無し
Mac： --utf-export
Mac 版のみの機能で「JIS X 0208 外の文字を \UTF{xxxx} に変換」である。これにより、ソースに環境依存文字を含む場合でも otf パッケージを用いて platex で処理が可能となる（ただし otf パッケージを読み込んでいる必要がある）。
出力画像プレビュー
Win/Mac 共通： --preview
「コンパイル後生成ファイルを開く」を CUI からも指定できる（Mac 版は 1.8.6.1 で新設）。Windows 版は GUI の設定をほとんど引き継ぐのだが、前提として
という考えから、他のオプションとは異なり唯一 CUI に GUI での指定を無視させている。CUI であえてプレビューしたければ --preview を付け加えるとよいだろう。
処理の継続有無の指定
Win： --batch <VAL>, --timeout <VAL>
Mac： 該当無し
Windows 版は呼び出したプログラムのフリーズや無限ループへの対策として、処理を中断する機能を持つ。CUI なら Ctrl + C で停止することもできるが、より安全な方法で停止するために開発されたのが --batch オプション（1.3.1 以降）と --timeout オプション（1.5.2 以降）である。
歴史的経緯により少々わかりにくいオプションになっているので、まずは Win 1.5.2 以降の挙動について例を挙げる：
- オプション無し → プログラムは中断することなく継続される
--batch nonstop→ プログラムは中断することなく継続される--batch stop→ プログラムは中断することなく継続される（！）--batch stopかつ--timeout 10→ プログラムが10秒待っても終了しない場合に強制終了--timeout 10→ 10秒ごとにユーザに継続確認を求める
Win 1.2.3 から Win 1.5.0 までの挙動について、いくつか例を挙げる：
- オプション無し → 10秒ごとにユーザに継続確認を求める
--batch stop→ プログラムが10秒待っても終了しない場合に強制終了--batch nonstop→ プログラムは中断することなく継続される
Win 1.5.2 以降、--timeout オプションのデフォルトの値は無限大である一方、Win 1.2.3 から Win 1.5.0 まではこれにあたる値は10で固定されていた。Win 1.5.2 で値が変更されたのは「直感的により素直な GUI 中断機能が実装され、中断確認の必要性が薄れたから」である。すなわち --batch stop を使う場合は必ず --timeout オプションと共存させる必要がある*3。なお、--batch オプション無しで単独で --timeout オプションを指定した場合は、指定した時間ごとにユーザに継続確認を求めるようになっている。
その他
Win/Mac 共通： --quiet, --version, --help
コンソールにログを表示したくない場合は --quiet を指定する。バージョン情報表示は --version であり、ヘルプメッセージは初めに述べたとおり --help である。
両バージョンのユーザとしての個人的な補足
Mac 版は CUI が GUI から独立しているので、必要なオプションをユーザが指定したとおりに実行してくれるという点で単純明快である。
Windows 版は CUI が GUI と設定を共有するので、「GUI でオプションを先に指定してしまい、CUI ではオプションを一切指定せずに使う」という方法や「GUI は面倒なので CUI でオプションを一気に設定して保存する」という方法も考えられる。使いやすい方法で OK だ。
いくつかの注意点（既に過去のもの）
- Win 1.3.0 はプログラム推定が CUI ではたらかない。したがって、一度も GUI を利用したことがない場合（正確には GUI 設定ファイルが存在しない場合）は先にいったん GUI を起動することを勧める。あるいは、CUI 初回起動時にコマンドオプションで
--platex,--dvipdfmx,--gs,--gsdeviceを指定して保存しておくことになる。 → Win 1.3.1 で解消 - Win 1.3.0 はオプション引数の TRUE/FALSE が煩わしかった*4が、Win 1.3.1 で解消した。
- Mac 1.8.9 以前ではアウトライン化 PDF の出力時の
--create-outlineを忘れがちだったが、これは 1.9.1 で改善されている。
…というわけで、簡潔にまとめるつもりが書いているうちに長くなってしまった。まあ何かの役に立てば幸いである。
*1:本当は阿部さんの方針としては「同一バイナリでオプションで分けるのがよい
*2:Mac 版は実行時にデバイス名を自動推定する。Windows 版も基本的に自動推定するが、GUI にもチェックボックスがあるとおり、推定を誤ったとき・不都合があるときに切り替える場合に用いる。
*3:GUI の経緯と照らし合わせるとわかりやすくなる：プログラムの強制終了については、Windows 版 1.5.1 以前が GUI でユーザに10秒ごとに継続確認を出す機能を持っていた。これはかえってバッチ処理で不便になりうるため、CUI ではいちいちユーザに確認を求めない --batch nonstop オプションを作り、逆に毎回確認を求める --batch stop オプションとともに実装した。しかし、1.5.2 の変更により結果的に --batch nonstop は冗長というかたちになっている。
*4:逆に GUI/CUI の設定共有の都合上、判別しやすいというメリットがあるかもしれない；もし TRUE/FALSE 方式でなければ、オプションが省略された場合に「単に GUI の設定を引き継ぎたいから」なのか「オプションを FALSE に変更したいから」なのか区別不能となってしまう？
