1.4 このマニュアルの使い方

このマニュアルにはm4の入力と出力の例が多数あり、入力、出力、m4のエラーメッセージを区別するための簡単な表記法を使います。例は通常の文章と分け、次のように等幅フォントで示します。

This is an example of an example!

入力と出力を区別するため、m4のすべての出力には⇒、すべてのエラーメッセージにはerror→を先頭に付けます。コマンドラインオプションの影響を示す場合、コマンドラインは「$ like this」というプロンプト付きで示します。それ以外の場合は、単にm4を起動すればよいと考えてください。次のようになります。

$ command line to invoke m4
Example of input line
⇒Output line from m4
error→and an error message

例の中の^Dは入力ファイルの終わりを示します。「NL」は改行文字を指します。これらの例の大半は単独で実行でき、m4 -dを起動すれば同様の結果が得られます。実際、GNU M4パッケージに同梱されたテストスイートは、この文書の例から構成されています。一部の例は、カレントディレクトリがインストール用配布物を展開した場所であることを前提とします。例を追試する予定なら、今その場所へ移動しておくと便利です。

$ cd m4-1.4.21

m4の各定義済みマクロを説明するときは、引数に説明的な名前を付け、マクロ呼び出しの原型を次のように示します。

合成マクロ（Composite）: example(string, [count = ‘1’], [argument]…)

これは原型の例です。実際にexampleという名前のマクロがあるわけではありませんが、仮にあれば、組み込みマクロ（Builtin）ではなく合成マクロ（Composite）であることを示しています。少なくとも1つの引数stringが必要です。m4では、引数なしでマクロを呼び出す意図がない限り、マクロ名と開き括弧の間に空白を入れてはいけないことを思い出してください。countとargumentを囲む角括弧は、これらが省略可能な引数であることを示します。countを省略すると、countが1であるかのように振る舞います。一方、argumentを省略すると、空文字列であるかのように振る舞います。空の引数と、省略した引数は同じではありません。たとえば、example(`a')、example(`a',`1')、example(`a',`1',)は、いずれもcountを1に設定した同じ振る舞いになります。それに対し、example(`a',)とexample(`a',`')では、countに空文字列を明示的に渡します。省略記号（…）は、argumentより後にある追加の引数を無視せず、処理することを示します。

m4のマクロ引数はすべて文字列ですが、一部は数値、ファイル名、正規表現などとして特別に解釈されます。各マクロの説明では、引数の解釈と、目的の解釈に従って引数を解析できない場合に何が起きるかを示します。特に指定がない限り、数値として指定された引数は、先頭にゼロがあっても10進数として解析されます。また、空文字列を数値として解析するとエラーではなく0になりますが、警告は出されます。

この文書では、英単語であるかのように、ハイフンを入れずにbuiltinと一貫して表記・使用します。これはm4内部でのbuiltinプリミティブのつづりです。