GROFF_TMAC(5)

名前
groff_tmac - roff テキスト整形システムのマクロファイル

説明
roff(7) テキスト整形システムは、特定のドキュメントにとって便利なマクロパッケージを 提供している。それぞれのマクロパッケージはパッケージごとの tmac ファイル と呼ばれるファイルにマクロと定義を格納している。 この名前は `Troff MACros' に由来する。

tmac ファイルは普通の roff のソースドキュメントで、通常は定義とセットアップ コマンドだけを含み、テキストは含まれない。 すべての tmac ファイルは、ひとつあるいはいくつかのディレクトリ (tmac ディレクトリ) に格納される。

命名方法
古典的な roff システムでは、奇妙な命名規則が用いられていた。 マクロパッケージの名前が で始まる場合は、この文字は省略された。たとえばマニュアルページ man 用のマクロパッケージは an で、そのマクロファイルは tmac.an と命名された。

同じような理由から、 で始まらないマクロパッケージはしばしば を追加されて呼ばれた。たとえば、 tmac.doc に対応するパッケージは mdoc と呼ばれた。なぜなら、このマクロを用いるときのコマンドラインが以下のように 読めるからである。

    troff -mdoc

現行バージョンの groff(1) では、使用するマクロパッケージの命名方法は先行する がある場合・ない場合の両方を提供している。 したがって、 groff では man マクロパッケージは以下のように指定できる。

    groff -m man
    groff -man
    groff -mman
    groff -m an

システム上で有効なマクロパッケージを見つけるもっとも簡単な方法は、 tmac ディレクトリの内容をチェックすることである。 たとえば、 tmac.anything というファイルは anything という名前のマクロパッケージを定義している。

groff では、ほとんどのマクロパッケージが groff_<name>(7) というマニュアルページで説明されており、古典的なパッケージも を先行してある。

マクロの使用方法
ドキュメント中でマクロパッケージを使う方法はいくつかある。 実行時の指定方法では、groff の オプション で、 命名方法 のセクションで記述したようにマクロファイル tmac.name の定義を有効にする。

groff のリクエスト や を使ってドキュメント中でマクロファイルを指定することもできる。 では、マクロファイルは格納されているディレクトリも含めた完全なファイル名で 指定する必要がある。 マクロファイルが tmac ディレクトリのひとつに格納されている場合は、代わりに を使用する方が便利である。こちらはファイル名に tmac パスを追加して 検索をする。

と のリクエストを解決するために roff のプリプロセッサ が呼び出されなければならないことに注意すること。 これは、コマンドライン上のパイプラインで直接実行する方法と、 の オプションを使って呼び出す方法のどちらでも可能である。

規定 のセクションで記述してあるように、プリプロセッサ指定子の文字 で指定することもできる。

たとえば、マクロファイルが /usr/share/groff/tmac/tmac.macros に格納されていて、 docu.roff というドキュメントで使用すると仮定する。

実行時では、フォーマッタの呼び出し方法は以下のようになる。

ドキュメント中でマクロファイルを直接指定するには、
    .mso tmac.macros
を用いるか、
    .so /usr/share/groff/tmac/tmac.macros
と指定する。

どちらの場合でも、フォーマッタを
    groff -s docu.roff
のようにして呼び出す。

規定

最近の多くの roff 整形システムでサポートされている プリプロセッサ指定子 の規定について以下に記述する。

ドキュメントの先頭行がコメントの場合は、コメント文字と空白に続く最初の 文字は プリプロセッサ指定子 を構成する。 つまり、これらの文字はドキュメントを整形するときに起動される プリプロセッサコマンドの省略形とみなされる。 たいていは、プリプロセッサの呼び出しオプションと一致する文字だけが認識され、 以下のものがある。 (roff(7) を参照のこと)

ユーザに良き助言を与えるならば、いくつかのフォーマッタ (たとえば man(1) プログラムなど) もプリプロセッサ指定子によって指定されたプリプロセッサを 自動的に起動することができる。しかし、その動作を期待するべきではない。

マクロファイルの記述方法
groff のマクロファイルを記述することは簡単である。 一連のマクロ、文字列、レジスタなどをデザインし、それらをひとつのファイルに 格納する。このマクロを用いるドキュメントで リクエストによってマクロファイルを指定する方法は マクロの使用方法 のセクションに記述してある。

tmac の機能を用いるには、マクロファイルを tmac.whatever のように命名して tmac パスで指定されるディレクトリに格納する (ファイル のセクションを参照)。 そして、ドキュメントでは マクロの使用方法 のセクションで記述してあるように、 リクエストや オプションによってそのマクロを使用することができる。

もしあなたのマクロが一般的な用途に向いているならば、groff のメンテナに 連絡をとって groff の contrib ソースディレクトリにそれらを含めるようにしてほしい。

マクロの記述には、一般的なガイドラインのいくつかが役に立つだろう。

•   機能的なバックスラッシュはすべて二重にする。 ->

•   表示するためのバックスラッシュは次のように記述する。

•   ドットはすべてエスケープする。 ->

•   テキスト部分には非表示文字である を の前と行の先頭に広く用いるようにする。ただし後に続くコマンドがある場合は この限りではない。

•   一時的な変数名には文字 を用いる。

•   マクロはテキストとグラフィックのデバイスでテストする。たとえば latin1 と ps など。

ファイル
tmac のメカニズムで用いようとするマクロの名前は tmac.name という形式で命名されていなければならない。

マクロファイルは tmac パス を構成する tmac ディレクトリ に格納される。 Filesystem Hierarchy Standard (FHS) に準拠していれば、 groff の標準的な tmac ディレクトリの場所は /usr/share/groff/tmac であり、ローカルな導入先は /usr/local/share/groff/tmac が用いられるだろう。 古いシステムにおいては、 /usr/lib 以下のサブディレクトリを使用していた。 デフォルトの tmac パスとは独立して、実際にドキュメントで用いられる tmac パスは常にシェル環境変数で指定することができる。セクション 環境変数 を参照のこと。

環境変数

GROFF_TMAC_PATH
    マクロファイルを検索するための tmac ディレクトリ (tmac パス) をコロンで区切ったリスト。 指定されていない場合は、 ファイル のセクションで示したデフォルトのパスが使用される。

バグ
現在、groff システムのドキュメントは進化の途上にある。 一時的にドキュメント同士でささやかな矛盾点が見られるだろう。

著者
このドキュメントは groff (GNU roff パッケージ) の一部である。 Bernd Warken <bwarken@mayn.de> によって記述された。

このドキュメントは FDL (GNU Free Documentation License) のバージョン 1.1 以降の元に配布される。あなたのシステムにも FDL のコピーがあるはずである。 以下でもオンラインで参照できる。

    <http://www.gnu.org/copyleft/fdl.html>.

関連項目
groff システムの詳細について、信ずべき情報源は、groff の info(1) ファイルである。

groff の概要については roff(7) と groff ソースパッケージの README ファイルを参照のこと。

groff の tmac マクロパッケージについては以下を参照のこと。 groff_man(7), groff_markup(7), groff_mdoc(7), groff_mdoc.samples(7), groff_me(7), groff_mm(7), groff_mmroff(7), groff_ms(7), groff_msafer(7)

groff 言語については groff(7) に、フォーマッタについては groff(1) と troff(1) に記述されている。

Filesystem Hierarchy Standard (FHS) については http://www.pathname.com/fhs/ を参照のこと。