GROFF_TMAC

名称
解説
GROFF マクロパッケージ
名称付け
取り込み
マクロの記述
関連ファイル
環境変数
作者
関連項目

名称

groff_tmac − roff 清書システム内にあるマクロファイル

解説

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

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

GROFF マクロパッケージ

groff は、すべての古典マクロパッケージ、いくつかの完全パッケージ、そしていくつかの特殊な用途の補助パッケージを提供しています。主要なマクロパッケージは同時に複数個使用できないことに注意してください。例えば

sh# groff −m man −m ms foo

や

sh# groff −m man foo −m ms bar

は失敗します。

man ページ

	man		UNIX マニュアルページ (man ページ) 用の古典マクロパッケージです。これはとても便利で使いやすいものです。 groff_man(7) を参照してください。
	doc
	mdoc		man ページ用のもう 1 つのマクロパッケージで、主に BSD システムで使用されています。これはたくさんの新しい機能を提供していますが、 man ページの標準ではありません。 groff_mdoc(7) を参照してください。

完全パッケージ

この節のパッケージは、どのような種類の文書 (本をまるごとでさえ) も執筆できる完全なマクロの組を提供します。これらは機能的には類似しています。どれを使用するかは、好みの問題です。

	me		古典的な me マクロパッケージです。 groff_me(7) を参照してください。
	mm		半古典的な mm マクロパッケージです。 groff_mm(7) を参照してください。
	mom		新しい mom マクロパッケージです。これは groff でのみ利用できます。これは他のパッケージを元にしていないため、自由に設計することができます。したがって、これは非常によい、現代的なマクロパッケージになると期待されています。 groff_mom(7) を参照してください。
	ms		古典的な ms マクロパッケージです。 groff_ms(7) を参照してください。

特殊パッケージ

この節のマクロパッケージは、単独で使用するように意図されたものではなく、他のマクロパッケージや素の groff に特殊な機能を追加するために使用されるものです。

papersize

このマクロファイルは既に起動時に troff が読み込み済なので、明示的に呼び出す必要はありません。コマンドラインオプション −dpaper=size で用紙サイズを設定するインタフェースを提供しています。 size に指定可能な値は、DESC ファイルでの定義済の papersize 値 (小文字だけです。詳細は groff_font(5) を参照してください) ですが a7-d7 は指定できません。文字 l (エル) を後に付けると、ランドスケープの向きを意味します。例: a4, c3l, letterl 。

ドライバ固有の DESC ファイルのデフォルト用紙長や向きに優先させるためには、ほとんどの出力ドライバで追加のコマンドラインスイッチ −p および −l が必要となります。例えば、ランドスケープの向きの A4 用紙に PS 出力を行う場合次のようにします:

sh# groff −Tps −dpaper=a4l −P−pa4 −P−l −ms foo.ms > foo.ps

pspic

このマクロでは、PostScript 画像を文書に取り込むために、1 個のマクロ PSPIC が提供されています。 PS 画像の取り込みをサポートする出力デバイス −Tps, −Tdvi, −Thtml でのみ意味があります。ファイルは自動的にロードされます。構文:

.PSPIC [−L|-R|−I n] file [width [height]]

file は画像を含むファイルの名前、 width と height は画像の望みの幅と高さです。 width と height の引数には、スケール指示子を付けられます。デフォルトのスケール指示子は i です。このマクロは、x および y 方向に画像を一様にスケールしますので、画像は幅 width も高さ height も越えません。デフォルトで、画像は水平位置の中央に置かれます。 −L および −R のオプションは、それぞれ画像を左寄せおよび右寄せにします。 −I オプションは、画像を n だけインデントします (デフォルトのスケール指示子は m です)。

tty-char

tty デバイス用に、troff の標準文字や groff のいくつかの文字の定義を上書きします。貧弱な機器で処理できるようにするため、通常の tty 形式のものと比べて、見た目を意図的に落しています。

www

インターネット (World Wide Web) ページで使用されている HTML フォーマットで知られている要素を追加します。これには URL リンクやメールアドレスが含まれます。 groff_www(7) を参照してください。

名称付け

古くからある roff システムには、オプションを解釈する部分の過度に単純化された設計のせいで奇妙な名称付けの体系がありました。マクロパッケージは、常にオプション -m を用いて指定されていました。このオプションの後に、区切りの空白もなしに直接引数が続くと、 1 つのマイナスに続く長い名前のオプションに見えます。これは、コンピュータの石器時代には驚くべきことでした。これをマクロパッケージの名前に対して実際に動くようにするため、すべての古典的なマクロパッケージには ‘m’ の文字で始まる名前がつけられており、この文字はマクロファイルの名前からは省略されていました。

例えば、man ページ用のマクロパッケージは man と呼ばれますが、このマクロファイルは tmac.an でした。したがって、これは引数 an をオプション -m に指定すること、もしくは短く -man と指定することで有効にできました。

同様の理由で、 ‘m’ で始まらないマクロパッケージには、文書化の際や会話において、先頭に ‘m’ が付けられていました。例えば、 tmac.doc に対応するパッケージでは、より適切な名前は doc であるのに関わらず、文書中では mdoc と呼ばれていました。なぜなら、オプションとその引数との間の空白を省略すると、このパッケージを有効にするコマンドラインオプションは -mdoc と表されるからです。

すべての状況に対処するため、現在のバージョンの groff(1) では、この虐げられてきたマクロパッケージに対して、先頭に ‘m’ が付くものと付かないものの 2 つのマクロファイルを提供することによって、両方の名称付け体系をうまく扱うことができます。したがって groff では、 man マクロパッケージは以下の 4 つの方法のうちの 1 つで指定することができます:

sh# groff −m man

sh# groff −man

sh# groff −mman

sh# groff −m an

最近のパッケージで ‘m’ で始まらないものは、文書化の際に追加の ‘m’ を使用しません。例えば、 www マクロパッケージは次の 2 つの方法のうちの 1 つのみで指定できます:

sh# groff −m www

sh# groff −mwww

明らかに -mmwww のようなものは意味をなしません。

古典的な troff の持つ 2 番目の奇妙な特徴は、マクロファイルに tmac.name のような名前を付けることです。現代的なオペレーティングシステムでは、ファイルの種類は接尾辞、つまりファイル名の拡張子によって指定されます。先ほどと同様に、groff は、 anything のみが指定された場合 anything.tmac と tmac.anything のどちらも検索することによって、この状況に対処します。

システムでどのマクロパッケージが利用可能であるかを調べる最も簡単な方法は、 man ページ groff(1) 、もしくは tmac ディレクトリの内容を確認することです。

groff では、マクロパッケージのほとんどは groff_name(7) という man ページで説明されています。古典的パッケージについては、先頭に ‘m’ がついています。

取り込み

文書中でマクロパッケージを使用する方法はいくつかあります。古典的な方法は、実行時に troff/groff のオプション −m name を指定することです。これによってマクロパッケージ name の内容が有効になります。 groff では、ファイル name.tmac は tmac パス内で検索されます。見つからなかった場合、代わりに tmac.name が検索されます。

別の方法として、文書中にリクエスト .so filename を追加することによって、マクロファイルを取り込むこともできます。引数は、存在するファイルの完全なファイル名でなくてはなりません。つまり、そのファイルのあるディレクトリをつけることが、おそらく必要です。 groff では、これは同様のリクエスト .mso package によって改善されました。これは、オプション -m がするように、tmac パス内を検索します。

取り込まれるファイルに前処理が必要な場合、 .so や .mso リクエストを解決するために、 roff プリプロセッサ soelim(1) が、呼び出される必要があることに注意してください。これは、直接コマンドライン上のパイプラインで、もしくは troff/groff オプション −s のどちらでも行うことができます。 man は、soelim を自動的に呼び出します。

例えば、マクロファイルが /usr/share/tmac/macros.tmac に保存されており、 docu.roff と呼ばれる文書で使われるとします。

実行時において、この文書に対するフォーマッタの呼び出しは次のようになります。

sh# groff −m macrofile document.roff

文書内にマクロファイルを直接取り込むには、

.mso macrofile.tmac

あるいは

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

を使用します。

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

sh# groff −s docu.roff

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

もし独自の groff マクロファイルを書きたい場合には、それを whatever.tmac と名付けて tmac パスのどこかのディレクトリに置くとよいでしょう。 FILES を参照してください。すると文書は、それを .mso リクエスト、もしくはオプション -m を使用して取り込むことができます。

マクロの記述

roff(7) 文書は、リクエストやエスケープシーケンス、文字列、数値レジスタ、マクロパッケージのマクロなどの定義済みフォーマット構造によって拡充されたテキストファイルです。これらの要素は roff(7) に説明されています。

文書を個人的なスタイルにしたい場合は、繰り返し行われることに対してマクロを定義して、既存の要素を拡張するのが最も役に立ちます。これを行うのは、文書の最初に近いところ、もしくは別のファイルにするのが最もよいでしょう。

引数のないマクロは、ちょうど文字列のようなものです。しかしマクロの本当の力は、マクロ呼び出しに引数が渡された時に現れます。マクロ定義内では、引数は次のエスケープシーケンスとして利用することができます: $1, ..., $9, $[...], $*, $@ 。マクロが呼び出された時のマクロ名は $0 に格納され、引数の数はレジスタ 0 に格納されています。 groff(7) を参照してください。

コピーイン (copy-in) モード

groff がマクロを読む込むフェーズを、roff ではコピーインモードと言います。これは、C 言語でプログラムを開発する時の C プリプロセッサが処理を行うフェーズに似ています。

このフェーズでは、groff はすべてのバックスラッシュを解釈します。これは、マクロ本体のすべてのエスケープシーケンスが解釈され、それぞれの値に置き換えられることを意味します。変化しない表現であれば、これは望まれた動作ですが、マクロ呼び出しのたびに変化するかもしれない文字列やレジスタは、値を評価しないように保護しなくてはなりません。これは、エスケープシーケンスの先頭にあるバックスラッシュを二重にすることでとても容易に行うことができます。位置パラメータにとって、この二重化は最も重要です。例として、マクロに渡された引数の情報を端末に表示するには、例えば以下のような ‘.print_args’ という名前のマクロを定義します。

       .ds midpart was called with
       .de print_args
       .  tm \f[I]\\$0\f[] \\*[midpart] \\n[.$] arguments:
       .  tm \\$*
       ..

このマクロが次のように呼ばれると、

       .print_args arg1 arg2

以下のようなテキストが端末に表示されます:

       print_args was called with the following 2 arguments:
       arg1 arg2

では、マクロ定義中の各バックスラッシュを解析してみましょう。位置パラメータと引数の数は、各マクロ呼び出しで変化するので、先頭のバックスラッシュは二重化しなければなりません。よって、 \\$* と \\[.$] となります。同様にマクロ名にもこれを適用します。なぜなら、別名で呼ばれるかも知れないからです。したがって、 \\$0 となります。

一方、 midpart は文字列定数であり変化しないので、 \*[midpart] は二重化しません。 \f エスケープシーケンスは、テキスト中のフォントを設定する定義済み groff 要素です。もちろん、この動作も変化しないので \f[I] と \f[] は二重化しません。

ドラフトモード

エスケープ機構を一時的に無効にすると、マクロを記述するのは簡単になります。 groff では、マクロ定義を .eo と .ec リクエストの組で囲むことで無効にすることができます。するとマクロ定義の本体は、通常の文書部分と同じようになります。ここで通常の文書部分とは、リクエストやマクロ、文字列、レジスタなどの呼び出しで拡張されたテキストのことです。例えば、上記のコードは以下のように簡単に書くことができます。

       .eo
       .ds midpart was called with
       .de print_args
       .  tm \f[I]\$0\f[] \*[midpart] \n[.$] arguments:
       .  tm \$*
       ..
       .ec

よくないことに、ドラフトモードは常に使えるわけではありません。これは通常のマクロを定義するには十分ですが、ドラフトモードは間接的に定義された文字列やレジスタなどの高度な応用には使えません。最もよい方法は、すべてのマクロをドラフトモードで定義してテストをし、そして最後の段階としてバックスラッシュを二重化することです。 .eo リクエストを外すのを忘れないようにしてください。

マクロ定義のための助言

•

すべての行をドットで始めるようにします。例えば、テキスト行に groff リクエスト .nop を使用したり、先頭がドットのテキスト行も扱うあなた独自のマクロを書きます。

.de Text
. if (\\n[.$] == 0) \
. return
. nop \)\\$*[rs]
..

•

コピーインモードでもドラフトモードでも動作するように、コメントマクロを記述するようにします。なぜなら、ドラフトモードではエスケープが無効になるので、通常のコメントが使用された時、問題が起こるかも知れないからです。例えば、以下のマクロは単に引数を無視するので、コメント行のように動作してしまいます。

.de c
..
.c This is like a comment line.

	•		長いマクロ定義中では、コメント行や構造化のための空行をたくさん使用するようにします。
	•		読みやすくするために、リクエストやマクロ呼び出しに対して groff のインデント機能を使用するようにします (先頭のドットの後に、任意の空白を置けます)。

転換 (diversion)

転換は、非常に高度なプログラミング構造を実現するために使用されます。これらは C プログラミング言語における大きなデータ構造へのポインタに似ていますが、その使用方法はとても異なっています。

過度に単純化された形式では、転換は複数行の文字列ですが、転換の能力は、それがマクロ中で動的に使用された時に現れます。転換内に保持された情報は、転換をちょうどマクロのように呼び出すことで取り出すことができます。

転換に関して起こるほとんどの問題は、転換は常に完全な行を扱うのだという事実を意識することで避けることができます。行バッファがフラッシュされてない時に転換が使用された場合、奇妙な結果が生成されます。このことを知らないと、多くの人が転換を使いものにならないと思ってしまいます。転換が動作することを保証するには、改行を適切な場所で入れることが必要です。安全のために、転換に関するものはすべて、1 対の改行の間に入れます。例えば、 .br リクエストを多用します。この規則は、転換の定義の中と外の両方、そしてすべての転換の呼び出しに適用するのがよいでしょう。これは少しやりすぎですが、これでちゃんと動作します。

[もし現在行の途中までを無視して転換を行う必要がある時には、現在行の途中までを保存するのに環境を使用するか、または .box リクエストを使用するか、もしくはこの両方を使用します]

転換の最も強力な特徴は、あるマクロ定義中で転換を開始し、他のマクロ中で転換を終えることです。すると、このマクロの組のそれぞれの呼び出しの間のすべてが転換に格納され、マクロ中で操作することができます。

環境変数

$GROFF_TMAC_PATH

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

作者

この文書は、FDL (GNU Free Documentation License) バージョン 1.1 かそれ以降のものに基づいて配布されています。あなたは、システム上に FDL のコピーを受け取っているはずですが、これは GNU copyleft siteからもオンラインでも入手可能です。

この文書は groff 、すなわち GNU roff 配布物の一部です。これは Bernd Warkenによって書かれ、 Werner Lembergによって保守されています。

	•	troff/groff の −M コマンドラインオプションで指定されたディレクトリ
	•	$GROFF_TMAC_PATH 環境変数で与えられたディレクトリ
	•	カレントディレクトリ (安全でないモードの時のみ。これは −U コマンドラインスイッチで有効になります)
	•	ホームディレクトリ
	•	プラットフォーム特有のディレクトリ。このインストールでは /usr/share/tmac です。
	•	サイト特有 (プラットフォーム非依存) のディレクトリ。このインストールでは /usr/share/tmac です。
	•	主要の tmac ディレクトリ。このインストールでは /usr/share/tmac です。

tmac(5)