Acetaminophen’s diary

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

TeX2img のコマンドライン版の使い方（改訂版）

TeX TeX2img ソフト
【最終更新 2015-08-23 02:50】Win 1.5.6 および Mac 1.9.8 に対応。
この記事は TeX2img のコマンドライン版の使い方を解説したものである。以前のバージョンを解説したアーカイブは別ページに残してある。

このブログではおなじみの TeX2img について、今度は Windows/Mac 両バージョンの CUI 版について使い方を網羅的に解説する。ただし、既に GUI 版の使い方の記事を読んでいることを前提とする。また、どちらかというと初心者向けに書いた GUI 版の解説とは異なり、今回の CUI 版の解説は必要最小限にとどめることにする*1。

 

特長

TeX2img の CUI 版は、GUI 版と同様の処理をコマンドラインで行うものであり、自動化に便利である。

【ソフトウェアの概要】

入力した TeX ソースコードを TeX でコンパイルして、画像として出力する。任意のエディタで作成したソースを読み込んで処理できる。その他詳細は GUI 版に準ずる。

配布サイト：Windows 版（阿部さん）、Mac 版（寺田さん）

Windows 版 1.5.6 と Mac 版 1.9.8 での変更点（2015-08-23 記載）

  • Win/Mac：ヘルプメッセージ等にオプションの現在値を表示
  • Win/Mac：クリップボードにコピー
    --copy-to-clipboard の追加
  • Win/Mac：オプション名の変更
    --no-embed-source → --[no-]embed-source（Win のみ影響）
    --no-delete → --[no-]delete-tmpfiles（Win/Mac に影響）
  • Win/Mac：CUI のデフォルト値の変更
    Win は --delete-display-size をデフォルト無効に
    Mac は --guess-compile, --transparent をデフォルト有効に
  • Win：--load-defaults オプションの追加
  • Mac：ON/OFF 切り替え系の全オプションに no- 付きを追加
    Win/Mac とも相反するオプションを指定可能に（最後に指定されたものが有効）

 

インストール方法

Windows 版

GUI 版の TeX2img.exe と CUI 版の TeX2imgc.exe が zip アーカイブに同梱されている。CUI 版はコンソール出力機能を持ったラッパーにすぎないので、展開後 TeX2imgc.exe と TeX2img.exe（および mudraw.exe, pdfiumdraw.exe）は同じフォルダに置いておく必要がある。このフォルダに PATH を通しておけば、コマンドラインから tex2imgc と入力して CUI 版を起動できる。

Mac 版

CUI 版の tex2img という実行ファイルが単独で配布されている。展開後 PATH の通ったディレクトリに置けば、ターミナルから tex2img と入力して CUI 版を起動できる。ただし、SVG 画像の出力には mudraw を事前にインストールしておく必要がある*2。

 

初めに知っておくべきこと

最も重要な点は、今述べたばかりではあるが

Mac 版は GUI (TeX2img.app) と CUI (tex2img) が独立のバイナリである

Windows 版は GUI (TeX2img.exe) のラッパーとして CUI (TeX2imgc.exe) がある

ことである*3。したがって

  • 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 で統一する。また、Windows 版の --option[-] とは、そのオプションを有効に (True) する場合は単に --option と入力し、無効に (False) する場合は --option- と末尾にマイナスを付けることを意味する。

 

試しに使ってみる

まずはヘルプを読むべきであろう。ここにすべての引数とオプションが書かれている。Windows 版はメッセージ表示時点で採用されている各オプションの現在の値が、Mac 版は各オプションの既定のデフォルト値が表示されている（Win 1.5.6 と Mac 1.9.8 以降）。

tex2img(c) --help

と入力すれば、以下のようなヘルプドキュメントが表示される。

Windows 版 1.5.6：

使い方：TeX2imgc.exe [Options] Input Output
  /platex=<VAL>            platex のパス（現在：C:\w32tex\bin\platex.exe）
  /dvipdfmx=<VAL>          dvipdfmx のパス（現在：C:\w32tex\bin\dvipdfmx.exe）
  /gs=<VAL>                Ghostscript のパス（現在：C:\gs\gs9.16\bin\gswin32c.exe）
  /gsdevice=<VAL>          Ghostscript の device（epswrite/eps2write）（現在：epswrite）
  /kanji=<VAL>             文字コード（utf8/sjis/jis/euc/no)（現在：no）
  /guess-compile[-]        LaTeX ソースコンパイル回数を推定（現在：true）
  /num=<NUM>               LaTeX ソースコンパイルの（最大）回数（現在：10）
  /resolution=<NUM>        解像度レベル（現在：6）
  /left-margin=<NUM>       左余白（現在：0）
  /right-margin=<NUM>      右余白（現在：0）
  /top-margin=<NUM>        上余白（現在：0）
  /bottom-margin=<NUM>     下余白（現在：0）
  /unit=<VAL>              余白の単位（bp/px）（現在：px）
  /transparent[-]          透過 PNG / TIFF / EMF（現在：true）
  /with-text[-]            PDF のテキスト情報を保持（現在：false）
  /delete-display-size[-]  SVG の表示寸法を削除（現在：false）
  /antialias[-]            アンチエイリアス処理（現在：true）
  /low-resolution[-]       低解像度で処理（現在：false）
  /ignore-errors[-]        少々のエラーは無視（現在：false）
  /delete-tmpfiles[-]      一時ファイルを削除（現在：true）
  /preview[-]              生成されたファイルを開く（現在：false）
  /embed-source[-]         ソース情報を生成ファイルに保存（現在：true）
  /copy-to-clipboard[-]    生成したファイルをクリップボードにコピー（現在：false）
  /savesettings[-]         設定の保存を行う（現在：false）
  /quiet[-]                Quiet モード（現在：false）
  /timeout=<NUM>           タイムアウト時間を設定（秒）（現在：0）
  /batch=<VAL>             Batch モード（stop/nonstop）（現在：stop）
  /exit                    設定の保存のみを行い終了する
  /load-defaults           現在の設定をデフォルトに戻す
  /help                    このメッセージを表示する
  /version                 バージョン情報を表示する

Mac 版 1.9.8：

Usage: tex2img [options] InputFile OutputFile
Arguments:
  InputFile  : path of a TeX source or PDF file
  OutputFile : path of an output file
               (*extension: eps/pdf/svg/jpg/png/gif/tiff/bmp)
Options:
  --compiler   COMPILER      : set the LaTeX compiler (default: platex)
  --kanji ENCODING           : set the Japanese encoding (no|utf8|sjis|jis|euc) (default: no)
  --[no-]guess-compile       : disable/enable guessing the appropriate number of compilation (default: enabled)
  --num        NUMBER        : set the (maximal) number of compilation
  --dvipdfmx   DVIPDFMX      : set dvipdfmx    (default: dvipdfmx)
  --gs         GS            : set ghostscript (default: gs)
  --resolution RESOLUTION    : set the 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)
  --[no-]transparent         : disable/enable transparent PNG/GIF/TIFF (default: enabled)
  --[no-]with-text           : disable/enable text-embedded PDF (default: disabled)
  --[no-]delete-display-size : disable/enable deleting width and height attributes of SVG (default: disabled)
  --[no-]ignore-errors       : disable/enable ignoring nonfatal errors (default: disabled)
  --[no-]utf-export          : disable/enable substitution of \UTF{xxxx} for non-JIS X 0208 characters (default: disabled)
  --[no-]quick               : disable/enable speed priority mode (default: disabled)
  --[no-]preview             : disable/enable opening products (default: disabled)
  --[no-]delete-tmpfiles     : disable/enable deleting temporary files (default: enabled)
  --[no-]embed-source        : disable/enable embedding of the source in products (default: enabled)
  --[no-]copy-to-clipboard   : disable/enable copying products to the clipboard (default: disabled)
  --[no-]quiet               : disable/enable quiet mode (default: disabled)
  --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 版の相違点を含めてメモを残しておこうと思う。ただし以下の記述では Windows 版オプションの [-] および Mac 版オプションの [no-] は省略した。

プログラムの指定

Win： --platex PATH, --dvipdfmx PATH, --gs PATH, --gsdevice DEVICE

Mac： --compiler PATH, --dvipdfmx PATH, --gs PATH

Windows/Mac 版ともに、LaTeX, dvipdfmx, gs の実行ファイル名を指定できる。Windows 版では gs のデバイス名 (epswrite/eps2write) も引数付オプションで指定できる*4。最もよく使うのは LaTeX コンパイルエンジンを指定する際であろう。デフォルトは platex なので、例えば

  • Windows 版では --platex uplatex または --platex pdflatex
  • Mac 版では --compiler uplatex または --compiler pdflatex

などのように利用する。

現在の設定の保存と終了

Win： --savesettings, --exit

Mac： 該当無し

繰り返しになるが、Windows 版の CUI は設定を GUI と共有する。CUI から設定ファイルを上書き保存したい場合は、--savesettings を付けることになる（CUI のデフォルトは非保存、GUI は保存）。なお、Windows 版は設定上書きだけのために CUI 版を起動するという作業も可能となっているが、この場合は入出力ファイルが存在しないというメッセージが出る。これが嫌いなら --exit を付けるとよいだろう。

初期設定の読み込み

Win： --load-defaults

Mac： 該当無し

Win 1.5.6 で新設されたオプション。Windows 版の CUI は設定を GUI と共有するが、場合によっては不便になりうる*5。そこで --load-defaults を使えば、そのオプションが指定された時点で初期状態のデフォルト値を読み込ませる。そうすると、それまでに変更された全オプションや設定ファイルが無視されることになるので、安心して CUI 操作が可能になる。

エンコーディング指定

Win/Mac 共通： --kanji ENCODING

入力ファイルのエンコーディング指定である。ENCODING は utf8/sjis/jis/euc/no から選択（no は「指定しない」に対応）する。

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

コンパイル回数を推定するか否か、また最大コンパイル回数（推定を行わない場合は単なるコンパイル回数）を指定する。ちなみに 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) である。

アンチエイリアスの有無

Win： --antialias

Mac： 該当無し

Windows 版でアンチエイリアスを有効にする場合に用いる（Win 1.4.0 以前の --imagemagick は廃止されている）。

透過処理の有無

Win/Mac 共通： --transparent

PNG/GIF/TIFF 出力で透過処理を行う（GIF/TIFF は Mac 1.9.0 以降）。

PDF でテキスト保持

Win/Mac 共通： --with-text

PDF 出力で文字をアウトライン化せずにテキストを保持する（Mac 1.8.9 以前ではデフォルトがテキスト保持で、アウトライン化したい場合に --create-outline を付けるという仕様であったが、1.9.0 でオプションが逆転）。

SVG で寸法情報削除

Win/Mac 共通： --delete-display-size

SVG の寸法情報を削除（width, height 削除）する。

出力画像へのソース埋め込みの有無

Win/Mac 共通： --embed-source

出力画像の拡張属性として TeX ソースを埋め込む機能が標準で有効である。しかし、特に GUI を使わずに CUI のみで作業するユーザにとってはソース保持にメリットがないかもしれない。これをキャンセルする場合、Windows 版では --embed-source- と末尾にマイナスを付け、Mac 版では--no-embed-source と no- を付ける。

Ghostscript のエラー回避

Win： --low-resolution

Mac： --quick

それぞれ GUI の「低解像度で処理」と「速度優先モード」である。Ghostscript が VMerror を起こす場合に有効にすればエラーを回避できる。

コンパイルのエラー無視

Win/Mac 共通： --ignore-errors

「少々のエラーは無視する」である。

デバッグ用オプション

Win/Mac 共通： --delete-tmpfiles

「コンパイル後に一時ファイルを削除」に対応する。デフォルトで有効になっているが、デバッグなどの目的で一時ファイルを確かめたい場合は無効にするとよい。Windows 版では --delete-tmpfiles- と末尾にマイナスを付け、Mac 版では --no-delete-tmpfiles と no- を付ける。

環境依存文字の置換

Win： 該当無し

Mac： --utf-export

Mac 版のみの機能で「JIS X 0208 外の文字を \UTF{xxxx} に変換」である。これにより、ソースに環境依存文字を含む場合でも otf パッケージを用いて platex で処理が可能となる（ただし otf パッケージを読み込んでいる必要がある）。

出力画像プレビュー

Win/Mac 共通： --preview

「コンパイル後生成ファイルを開く」を CUI からも指定できる。Windows 版は GUI の設定をほとんど引き継ぐのだが、前提として

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

という考えから、他のオプションとは異なり、唯一 CUI に GUI での指定を無視させている。CUI であえてプレビューしたければ --preview を付け加えるとよいだろう。

処理の継続有無の指定

Win： --batch <VAL>, --timeout <VAL>

Mac： 該当無し

Windows 版は呼び出したプログラムのフリーズや無限ループへの対策として、処理を中断する機能を持つ。CUI なら Ctrl + C で停止することもできるが、より安全な方法で停止するために開発されたのが --batch オプションと --timeout オプションである。

歴史的経緯により少々わかりにくいオプションになっているが、Win 1.5.2 以降の挙動は以下のとおりである：

  • オプション無し → プログラムは中断することなく継続される
  • --batch nonstop → プログラムは中断することなく継続される
  • --batch stop → プログラムは中断することなく継続される（！）
  • --batch stop かつ --timeout 10 → プログラムが10秒待っても終了しない場合に強制終了
  • --timeout 10 → 10秒ごとにユーザに継続確認を求める

--timeout オプションを単独で指定した場合は、指定した時間ごとにユーザに継続確認を求める。--batch オプションを付けるとユーザに継続確認を求めることは決してなく、--timeout オプションで指定した時間で処理を強制終了する。時間の閾値を指定する --timeout オプションのデフォルト値は無限大であるため、単に --batch stop とするだけでは停止しない（必ず --timeout オプションと共存させる必要がある）。

その他

Win/Mac 共通： --quiet, --version, --help

コンソールにログを表示したくない場合は --quiet を指定する。バージョン情報表示は --version であり、ヘルプメッセージは初めに述べたとおり --help である。

 

両バージョンのユーザとしての個人的な補足

Mac 版は CUI が GUI から独立しているので、必要なオプションをユーザが指定したとおりに実行してくれるという点で単純明快である。

Windows 版は CUI が GUI と設定を共有するので、「GUI でオプションを先に指定してしまい、CUI ではオプションを一切指定せずに使う」という方法や「GUI は面倒なので CUI でオプションを一気に設定して保存する」という方法も考えられる。使いやすい方法で OK だ。

Windows 版は、オプションの解釈を担う NDesk.Options の「--option に対して --option- のように末尾に「マイナス」を付けることで TRUE/FALSE を区別する」という仕様に基づく。これを活用することで

  • オプションが省略された場合：GUI の設定を引き継ぐ
  • オプションが指定された場合：TRUE と解釈
  • オプションにマイナスが付いた場合：FALSE と解釈

という区別が可能となり、入力の手間が省けて効率的である。オプション解釈については既にあべのりさんの にっき♪ (2014-12-12) で説明されているのでこちらを参照。

その他細かい点

  • Windows 版については、GUI ではエディタコンポーネントの Azuki.dll が必須であるため、存在しなければ起動しない設定になっている。一方 CUI では当然ながら必要ないため、チェックは行われない。

 

…というわけで、簡潔にまとめるつもりが書いているうちに長くなってしまった。まあ何かの役に立てば幸いである。

*1:「優れた GUI があるにもかかわらず、あえて CUI を使う」ことを選択するユーザがこの記事の読者の大半であることを想定してのことである。また、Windows/Mac 両バージョンの挙動が少々異なるため、両方のユーザである僕自身も時々混乱するので、ここでいったん整理しておく意味合いもある。

*2:仮に GUI 版の TeX2img.app を、標準的なインストール先である /Applications（または美文書6版のデフォルトの /Applications/TeXLive）に置いておけば、特別な操作を必要とせずその中の mudraw を勝手に使ってくれる。その他の場所に TeX2img.app を置いている場合は、その TeX2img.app/Contents/Resources/mupdf にパスを通しておけばよい。GUI 版をインストールしない場合は、MacPorts などを使って自分で mudraw (mupdf) をインストールしておく。

*3:本当は阿部さんの方針としては「同一バイナリでオプションで分けるのがよいのですが，挫折しかけです．次善の策としてのラッパにしようかなと思います．」とのこと。

*4:Mac 版は実行時にデバイス名を自動推定する。Windows 版も基本的に自動推定するが、GUI にもチェックボックスがあるとおり、推定を誤ったとき・不都合があるときに切り替える場合に用いる。

*5:たとえば、GUI の設定を頻繁に切り替える可能性を考えよう。この場合「現在の GUI 設定は余白5だろうか、0だろうか」と心配しながら CUI を使わざるをえなくなり、結果として余白0の画像を CUI で作りたい場合に「安全を期すために毎回余白オプションを0と明示しなければならない」という事態が生じうる。