Acetaminophen’s diary

化学に関すること,TeXに関すること,ゆきだるまに関すること。

TeX2img のコマンドライン版の使い方(旧版アーカイブ)

重要:以下の内容は古くなっています!(2015-08-13)
この記事は TeX2img CUI 版の下記バージョンに対応している。
  • Windows 版 1.3.0 から 1.5.5 まで
  • Mac 版 1.8.6 から 1.9.4 まで
最新版(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 版にも関連するため、以前の記事に追記した。これにより相互参照(数式番号などを含む)が問題なく処理できるはずである。
  • WindowsGUI でプログラムのパス指定への制限撤廃
    従来 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 のオプションに対応付けるだけで理解できるはずであろう。

実行コマンドは

  • Windows 版では tex2imgc
  • Mac 版では tex2img

となっているので、この記事では以下 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--savesettingsGUI の設定を上書きする場合の対応付けとしては

  • 保存されている設定が「指定しない(入力 Shift_JIS)」の状態で --kanji no とした場合は、設定を変更せず保持
  • その他の状態で --kanji no とした場合は、「指定しない(入力 UTF-8)」として処理

することになっている。

コンパイル回数設定

Win/Mac 共通--guess-compile, --num NUMBER

コンパイル回数を推定するか否か、また最大コンパイル回数(推定を行わない場合は単なるコンパイル回数)を指定する(Win 1.3.0 は TRUEFALSE あり)。ちなみに MacCUI--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/TIFFMac 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 の設定をほとんど引き継ぐのだが、前提として

  • GUI はプレビューする方が自然
  • CUI はしない方が自然

という考えから、他のオプションとは異なり唯一 CUIGUI での指定を無視させている。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 版は CUIGUI から独立しているので、必要なオプションをユーザが指定したとおりに実行してくれるという点で単純明快である。

Windows 版は CUIGUI と設定を共有するので、「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 に変更したいから」なのか区別不能となってしまう?