Diff from 1.10.2.6 to 1.10.2.7

Submitted by:	Yuko Sasaki <yuko@veltec.co.jp>
Reviewed by:	OHSAWA Chitoshi <ohsawa@ccn.aitai.ne.jp>,
		Mori Kouji <mori@tri.asanuma.co.jp>

ja_JP.eucJP/man/man1/m4.1

@@ -1,9 +1,9 @@
-.\"
-.\"	@(#) %FreeBSD: src/usr.bin/m4/m4.1,v 1.10.2.6 2002/06/21 15:28:03 charnier Exp %
+.\"     @(#) $OpenBSD: m4.1,v 1.24 2002/04/18 18:57:23 espie Exp %
+.\" %FreeBSD: src/usr.bin/m4/m4.1,v 1.10.2.7 2002/07/15 02:06:15 jmallett Exp %
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 26, 1993
+.Dd April 17, 2002
 .Dt M4 1
 .Os
 .Sh 名称
@@ -11,107 +11,207 @@
 .Nd マクロ言語プロセッサ
 .Sh 書式
 .Nm
-.Op Fl s
-.Oo
-.Fl D Ar name Ns Op Ar =value
-.Oc
+.Op Fl d Ar flags
+.Op Fl t Ar name
+.Op Fl gs
+.Op Fl D Ar name Ns Op = Ns Ar value
 .Op Fl U Ar name
+.Op Fl I Ar dirname
 .Op Ar
 .Sh 解説
 .Nm
 ユーティリティは、さまざまな言語
 (たとえば C, ratfor, fortran, lex, yacc など) のフロントエンドとして
 利用できるマクロプロセッサです。
-引数で指定されたファイルが指定された順に処理されます。
-ファイルが指定されていないか、ファイル名が \`-\' なら
-標準入力が読まれます。処理されたテキストは標準出力へ送られます。
+.Nm
+は、標準入力から読み込みます。
+また、標準出力のプロセステキストへ書き出します。
 .Pp
-マクロの呼出しは name(argument1[, argument2, ...,] argumentN) の
+マクロの呼び出しは
+.Ic name Ns Pq Ar argument1 Ns Op , Ar argument2 , ... , argumentN
+の
 形式を取っています。
 .Pp
-マクロ名とそれに続く開き括弧 `(' との間にはスペースがあってはいけません。
-もしマクロ名の直後に開き括弧が続いていなければ引数なしのマクロ呼出しとして
+マクロ名とそれに続く開き括弧
+.Pq Ql \&(
+との間にはスペースがあってはいけません。
+もしマクロ名の直後に開き括弧が続いていなければ引数なしのマクロ呼び出しとして
 処理されます。
 .Pp
 マクロ名として先頭はアルファベットまたはアンダースコアが、2 文字目以降は
 英数字またはアンダースコアが使えます。
-よって正しいマクロ名にマッチする正規表現は [a-zA-Z_][a-zA-Z0-9_]*
+よって正しいマクロ名にマッチする正規表現は
+.Dq Li [a-zA-Z_][a-zA-Z0-9_]*
 となります。
 .Pp
 マクロの引数のうちで、先頭のクォートされていない空白、タブ、
-改行文字は無視されます。
+改行文字
+.Pq Ql \en
+は無視されます。
 文字列をクォートするためには、左、および右シングルクォートを使用して
-ください (例: ` this is a string with a leading space')。
-組み込みマクロ changequote を使ってクォート文字を変更することができます。
+ください (例: 
+.Sq "\ this is a string with a leading space" )
+。
+組み込みマクロ
+.Ic changequote
+を使ってクォート文字を変更することができます。
+.Pp
+大抵の組み込みマクロは、引数がないと意味をなしませんので、
+開き括弧が後に続かない場合、特別のものとして認識されません。
 .Pp
 オプションは以下の通りです:
-.Bl -tag -width "-Dname[=value]xxx"
+.Bl -tag -width indent
 .It Fl s
 .Xr cpp 1
 用に、
-.Em #line
+.Ic #line
 ディレクティブを出力します。
-.It Fl D Ar name Ns Oo
-.Ar =value
-.Oc
+.It Fl D Ar name Ns Op = Ns Ar value
 シンボル
 .Ar name
-の値を value (無指定時は NULL) と定義します。
-.It Fl "U" Ar "name"
+の値を value (無指定時は
+.Dv NULL ) と定義します。
+.It Fl U Ar name
 シンボル
 .Ar name
 を未定義にします。
+.It Fl I Ar dirname
+include パスを
+ディレクトリ
+.Ar dirname
+で追加します。
+.It Fl d Ar flags
+トレースフラグをセットします。
+.Ar flags
+引数は、以下の通りです:
+.Pp
+.Bl -tag -width indent -compact
+.It Cm a
+マクロの引数を表示します。
+.It Cm c
+マクロの展開を複数行で表示します。
+.It Cm e
+マクロの展開結果を表示します。
+.It Cm f
+ファイル名の場所を表示します。
+.It Cm l
+行数を表示します。
+.It Cm q
+引数と現在のクォートの結果を引用します。
+.It Cm t
+すべてのマクロをトレースします。
+.It Cm x
+マクロの展開の数です。
+.It Cm V
+すべてのオプションフラグをオンにします。
+.El
+.Pp
+デフォルトでは、トレースは
+.Cm eq
+にセットしています。
+.It Fl t Ar macro
+.Ar macro
+をトレーシングします。
+.It Fl g
+GNU-m4 互換モードを有効にします。
+このモードでは
+.Ic changequote
+に 2 つの空のパラメータをつけることで
+クォートの使用をやめられます。
+.Ic translit
+は、
+単一の文字範囲 (例えば
+.Li a-z )
+を扱い、
+正規表現で
+.Xr emacs 1
+のように動作します。
+変換の数は無制限です。
 .El
 .Sh 文法
 .Nm
 ユーティリティには以下に示す組み込みマクロが実装されています。
 これらのマクロは再定義可能であり、その場合には元の定義は失われます。
 特に記述のない限り戻り値は NULL です。
-.Bl -tag -width changequotexxx
-.It changecom
+.\" 原文 NULL -> null
+.Bl -tag -width ".Ic changequote"
+.It Ic builtin
+指定した組み込みマクロを呼び出します。再定義されている場合は無視します。
+組み込みがそれらの名前によって呼び出され、
+可能な再定義を無視します。
+.It Ic changecom
 コメントの開始文字列と終了文字列を変更します。
-デフォルトでは、ポンド記号 `#' と改行文字です。
-引数を指定しなかった場合はシーケンスがリセットされます。
+デフォルトでは、ポンド記号
+.Pq Ql #
+と改行文字です。
+引数を指定しなかった場合はコメントシーケンスがリセットされます。
+GNU モードの
+.Nm
+では、コメントはオフです。
 設定できる文字列の長さは最大で 5 文字です。
-.It changequote
+.It Ic changequote
 第 1、第 2 引数をクォートシンボルとして定義します。
-引数の最初の文字のみ使用されることに注意してください。
+シンボルは、長さ 5 文字以内にしてください。
 引数が与えられなかった場合にはデフォルトの左右シングルクォートに
 設定されます。
-.It decr
+.It Ic decr
 引数の値を 1 だけ減少させます。
 引数は正しく数値を表現する文字列でなければなりません。
-.It define
+.It Ic define
 第 1 引数で指定した名前の新しいマクロを定義します。
 定義内容は第 2 引数で与えます。
-定義中での $n (n は 0 から 9 まで) は それぞれそのマクロに与えられる
-第 n 引数に置換されます。$0 はマクロ名そのものです。
+定義中での
+.Sq Li $ Ns Ar n
+(
+.Ar n
+は 0 から 9 まで) は それぞれそのマクロに与えられる
+第
+.Ar n
+引数に置換されます。
+.Ql $0
+はマクロ名そのものです。
 指定されなかった引数は NULL 文字列に置換されます。
-また $# は引数の数を表し、$* はコンマで区切られた全引数になります。
-$@ は $* と同様ですが、更なる置換が行われないように全部の引数が
+.\" 原文 NULL -> null
+また
+.Ql $#
+は引数の数を表し、
+.Ql $*
+はコンマで区切られた全引数になります。
+.Ql $*
+は
+.Ql $*
+と同様ですが、更なる置換が行われないように全部の引数が
 クォートされます。
-.It defn
+.It Ic defn
 各引数で指定されたマクロの定義内容をクォートして返します。
 これはマクロ定義の名称変更 (組み込みマクロであっても) に利用できます。
-.It divert
+.It Ic divert
 .Nm
 には 10 本の出力キューが用意されています
 (0 から 9 までの番号がついています)。
 処理の最後に、全てのキューは番号順に連結されて最終的な出力を
 生成するようになっています。
 初期状態では出力キューは 0 番に設定されています。
-divert マクロを使って新しい出力キューを選ぶことが出来ます
-(divert に不正な引数を与えると出力が破棄されてしまいます)。
-.It divnum
+.Ic divert
+マクロを使って新しい出力キューを選ぶことが出来ます
+(
+.Ic divert
+に不正な引数を与えると出力が破棄されてしまいます)。
+.It Ic divnum
 現在の出力キューの番号を返します。
-.It dnl
+.It Ic dnl
 改行文字を含めた行末までの入力文字を破棄します。
-.It dumpdef
+.It Ic dumpdef
 引数で指定した項目に関して、その名前と定義を出力します。
 引数が与えられなかった場合は全てのマクロについて出力します。
-.It errprint
+.It Ic errprint
 第 1 引数を標準エラー出力ストリームへ出力します。
-.It eval
+.It Ic esyscmd
+その最初の引数をシェルへ渡し、シェルの標準出力に返します。
+シェルがその標準入力および
+.Nm
+の標準エラーを共有することに注意してください。
+.It Ic eval
 第 1 引数を計算式とみなして 32-bit 幅の算術演算を用いて計算します。
 演算子としては標準の C で用いられるもの、すなわち 3 項、
 算術、論理、シフト、関係、ビットの各演算子、および括弧が
@@ -119,109 +219,220 @@ divert
 また数値も C と同様に 8 進、10 進、16 進で記述できます。
 第 2 引数で (もしあれば) 演算結果の基数を指定でき、
 第 3 引数で (もしあれば) 演算結果の最小桁数を指定できます。
-.It expr
-eval の別名です。
-.It ifdef
+.It Ic expr
+.Ic eval
+の別名です。
+.It Ic ifdef
 第 1 引数で指定した名前のマクロが定義されていれば第 2 引数を返し、
 定義されていなければ第 3 引数を返します。
-第 3 引数が省略されていた場合は、その値は NULL になります。
-ちなみに `unix' という単語があらかじめ定義されています。
-.It ifelse
+第 3 引数が省略されていた場合は、その値は
+.Dv NULL
+になります。
+ちなみに
+.Ic unix
+という単語があらかじめ定義されています。
+.It Ic ifelse
 第 1 引数が第 2 引数とマッチしたら第 3 引数を返します。
-マッチしなかった場合、その 3 個の引数は捨てられて次の 3 引数を
+.Ic マッチしなかった場合 (ifelse)、
+その 3 個の引数は捨てられて次の 3 引数を
 用いて同様の検査を繰り返します。
 この処理は引数がなくなるか あるいは 1 つだけ残るまで繰り返され、
-どれにもマッチしなかった場合には その最後に残った引数または NULL
+どれにもマッチしなかった場合には その最後に残った引数または
+.Dv NULL
 (引数がなくなった場合) が返されます。
-.It include
+.It Ic include
 第 1 引数で指定されたファイルの内容を返します。
-ファイルが読み込めなかった場合にはエラーメッセージを出力して処理を
-中断します。
-.It incr
+ファイルが見つからなかった場合は、include パスを
+コマンドラインで
+.Fl I
+指定されたディレクトリを指定するか、
+ディレクトリ毎にコロンで分けたリストを
+環境変数
+.Ev M4PATH
+に設定してください。
+ファイルを include できない場合は、
+エラーメッセージを表示して異常終了します。
+.It Ic incr
 引数を 1 だけ増加させます。
 引数は正しく数値を表現する文字列でなければいけません。
-.It index
+.It Ic index
 第 2 引数が、第 1 引数の中で、何文字目に出現するかを返します
-(たとえば index(the quick brown fox jumped, fox) では 16 が返ります)。
-第 2 引数が第 1 引数の中に含まれていなかった場合には -1 を返します。
-.It len
+(たとえば
+.Fn index "the quick brown fox jumped" fox
+では 16 が返ります)。
+第 2 引数が第 1 引数の中に含まれていなかった場合には 
+.Ic index
+は -1 を返します。
+.It Ic indir
+第 1 引数として渡される項目のマクロを間接的に呼びます。
+それ以降は、第 1 引数のマクロに対する引数です。
+.It Ic len
 第 1 引数の文字数を返します。余分な引数は無視されます。
-.It m4exit
+.It Ic m4exit
 第 1 引数 (指定されなかった場合は 0) を終了コードとして即座に終了します。
-.It m4wrap
-入力が最後の EOF に達したときに、どのような動作を行うかを設定します。
+.It Ic m4wrap
+入力が最後の
+.Dv EOF
+に達したときに、どのような動作を行うかを設定します。
 一般には種々の後始末を行うマクロを設定します
-(たとえば、m4wrap("cleanup(tempfile)") とすると他の全ての処理が終了した
-後に cleanup マクロが呼び出されます)。
-.It maketemp
-第 1 引数の中の文字列 XXXXX を現在のプロセス ID に置換します。
+(たとえば、
+.Fn m4wrap cleanup(tempfile)
+) とすると他の全ての処理が終了した
+後に
+.Ic cleanup
+マクロが呼び出されます)。
+.It Ic maketemp
+第 1 引数の中の文字列
+.Dq Li XXXXX
+を現在のプロセス ID に置換します。
 その他の部分はそのままです。
 これはユニークなテンポラリファイル名の生成に利用できます。
-.It paste
+.It Ic paste
 第 1 引数で指定されたファイルの内容をマクロ処理を一切行わずに include
 します。
 もしファイルが読み込めない場合にはエラーメッセージを出力して処理を
 中断します。
-.It popdef
-各引数へ pushdef されている定義を戻します。
-.It pushdef
-define と同様の引数をとってマクロを定義しますが元の定義をスタックへ
+.It Ic patsubst
+文字列のうち、正規表現にマッチする部分が置換文字列で置き換えられます。
+通常は次の代入規則が適用されます:
+アンパサンド
+.Pq Ql &
+は、正規表現にマッチした文字列で置き換えられます。
+文字列
+.Sq \e Ns Ar #
+.Ns ( Ar #
+は数値)
+は、一致する後方参照と置き換えられます。
+.It Ic popdef
+各引数へ
+.Ic pushdef
+されている定義を戻します。
+.It Ic pushdef
+.Ic define
+と同様の引数をとってマクロを定義しますが元の定義をスタックへ
 保存しておきます。
-保存された定義は後で popdef で戻すことができます。
-.It shift
+保存された定義は後で
+.Ic popdef
+で戻すことができます。
+.It Ic regexp
+正規表現に基づき、文字を見つけます。
+第 2 引数までの場合は
+最初にマッチする文字位置を、
+マッチする文字がない場合は -1 を返します。
+第 3 引数がある場合、
+その中に含まれるパターンを置き換えた文字列を返します。
+.It Ic shift
 第 1 引数を除いた全ての引数を返します。
 残りの引数はクォートされてコンマで区切られます。
 クォートすることによって以降の処理で置換が行われないようにしています。
-.It sinclude
-エラーが起きても無視される点を除いて include と同じです。
-.It spaste
-エラーが起きても無視される点を除いて paste と同じです。
-.It substr
+.It Ic sinclude
+エラーが起きても無視される点を除いて
+.Ic include
+と同じです。
+.It Ic spaste
+エラーが起きても無視される点を除いて
+.Ic paste
+と同じです。
+.It Ic substr
 第 1 引数の文字列のうちの、第 2 引数で指定されるオフセットから始まり
 第 3 引数で指定される文字数の範囲の部分文字列を返します。
 第 3 引数が省略された場合は残りの文字列全てを返します。
-.It syscmd
+.It Ic syscmd
 第 1 引数をシェルに渡します。戻り値はありません。
-.It sysval
-最後に実行した syscmd の戻り値を返します。
-.It translit
+.It Ic sysval
+最後に実行した
+.Ic syscmd
+の戻り値を返します。
+.It Ic traceon
+引数がある場合はそのマクロの展開をトレースをオンにします。
+引数がない場合はすべてのマクロをトレースをオンにします。
+.It Ic traceoff
+引数がある場合はそのマクロの展開をトレースをオフにします。
+引数がない場合はすべてのマクロをトレースをオフにします。
+.It Ic translit
 第 1 引数の中の文字を、第 2 引数で指定された文字集合から第 3 引数で
 指定された文字集合へ書き直します。ただし
 .Xr tr 1
 式の省略指定を用いることはできません。
-.It undefine
-第 1 引数で指定されたマクロを未定義にします。
-.It undivert
+.It Ic undefine
+引数で指定されたマクロを未定義にします。
+.It Ic undivert
 指定された出力キュー (引数がない場合は全てのキュー) の内容を掃き出します。
-.It unix
+.It Ic unix
 OS プラットフォームを調べるために予め定義されているマクロです。
+.It Ic __line__
+現在のファイルの行番号を返します。
+.It Ic __file__
+現在のファイル名を返します。
 .El
 .Sh 診断
 .Ex -std
 .Pp
-終了ステータスは、入力ファイルの
-.Em m4exit
-マクロを使用して指定可能です。
-.Sh 関連項目
-.Xr cpp 1
-.Sh 規格
+.Ic m4exit
+マクロは、入力ファイルから終了状態に変更するために
+使用してください。
+.Sh 互換性
 .Nm
-ユーティリティは、未実装の
-.Em traceon
+は、GNU-m4 から加えられた少々の拡張に加えて、
+Single Unix Specification Version 2 に追従しています。
+フラグ
+.Fl I, d
 および
-.Em traceoff
-の組み込みマクロを除き、
-.St -p1003.1-2001
-仕様互換です
+.Fl t
+は非標準です。
 .Pp
-.Em expr ,
-.Em paste ,
-.Em spaste ,
-.Em unix
-の組み込みマクロは、標準を拡張したものです。
+トレーシングフォーマット出力と
+.Ic dumpdef
+は、
+任意の標準で
+指定されません。
+それらは、変更するでしょう。
+依存してはなりません。
+現在のトレーシングフォーマットは、
+.Nm autoconf
+が機能できるよう GNU-m4 に基づいて厳密に作成されています。
+.Pp
+移植性のためには、
+.Ic builtin ,
+.Ic esycmd ,
+.Ic expr ,
+.Ic indir ,
+.Ic paste ,
+.Ic patsubst ,
+.Ic regexp ,
+.Ic spaste ,
+.Ic unix ,
+.Ic __line__ ,
+および
+.Ic __file__
+のマクロは、使用しないほうがよいです。
+.Pp
+すべての組み込みは、
+他の多くの
+.Nm
+の実装内で、
+引数なしで
+拡張します。
+.Pp
+他の多くの
+.Nm
+の実装は、
+バッファサイズに関して、非常にサイズ制限を行っています。
+.Sh 規格
+The
+.Nm
+ユーティリィティは
+.St -p1003.1-2001
+適合します。
+.Sh 歴史 
+An
+.Nm
+コマンドは、PWB UNIX から登場しました。
 .Sh 作者
+.An -nosplit
 .An Ozan Yigit Aq oz@sis.yorku.ca
 および
-.An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU
-.Sh バグ
-トレーシングマクロは実装されていません。
+.An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU .
+.br
+.An Marc Espie Aq espie@cvs.openbsd.org
+による GNU-m4 互換性拡張