man groff_tmac (5): roff 清書システム内にあるマクロファイル

解説

roff(7) 清書システムは、特殊な用途のドキュメントに適したマクロパッケージを提供しています。それぞれのマクロパッケージは、そのパッケージの tmac ファイル と呼ばれるファイル中にマクロおよび定義を格納しています。 tmac という名前は、 `Troff MACros' を縮めたものです。

tmac ファイルは、普通の roff ソースドキュメントです。ただし、通常このファイルには定義および設定コマンドしか含まれておらず、テキストは入っていません。tmac ファイルはすべて tmac ディレクトリという 1 つあるいは少数のディレクトリ内に保管されています。

名称付け

古くからある roff システムには、奇妙な名称付けの体系がありました。マクロパッケージの名称が m で始まっている場合には、この文字は省略されました。例えば、マニュアルページ用のマクロパッケージ man は an と呼ばれ、そのパッケージのマクロファイルは tmac.an と呼ばれました (現在のバージョンの groff では、このファイルは代りに an.tmac と呼ばれることに注意してください)。

似たような理由で、名称が m で始まらないマクロパッケージは、 m をつけて表されることがよくありました。例えば、 tmac.doc に対応するパッケージは、 mdoc と呼ばれました。なぜなら、このパッケージをアクティブにするためのコマンドラインは、次のように表されるからです。

: troff -m doc

現在の groff(1) のバージョンでは、パッケージ名に m が付こうが付くまいが、この悩ましいマクロパッケージの名称付け体系をどちらも提供しています。ですので、 groff では、 man マクロパッケージは、次のいずれでも指定可能です。

: groff -m man
groff -m an
groff -m man
groff -m an

システムでどのマクロパッケージが利用可能であるかを判別するのに最も簡単な方法は、 tmac ディレクトリ群の中身を調べることです。例えば、 tmac.anything または anything.tmac と呼ばれるファイルは、 anything という名前のマクロパッケージを決定しています。

groff では、マクロパッケージの大部分は、古くからあるパッケージに対して m を先頭に付けた groff_<name>(7) という名前のマニュアルページで説明がされています。

取り込み

ドキュメント中でマクロパッケージを使うための方法はいくつかあります。実行時に、groff のオプション -m name を用いてマクロファイル name.tmac 内の定義を 名称付け のセクションで述べたように利用可能にします。このファイルが見付からない場合、 tmac.name が探されます。

groff リクエスト .so あるいは .mso を用いてマクロファイルをドキュメントに取り込むことも可能です。 .so については、マクロファイルのフルパスでのファイル名を指定しなくてはいけません --- そのマクロファイルが保存されているディレクトリを含む必要があります。マクロファイルが tmac ディレクトリ群のどれか 1 つに格納されている場合、代わりに .mso を使用するほうが便利です。なぜなら、このリクエストは tmac パスを探索してファイル名を見つけるからです。更に、インクルードされるファイルの名前が name.tmac という書式の場合でこれが見付からない場合、 .mso は代りに tmac.name をオープンしようとします。また、この逆も行います。

.so および .mso リクエストを解決するために、roff プリプロセッサが呼ばれなくてはならないことに注意してください。ただし、インクルードされるファイルが前処理が必要な場合に限ります。これは、コマンドライン上でパイプラインから直接呼ぶか、またはの -s オプションを使うかすればできます。

約束事 のセクションで述べているように、プリプロセッサワード中に文字 s を入れても良いです。

例えば、マクロファイルが /usr/share/tmac/macros.tmac に保存されており、 docu.roff という名前のドキュメントで使用されているとします。

実行時において、このドキュメントに対するフォーマッタ呼び出しは次のように行います。

: macros docu.roff

ドキュメント内に直接マクロファイルを取り込むには、

: .mso macros.tmac

あるいは

: .so /usr/share/tmac/macros.tmac

を使用します。

どちらの場合でも、フォーマッタは

: groff -s docu.roff

を使用して呼び出されます。

約束事

最近の roff 清書システムの多くでサポートされている約束事があります。次に述べられているような プリプロセッサワード がそれです。

ドキュメントの 1 行目がコメントである場合、最初の単語 (コメント文字および空白の後) は プリプロセッサ ワード で構成されます。これはつまり、このワードの文字が、ドキュメントを整形する際に起動しなくてはならないプリプロセッサコマンドの省略形であると解釈されるということです。ほとんどの場合、プリプロセッサのオプションに対応した文字だけが認識されます。それは、 e , G , g , p , R , s , t です ( roff(7) を参照)。

さらに、ユーザへの良き忘備録として書いておきますが、フォーマッタによっては ( man(1) プログラムのように) プリプロセッサワードで指定されたプリプロセッサを自動的に起動させることまでもできるものがあります。ただし、このことをあてにしてはいけません。

マクロファイルを記述する

マクロファイルを記述するのは簡単です。マクロ、文字列、レジスタなどのセットを設計してください。そしてそれを 1 つのファイルに保存してください。記述したマクロを使用するドキュメントは、 取り込み セクションで述べたように .so リクエストを使ってマクロを取り込みます。

tmac の機能を使用するには、マクロファイル whatever.tmac (または tmac.whatever) を呼び出し、tmac パスのどれかのディレクトリにファイルを置きます。 関連ファイル セクションを参照してください。そうすると、ドキュメントは 取り込み セクションで述べたように .mso リクエストあるいはオプションを使ってマクロファイルを取り込むことができます。

もしあなたが書いたマクロが一般用途に使えるかもしれないものなら、 groff メンテナに連絡を取って、そのマクロが groff の contrib ソースディレクトリに含まれるようにしてください。

マクロを書く際には、いくつか一般的なガイドラインがあれば役に立つでしょう。

機能のあるバックスラッシュはすべて 2 重にします。 \ -> \\
印字可能なバックスラッシュはすべて \e というように書かなくてはなりません。
ドットはすべてエスケープしてください。 . -> \.
テキスト部分には、印字できない文字 \& を広く使用するようにしてください。特に、 \ の前や行頭で使用してください。ただし、遅延コマンドの前では使用しないでください。
文字 @ を一時的な変数名に使用してください。
あなたが書いたマクロをテキストおよびグラフィックデバイスに対してテストしてください。例えば、 latin1 と ps がそうです。

環境変数

GROFF_TMAC_PATH: コロン区切りの追加の tmac ディレクトリリストであり、このリストからマクロファイルを探します。詳細については、前の節を参照してください。

バグ

groff ドキュメントは、現在発展中です。一時的に他のドキュメントとの間で小さな食い違いができてしまう可能性があります。

作者

このドキュメントは groff、すなわち GNU roff 配布物の一部です。このドキュメントは Bernd Warken <[email protected]> が書きました。

このドキュメントは FDL (GNU Free Documentation License) バージョン 1.1 以降の条項のもとで配布されています。お使いのシステムには FDL のコピーがあるはずです。また、

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

からオンラインでも入手可能です。

解説

名称付け

取り込み

約束事

マクロファイルを記述する

関連ファイル

環境変数

バグ

作者

翻訳

参照

最後に検索