タイプ

enum mandoc_esc

エスケープシーケンスの分類。

enum mandocerr

解析中の致命的なエラー、エラーまたは警告メッセージ。

enum mandoclevel

システムオペレーションに関連する enum mandoclevel の分類。

struct mchars

文字列とグリフ (glyph) の間の変換を考慮に入れるオブジェクトへの不透明な (サイズおよび形がわからない) ポインタ。 mchars_alloc() を参照してください。

enum mparset

入力を読み込むとき、パーサ (parser) のタイプ。これは、通常、自動検出のための MPARSE_AUTO であるべきです。

struct mparse

実行している解析シーケンスへの不透明なポインタ。 mparse_alloc() で作成され、 mparse_free() で解放されます。これは、 mparse_reset() が解析の間に呼び出されるなら、解析された入力にわたって使用されます。

mandocmsg

パーサによって出力される致命的エラー、エラーと警告メッセージを取り扱う関数のためのプロトタイプ。

関数

mandoc_escape()

エスケープシーケンス (すなわち、‘\’で始まる文字列) をスキャンします。 end (終り) として‘\’の後の文字へのポインタを渡します。 ESCAPE_ERROR を返さないなら、それは解析されたエスケープシーケンスの上限に設定されます、その場合に、文字列は、偽りであり、捨てられるべきです。 ESCAPE_ERROR または ESCAPE_IGNORE でないなら、 start (開始) は、長さ sz のサブストリング (フォント、グリフ、何でも) の最初の適切な文字に設定されます。 start と sz の両方は、 NULL かもしれません。

man_meta()

成功した解析のメタデータを取得します。これは、 mparse_result() によって返されたポインタでのみ使用されます。

man_mparse()

現在の出力のための使用されたパーサ (parser) を取得します。

man_node()

成功した解析のルートノードを取得します。これは、 mparse_result() によって返されたポインタでのみ使用されます。

mchars_alloc()

特殊文字をグリフ (glyph) に変換するために struct mchars * オブジェクトを割り付けます。特殊文字の概観については、 mandoc_char(7) を参照してください。オブジェクトは、 mchars_free() で解放されなければなりません。

mchars_free()

mchars_alloc() で作成されたオブジェクトを解放します。

mchars_num2char()

文字インデックス (例えば、\N''エスケープ) を印刷可能な ASCII 文字に変換します。入力シーケンスが不正であるなら、\0 (nil 文字) を返します。

mchars_num2uc()

16 進数文字のインデックス (例えば、\[uNNNN] エスケープ) を Unicode コードポイントに変換します。入力シーケンスが不正であるなら、\0 (nil 文字) を返します。

mchars_spec2cp()

特殊文字を有効な Unicode コードポイントに変換します。失敗すれば、-1 を返し、成功すれば、0 でない Unicode コードポイントを返します。

mchars_spec2str()

特殊文字を ASCII 文字列に変換します。失敗すれば、 NULL を返します。

mdoc_meta()

成功した解析のメタデータを取得します。これは、 mparse_result() によって返されたポインタでのみ使用されます。

mdoc_node()

成功した解析のルートノードを取得します。これは、 mparse_result() によって返されたポインタでのみ使用されます。

mparse_alloc()

パーサ (parser) を割り付けます。同じパーサは、 mparse_reset() が解析の間に呼び出され限り、複数のファイルのための使用されます。 mparse_free() は、この関数によって割り付けられたメモリを解放するために呼び出されなければなりません。

mparse_free()

mparse_alloc() によって割り付けられたすべてのメモリを解放します。

mparse_getkeep()

keep バッファを獲得します。 mparse_keep() の呼び出しに続かなければなりません。

mparse_keep()

その解析された入力のコピーを保持するためにパーサ (parser) に指示します。これは、後の mparse_getkeep() 呼び出しで獲得することができます。

mparse_readfd()

ファイルまたはファイル記述子を解析します。 fd が -1 であるなら、 fname は、読み込みのためのオープンされます。そうでなければ、 fname は、 fd に関連した名前であると仮定されます。これは、異なるパラメータで複数回呼び出されるかもしれません。しかしながら、 mparse_reset() は、解析の間に呼び出されるべきです。

mparse_reset()

mparse_readfd() が再び使用できるように、パーサ (parser) をリセットします。

mparse_result()

解析の結果を取得します。成功した解析のみ、 (すなわち、 mparse_readfd() が MANDOCLEVEL_FATAL 未満を返した場合に) この関数を呼び出すべきで、その場合に、2 つのポインタのうちの 1 つが書き込まれます。

mparse_strerror()

エラーコードの静的に割り付けられた文字列表現を返します。

mparse_strlevel()

レベルコードの静的に割り付けられた文字列表現を返します。

変数

man_macronames

enum mant によってインデックスを付けられるような man マクロの文字列表現。

mdoc_argnames

enum mdocargt によってインデックスを付けられるような mdoc のマクロの引数の文字列表現。

mdoc_macronames

enum mdoct によってインデックスを付けられるような mdoc マクロの文字列表現。

man と mdoc 文字列

文字列は、mdoc と man のメタデータ、またはテキストノード (それぞれ MDOC_TEXT と MAN_TEXT) から抽出されます。これらの文字列は、入力から保護されている roff(7) エスケープと同様に、テキスト自体に組み込まれた特別の非印刷形式のキューがあります。システムを実装することは、人間に読み込み可能なテキストを生成するために両方の状況を扱う必要があります。一般的に、文字列は、7 ビットの ASCII 文字から成ると仮定されます。

次の非印刷文字が、テキスト文字列に組み込まれます:

ASCII_NBRSP

ブレークしない空白文字。

ASCII_HYPH

ソフトハイフン。

また、エスケープ文字は、テキスト文字列に逐語的に渡されます。エスケープ文字は、バックスラッシュ (‘\’) で始まる文字のシーケンスです。人間に読み込み可能なテキストを構築するために、これらは、 mandoc_escape() でインタセプト (intercept) されるべきで、 mchars_num2char(), mchars_spec2str() などの 1 つで変換されます。

man 抽象構文ツリー

この AST は、 man(7) で指示された存在論の規則によって管理され、その用語を従って抽出します。

AST は、 type フィールドによって宣言されるような要素、ルートとテキストがある struct man_node ノードから成ります。また、各ノードは、その解析ポイント ( line, sec と pos フィールド)、ツリーのその位置 ( parent, child, next と prev フィールド) といくつかのタイプ特有のデータを提供しています。

ツリーそれ自体は、大文字化された非端末がノードを表わすところで、次の標準形式によって配置されます。

ROOT

← mnode+

mnode

← ELEMENT | TEXT | BLOCK

BLOCK

← HEAD BODY

HEAD

← mnode*

BODY

← mnode*

ELEMENT

← ELEMENT | TEXT*

TEXT

← [[:ascii:]]*

入れ子にされた他の要素ができる要素のみは、 man(7) で文書化されるような next-lint 範囲があるものです。

mdoc 抽象構文ツリー

この AST は、 mdoc(7) で指示された存在論の規則によって管理され、その用語を従って抽出します。 mdoc(7) に記述される“in-line”要素は、単に“elements”と記述されます。

AST は、 type フィールドによって宣言される、ブロック、ヘッド、ボディ、要素、ルートとテキストタイプがある struct mdoc_node ノードから成ります。また、各ノードは、特に、 tok フィールドの生成されたマクロ、マクロから生成されたノードについて、その解析ポイント ( line, sec と pos フィールド)、ツリーのその位置 ( parent, child, nchild, next と prev フィールド) といくつかのタイプ特有のデータを提供しています。

ツリーそれ自体は、大文字化された非端末がノードを表わすところで、次の標準形式によって配置されます。

ROOT

← mnode+

mnode

← BLOCK | ELEMENT | TEXT

BLOCK

← HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]

ELEMENT

← TEXT*

HEAD

← mnode*

BODY

← mnode* [ENDBODY mnode*]

TAIL

← mnode*

TEXT

← [[:ascii:]]*

注目すべきものは、BLOCK 生成の HEAD、BODY と TAIL ノードに続く TEXT ノードです: これらは、句読点を参照します。さらに、TEXT ノードは、一般的に 0 でない長さの文字列がありますが、‘.Bd -literal’の特別の場合に、空行は、長さ 0 の文字列を生成します。複数のボディ部分は、新しいボディが新しいフレイズ (phrase) を導入するところで、‘Bl -column’の呼び出しでのみ見つかります。

mdoc(7) 構文ツリーは、同様に、壊れたブロック構造に対応します。 ENDBODY ノードは、そのブロックの物理的な終りの前に与えられたブロックに関連した書式化を終了するために利用可能です。それは、null でない end フィールドがあり、BODY の type には、それが終了している BLOCK と同じ tok があり、その BLOCK の BODY ノードを指す pending フィールドがあります。それは、その BODY ノードの間接的な子どもで、それ自体の子どもがありません。

ENDBODY ノードは、次の例のように、その子どもブロックの 1 つが、まだオープンされている間に、ブロックが終了するとき、生成されます:

.Ao ao 
.Bo bo ac 
.Ac bc 
.Bc end

この例は、次のブロック構造の結果となります:

BLOCK Ao 
    HEAD Ao 
    BODY Ao 
        TEXT ao 
        BLOCK Bo, pending -> Ao 
            HEAD Bo 
            BODY Bo 
                TEXT bo 
                TEXT ac 
                ENDBODY Ao, pending -> Ao 
                TEXT bc 
TEXT end

ここで、‘Ao’ブロックの書式化は、TEXT ao から TEXT ac まで拡張され、一方、‘Bo’ブロックの書式化は、TEXT bo から TEXT bc まで拡張されます。それは、 -Tascii モードで次のように提供されます:

<ao [bo ac> bc] end

悪く入れ子にされたブロックのためのサポートは、いくつかのより古い mdoc(7) 実装の後方互換性のみ提供されています。悪く入れ子にされたブロックを使用することは、 強く使用しないことを勧めます。例えば、 mandoc(1) の -Thtml と -Txhtml フロントエンドは、どれも意味のある方法でそれらを表示することができません。さらに、悪く入れ子にされたブロックに遭遇するときの振る舞いは、特に悪く入れ子にされたブロックの複数レベルを使用するとき、 troff 実装に渡って一貫していません。