名称

groff - groff ドキュメントフォーマットシステムのフロントエンド

書式

[ file

|

| [ option

コマンドラインは、GNU の慣習にしたがって解析されます。コマンドラインオプションとその引数との間の空白は、省略可能です。オプションは、1 つの (マイナス符号) の後にまとめて記述して構いません。ファイル名として (マイナス符号) を指定した場合、標準入力を表します。

解説

この文書は、 groff ドキュメントフォーマットシステムの主要フロントエンドプログラムである groff プログラムについて記述してあります。 groff プログラムとマクロスイートは、フリーソフトウェアコレクションに含まれる、 roff(7) システムの実装です。 groff システムは、古典的な roff の持つすべての特徴を持ち、さらに多くの拡張が追加されています。

groff プログラムによって、 groff システム全体をコマンドラインオプションで制御することができます。これは、(パイプのみを使用していた) 古典的なものに比べ、とても単純化したものとなっています。

オプション

groff は troff へのラッパプログラムなので、両方のプログラムはオプションの集合を共有します。しかし groff プログラムには、いくつかネイティブオプションが追加されており、またいくつかの troff オプションには新しい意味が与えられています。また逆に、 troff オプションのすべてが groff へ与えられるわけではありません、

ネイティブ groff オプション

以下のオプションは、 troff には存在しないか、 groff によって異なった解釈をされるものです。

: eqn を使って前処理を行います。

: grn を使って前処理を行います。

: grap を使って前処理を行います。

: ヘルプメッセージを表示します。

: このオプションは、(コマンドラインと .psbb と .so リクエストと \X'ps: import' と \X'ps: file' エスケーブで指定される両方の) ファイルを検索するためのディレクトリを指定するために使用されます。カレントディレクトリは常に最初に検索されます。このオプションは 2 つ以上指定できます。ディレクトリは、指定された順序で検索されます。絶対パスを使用して指定されたファイルでは、ディレクトリ検索を実行しません。このオプションはオプションを暗黙的に指定します。

: 印刷のために、出力をスプーラプログラムに送ります。これに使われるコマンドは、デバイス記述ファイルの print コマンドによって指定されます。デバイス記述ファイルについては、 groff_font(5) を参照して下さい。このコマンドが存在しない場合、デフォルトで出力は lpr(1) プログラムへパイプされます。オプションとを参照してください。

: arg をスプーラプログラムへ渡します。複数の引数は、それぞれ別のオプションで渡す必要があります。 groff は、引数をスプーラプログラムに渡す際に、 arg の前に (マイナス符号) をつけたりしないことに注意してください。

: eqn の区切り文字間に改行が入ることを禁止します。これは eqn のオプションと同様です。

: pic を使って前処理を行います。

: 後処理プログラムへ -option もしくは -option arg を渡します。オプションには、必要なマイナス符号やを前につけて指定しなければなりません。というのも、groff は、いかなるダッシュも前につけて後処理プログラムに渡したりしないからです。例えば、gxditview 後処理プログラムにタイトルを渡す場合、シェルコマンド

: は、次と同等です。

: refer を使って前処理を行います。 refer に引数を渡す仕組みは提供されていません。というのも、ほとんどの refer オプションには、文書中で指定できる等価な言語要素があるからです。詳細は refer(1) を参照してください。

: soelim を使って前処理を行います。

: より安全なモード。オプションを pic に渡し、次の troff リクエストを無効化します: .open, .opena, .pso, .sy, .pi。セキュリティ上の理由から、安全なモードはデフォルトで有効です。

: tbl を使って前処理を行います。

: 出力デバイスを dev に設定します。このデバイスに、 troff は、中間出力を生成します。 groff_out(5) を参照してください。次に、 groff は、 troff の 中間出力 を最終的な形式に変換するために後処理を呼び出します。 groff の実デバイスは次の通りです。

dvi: TeX DVI フォーマット (後処理プログラムは grodvi です)。

html: HTML 出力 (前処理プログラムは soelim と pre-grohtml で、後処理プログラムは post-grohtml です)。

lbp: Canon CAPSL プリンタ (LBP-4 と LBP-8 のシリーズのレーザプリンタ。後処理プログラムは grolbp です)。

lj4: HP LaserJet4 互換 (または他の PCL5 互換) プリンタ (後処理プログラムは grolj4 です)。

ps: PostScript 出力 (後処理プログラムは grops です)。

: 下記の TTY 出力デバイス (後処理プログラムは常に grotty です) に対しては、が出力エンコードを選択します:

ascii: 7 ビット ASCII。

cp1047: EBCDIC ホスト用の Latin-1 文字集合。

latin1: ISO 8859-1。

utf8: UTF-8 エンコードの Unicode 文字集合。

: 下記の引数は gxditview を `後処理プログラム' として選択します (これはどちらかというと閲覧プログラムですが):

X75: 75dpi 解像度の 10pt 文書ベースフォント。

X75-12: 75dpi 解像度の 12pt 文書ベースフォント。

X100: 100dpi 解像度の 10pt 文書ベースフォント。

X100-12: 100dpi 解像度の 12pt 文書ベースフォント。

: デフォルトのデバイスは ps です。

: 安全でないモード。 (古い) 安全でない動作に戻します。オプションを参照してください。

: groff と、groff から起動されるすべてのプログラムのバージョン情報を出力します。つまり、指定されたコマンドラインは通常どおりに解析され、すべてのサブプログラムにを渡します。

: (ラッパプログラムとして) groff によって実行されるパイプラインを標準出力に出力しますが、それは実行されません。 2 度以上を与えるなら、コマンドは、標準エラーに印刷 (表示) して実行します。

: 通常の後処理プログラムの代りに、 gxditview を起動して文書をプレビューします。オプションとで指定されたプリンタスプーラの動作は、 gxditview(1) の -printCommand オプションへの引数によって gxditview(1) へと渡されます。これによって、デフォルトの Print アクションと対応するメニューエントリとが、その値へと設定されます。は、が指定された時のみ、よい結果を生成します。の出力をプレビューする時のデフォルト解像度は 75dpi です。これは、オプションを gxditview に渡すことで変更可能です。例えば以下のようにします。

: troff からの出力を捨てます。エラーメッセージのみが表示されます。

: 標準出力に groff 中間出力 を印刷 (出力) します。 groff_out(5) を参照してください。通常、 groff は自動的に後処理をを呼び出します。このオプションにより、デバイスのための troff の出力、いわゆる 中間出力 は後処理なしで出力されます。

透過オプション

以下のオプションは、groff から引き続いて呼ばれるフォーマットプログラム troff へと、透過的に引き継がれます。これらのオプションの詳しいことは、 troff(1) で説明されています。

: ASCII 文字のみの近似的な出力を行います。

: エラーや警告をバックトレースします。

: カラー出力を無効にします。より詳しい情報については、 grotty(1) マニュアルページを調べてください。

: 互換モードを有効にします。

: 文字列を定義します。

: troff のエラーメッセージを無効にします。

: デフォルトのフォントファミリを設定します。

: フォントファイルと DESC ファイルへのパスを設定します。

: 指定された入力ファイルの後に、標準入力を処理します。

: マクロファイル name .tmac (もしくは tmac. name) を取り込みます。 groff_tmac(5) も参照してください。

: マクロファイルへのパスです。

: 最初のページを num とします。

: list 中のページのみ出力します。

: 数値レジスタを設定します。

: 警告 name を有効にします。

: 警告 name を無効にします。

GROFF の使用法

groff システム は、古典的な roff のインフラストラクチャを実装しています。一般的に roff システムがどのように動作しているかを調べるには、 roff(7) を参照してください。 groff システムにはフロントエンドプログラムが備わっているために、 groff の使用は、 古典的な roff に比べてとても容易となっています。この節では、groff システムの構成部分について概観します。これは、groff に特化した機能とともに roff(7) を補完するものです。この節は、groff システムまわりの文書へのガイドと見ることもできます。

ペーパサイズ

入力を書式設定 (フォーマット) するために troff によって使用される仮想のペーバサイズは、リクエスト .po, .pl と .ll で全体的に制御されます。便利なインタフェースを提供する `papersize' マクロパッケージについては groff_tmac(5) を参照してください。

用紙の実際の寸法である、 物理的な ペーパサイズは、コマンドラインオプションの -p と -l で grops のような出力デバイスによって制御されます。より詳しい情報については groff_font(5) と出力デバイスのマニュアルページを参照してください。 groff は、オプションを出力デバイスに渡すためにコマンドラインオプション -P を使用します。例えば、次は PS デバイスに対して横方向で A4 紙を選択します:

groff -Tps -P-pa4 -P-l ...

フロントエンド

groff プログラムは、 troff(1) プログラムを包むラッパです。これによって、コマンドラインオプションからプリプロセッサを指定することができ、また指定されたデバイスに適した後処理プログラムを自動的に実行することができます。このようにすることで、たまに長々となる古典的な roff(7) のパイプ機構を避けることができます。

grog(1) プログラムは、ファイルをフォーマットするための適切な groff のコマンドラインを推測するのに使われます。

groffer(1) プログラムは、groff ファイルやマニュアルページ用のオールラウンドのビューアです。

プリプロセッサ

groff のプリプロセッサは、古典的なプリプロセッサに適度な拡張を施して再実装したものです。 groff パッケージで配布されているプリプロセッサは以下です:

eqn(1): は、数学の式用。

grn(1): は、 gremlin(1) 図の取り込み用。

pic(1): は、作図用。

refer(1): は、参考文献目録用。

soelim(1): は、標準位置からのマクロファイル取り込み用。

tbl(1): は、表作成用。

これらの他にも、いくつかの内部的なプリプロセッサがあり、いくつかのデバイスに対して自動的に実行されます。これらは、ユーザからは認識できません。

マクロパッケージ

オプションによって、マクロパッケージを取り込めます。 groff システムでは、古典的なすべてのマクロパッケージを互換性を保った形で拡張して実装し、さらにいくつかの独自のパッケージを追加しています。実際には、以下のマクロパッケージが groff に付属しています:

man: 伝統的なマニュアルページ形式。 groff_man(7) を参照してください。これは、コマンドラインからもしくは man のように指定できます。

mandoc: マニュアルページ用の一般的なパッケージです。文書に man 形式か mdoc 形式が使用されているかどうかは自動的に見分けられ、対応するマクロパッケージに分岐します。これは、コマンドラインからもしくは mandoc のように指定できます。

mdoc: BSD スタイルのマニュアルページ形式です。 groff_mdoc(7) を参照してください。これは、コマンドラインからもしくは mdoc のように指定できます。

me: 古典的な me 文書形式です。 groff_me(7) を参照してください。これは、コマンドラインからもしくは me のように指定できます。

mm: 古典的な mm 文書形式です。 groff_mm(7) を参照してください。これは、コマンドラインからもしくは mm のように指定できます。

ms: 古典的な ms 文書形式です。 groff_ms(7) を参照してください。これは、コマンドラインからもしくは ms のように指定できます。

www: 任意の groff 文書に含めるための HTML に似たマクロです。 groff_www(7) を参照してください。

マクロファイルの命名やそれらの場所についての詳細は、 groff_tmac(5) に書かれています。また、このマニュアルページには、ここで記述されなかった他のいくつかのマイナな補助的マクロパッケージも文書化しています。

プログラミング言語

すべての roff プログラミング言語に共通する一般的な概念は、 roff(7) に記述があります。

古典的な troff 言語に対する groff 拡張については、 groff_diff(7) に文書化されています。

groff 言語の全体は、(未だ不完全ですが) groff info ファイル に記述されています。簡潔な (しかし完全な) リファレンスは、 groff(7) に書かれています。

フォーマッタ

groff システムに含まれている中心的な roff フォーマッタは、 troff(1) です。これは、古典的な troff と nroff の両方の特徴に加え、 groff 拡張も備えています。コマンドラインオプションによって、古典的な roff をできるだけエミュレートしようとする 互換モード に、 troff を切り替えることができます。

古典的な nroff の動作をエミュレートするシェルスクリプト nroff(1) もあります。これは、現在のロケールにしたがって、自動的に適切な出力エンコーディングを選択しようと試みます。

フォーマッタプログラムは、 中間出力 を生成します。 groff_out(7) を参照してください。

デバイス

roff では、出力ターゲットを デバイス と呼びます。デバイスは、プリンタのようなハードウェアの一部であることもあれば、ソフトウェアのファイル形式であることもあります。デバイスはオプションで指定します。 groff のデバイスは以下の通りです:

ascii: ascii(7) 文字集合を用いたテキスト出力。

cp1047: EBCDIC コードページの IBM cp1047 を用いたテキスト出力 (例えば OS/390 Unix)。

dvi: TeX の DVI 形式。

html: HTML 出力。

latin1: ISO Latin-1 (ISO 8859-1) 文字集合を用いたテキスト出力。 iso_8859_1(7) を参照してください。

koi8-r: ロシア語の KOI8-R 文字集合を用いたテキスト出力。

lbp: Canon CAPSL プリンタ用出力 (LBP-4 と LBP-8 シリーズのレーザプリンタ)。

lj4: HP LaserJet4 互換 (または他の PCL5 互換) プリンタ。

ps: PostScript 出力。プリンタや gv(1) のようなプレビュアに適しています。

utf8: UTF-8 エンコードした Unicode (ISO 10646) 文字集合を用いたテキスト出力。 unicode(7) を参照してください。

X75: xditview(1x) や gxditview(1) のようなプレビュアに適した、75dpi の X Window System 出力。 12pt 文書のベースフォント用は X75-12 です。

X100: xditview(1x) や gxditview(1) のようなプレビュアに適した、100dpi の X Window System 出力。 12pt 文書のベースフォント用は X100-12 です。

デバイスに対して使用される後処理プログラムは、デバイス記述ファイル中の postpro コマンドで指定されます。 groff_font(5) を参照してください。これは -X オプションで上書きされます。

デフォルトのデバイスは ps です。

後処理プログラム

groff は 3 つのハードウェア用後処理プログラムを備えています:

grolbp(1): いくつかの Canon プリンタ用。

grolj4(1): HP LaserJet 4 互換と PCL5 互換プリンタ用。

grotty(1): さまざまなエンコーディングのテキスト出力用。例えばテキスト指向端末やラインプリンタなど。

現在では、ほとんどの印刷や描画ハードウェアはオペレーティングシステムやデバイスドライバ、ソフトウェアインタフェースによって扱われているため、通常 PostScript を受け付けます。したがって、さらに多くのハードウェアデバイス用後処理プログラムに対する差し迫った要求はないでしょう。

他の文書ファイル形式へ変換する groff ソフトウェアデバイスは以下です:

grodvi(1): DVI 形式用。

grohtml(1): HTML 形式用。

grops(1): PostScript 用。

多数存在するフリーの変換ツールと組み合わせることで、troff 文書を事実上存在するどんなデータ形式へと変換するのにも、これで十分でしょう。

ユーティリティ

groff まわりの以下のユーティリティが利用可能です。

addftinfo(1): groff とともに使う troff のフォント記述ファイルへ情報を追加します。

afmtodit(1): PostScript デバイス用のフォント記述ファイルを作成します。

groffer(1): groff ファイルとマニュアルページ用の一般的なビューアプログラム。

gxditview(1): groff の X ビューア。 GNU 版の xditview です。

hpftodit(1): lj4 デバイス用のフォント記述ファイルを作成します。

indxbib(1): 文献目録データベースの逆引きインデックスを作成します。

lkbib(1): 文献目録データベースを検索します。

lookbib(1): 文献目録データベースを対話的に検索します。

pfbtops(1): .pfb 形式の PostScript フォントを ASCII 形式に変換します。

tfmtodit(1): TeX DVI デバイス用のフォント記述ファイルを作成します。

xditview(1x): X window と一緒に配布されている roff ビューア。

環境変数

通常、以下の環境変数におけるパスの区切り文字はコロンですが、これはオペレーティングシステムに依存して変わります。例えば、DOS や Windows では代わりにセミコロンを使用します。

GROFF_BIN_PATH: この検索パスは $PATH の前に置かれ、 groff が起動するコマンドのために使用されます。これが設定されていない場合、groff のバイナリがインストールされたディレクトリが PATH の前に追加されます。

GROFF_COMMAND_PREFIX: 同時に別の roff の実装を実行する必要のある場合に備えて、 groff には、実行時に名前の衝突を引き起こす可能性のあるプログラムのほとんどにプレフィックスをつける機能が備わっています (デフォルトではつきません)。歴史的にこのプレフィックスは文字 g でしたが、これはなんでも構いません。例えば、 gtroff は groff の troff を表しており、 gtbl は tbl の groff 版です。 GROFF_COMMAND_PREFIX を異なる値に設定することで、別にインストールした roff を指定することができます。もっと正確に言うと、プレフィックス xxx が設定された場合、ラッパプログラムである groff は troff の代わりに xxx troff を内部的に呼び出します。これは以下のプリプロセッサにも適用されます: eqn, grn, pic, refer, tbl, soelim。そして次のユーティリティにも適用されます: indxbib および lookbib。この機能は、上にあげたもの以外のプログラムには適用されません (特に groff 自身にも)。というのも、それらは groff パッケージ独自のものだからです。

GROFF_FONT_PATH: デフォルトのリストに加えて、 dev name ディレクトリを検索するためのディレクトリのリストです。詳細は troff(1) と groff_font(5) を参照してください。

GROFF_TMAC_PATH: デフォルトのリストに加えて、マクロファイルを検索するためのディレクトリのリストです。詳細は troff(1) と groff_tmac(5) を参照してください。

GROFF_TMPDIR: 一時的なファイルが作成されるディレクトリです。これが設定されておらず、代わりに環境変数 TMPDIR が設定されていた場合は、一時ファイルはディレクトリ $TMPDIR に作成されます。また、MS-DOS と Windows 32 プラットフォームでは、環境変数 TMP と TEMP は、 GROFF_TMPDIR と TMPDIR の後に、(その順序で) 検索されます。それ以外の場合、一時ファイルは /tmp に作成されます。 refer(1), groffer(1), grohtml(1), grops(1) コマンドが一時ファイルを使用します。

GROFF_TYPESETTER: デフォルトのデバイスをあらかじめ設定します。これが設定されていない場合は、デフォルトで ps デバイスが使用されます。このデバイス名は、オプションで上書きされます。

使用例

以下の例は、 troff を包むラッパである groff プログラムの能力を説明するものです。

プリプロセッサ tbl と pic を用い、 me マクロセットを使って roff ファイルを処理するには、古典的な troff では以下のように呼び出さねばなりませんでした。

groff を使うと、このパイプを以下のような等価なコマンドへと短くすることができます。

これを呼び出すさらに簡単な方法は、 grog(1) を用いてプリプロセッサとマクロオプションを推測し、生成されたコマンドを実行することです (バッククォートを使用して、シェルコマンド置換を指定します)。

最も単純な方法は、以下を呼び出して自動化された方法で内容を見ることです。

バグ

EBCDIC ホスト (例えば OS/390 Unix) 上では、出力デバイス ascii と latin1 は利用できません。同様に、EBCDIC コードページ cp1047 用の出力は、ASCII ベースのオペレーティングシステムでは利用できません。

バグレポートは、bug-groff@gnu.org までお願いします。レポートの際にはバグを再現できる完全な例題を添付し、あなたの利用している groff のバージョンを添えて下さい。

入手性

groff の入手方法や関連情報は、から入手できます。もっとも最近リリースされたバージョンの groff は、から anonymous ftp で入手できます。

3 つの groff メーリングリストが利用できます:

は、バグレポート用です。

は、groff に関する一般的な議論用です。

は、CVS リポジトリへのコミットログを流す、投稿不可のメーリングリストです。

CVS でのアクセスやそれ以上の詳細は、 groff のソースパッケージのトップディレクトリにある README ファイルに書かれています。

grap プリプロセッサのフリーの実装があります。これはによって書かれました。実際のバージョンはにあります。これは、groff でサポートされている唯一の grap です。

作者

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

この文書は、によって書かれたオリジナルの groff のマニュアルページに基づいています。これは、 Bernd Warken によって書き直され、書き足され、FDL ライセンスに変更されました。これは、によって保守されています。

groff は、GNU のフリーソフトウェアプロジェクトです。 groff パッケージ 全体は、GNU のコピーレフトライセンスによって保護されています。ソフトウェアのファイルは GNU General Public License (GPL) の下で配布されており、ほとんどの文書ファイルには GNU Free Documentation License (FDL) が使用されています。

YOS OPENSONAR

名称

書式

解説