スポンサーリンク

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 は画像を含むファイルの名前、 widthheight は画像の望みの 幅と高さです。 widthheight の引数には、スケール指示子を付 け ら れ ます。デフォルトのスケール指示子は 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.tmactmac.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 リクエストを使 用 す る か、もしくはこの両方を使用します]

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

関連ファイル

tmac の機構を完全に使用するためには、すべてのマクロの名前は name.tmac と名付けなければなりません。古典パッケージのように tmac.name も同様に可 能ですが、使用しない方がよいでしょう。

マ クロファイルは tmac ディレクトリに保持されています。 tmac パスは、こ れらのコロン区切りのリストで構成されます。

マクロファイルの検索手順は以下のように (この順で) 行われます:

troff/groff の −M コマンドラインオプションで指定されたディレク ト リ

$GROFF_TMAC_PATH 環境変数で与えられたディレクトリ

カレントディレクトリ (安全でないモードの時のみ。これは −U コマン ドラインスイッチで有効になります)

ホームディレクトリ

プラットフォーム特有のディレクトリ。 こ の イ ン ス トー ル で は /usr/share/tmac です。

サイト特有 (プラットフォーム非依存) のディレクトリ。このインス トールでは /usr/share/tmac です。

主要の tmac ディレクトリ。このインストールでは /usr/share/tmac で す。

環境変数

$GROFF_TMAC_PATH

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

作者

Copyright (C) 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

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

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

関連項目

groff システムのすべての部分の完全なリファレンスは、 groff info(1) ファ イル中にあります。

groff(1)

groff システムの全体像です。

groff_man(7),

groff_mdoc(7),

groff_me(7),

groff_mm(7),

groff_mom(7),

groff_ms(7),

groff_www(7).

groff tmac マクロパッケージです。

groff(7)

groff 言語です。

ファイルシステム階層標準 (FHS) は FHS web siteから入手可能です。

スポンサーリンク