YOS OPENSONAR

  2. >
  3. freebsd
  4. >
  5. man
  6. >
  7. ja
  8. >
  9. man1
  2. >
  3. freebsd
  4. >
  5. man
  6. >
  7. ja
  8. >
  9. man1
EN JA
MANDOC(1)
MANDOC(1) FreeBSD General Commands Manual MANDOC(1)

名称

mandoc — UNIX マニュアルを書式化して表示する

書式

mandoc [ -V][ -mformat][ -Ooption][ -Toutput][ -Wlevel][ file ...]

解説

mandoc ユーティリティは、表示のために UNIX マニュアルページを書式化します。

デフォルトで、 mandoc は、 -mandoc を意味して、stdin (標準入力) から mdoc(7) または man(7) テキストを読み込み、 -Tascii 出力を生成します。

引数は、次の通りです:

-m format
入力書式。利用可能な書式ついては、 入力書式 を参照してください。デフォルトは、 -m andoc です。
-O option
コンマで区切られた出力オプション。
-T output
出力書式。利用可能な書式については、 出力書式 を参照してください。 -Tasciiへのデフォルト。デフォルトは、 -T ascii です。
-V
バージョンを印刷 (表示) して、終了します。
-W level
標準エラー出力に報告され、終了状態に影響する最小のメッセージ level 指定します。 level は、 warning, error または fatal を指定することができます。デフォルトは、 -W fatal です。 -W all は、 -W warning に対する別名です。詳細については、 終了ステータス と 診断 を参照してください。

特別のオプション -Wstop は、少なくとも要求されたレベルの警告またはエラーを引き起こすファイルを解析の後に終了するように mandoc に伝えます。書式化された出力は、そのファイルから生成されません。 level と stop が要求されるなら、それらは、コンマに結合することができます、例えば、 -Werror, stop。

file
0 個以上のファイルから入力を読み込みます。指定されないなら、stdin (標準入力) から読み込みます。複数のファイルが指定されるなら、 mandoc は、最初の失敗した解析で停止します。

入力書式

mandoc ユーティリティは、それぞれ -m doc と -m an を付けて mdoc(7) と man(7) 入力を受け付けます。 mdoc(7) 形式が 強く 推奨されます。 man(7) は、古いマニュアルのためだけに使用されるべきです。

また、デフォルトである 3 番目のオプション -mandoc は、次のその場のエンコーディングを決定します: 最初のコメントでないマクロが‘Dd’または‘Dt’であるなら、 mdoc(7) パーサ (parser) が使用されます。そうでなければ、 man(7) パーサが使用されます。

複数のファイルが -mandoc で指定されるなら、それぞれは、このように、その決定されたファイルタイプがあります。複数のファイルが指定され、 -mdoc または -man が指定されるなら、この形式は、排他的に使用されます。

出力書式

mandoc ユーティリティは、出力モードに対応する次の -T 引数を受け付けます:
-T ascii
7 ビットの ASCII 出力を生成します。これは、デフォルトです。 ASCII 出力 を参照してください。
-T html
厳格な CSS1/HTML-4.01 出力を生成します。 HTML出力を を参照してください。
-T lint
解析のみです: 出力を生成しません。 -W warning を意味します。
-T locale
現在のロケールを使用して、出力をエンコードします。 ロケール出力 を参照してください。
-T man
man(7) 形式の出力を生成します。 man 出力 を参照してださい。
-T pdf
PDF 出力を生成します。 PDF 出力をを参照してください。
-T ps
PostScript 出力を生成します。 PostScript 出力 を参照してください。
-T tree
段付けされた解析ツリーを生成します。
-T utf8
UTF-8 マルチバイト形式で出力をエンコードします。 UTF-8 出力 を参照してください。
-T xhtml
厳格な CSS1/XHTML-1.0 出力を生成します。 XHTML 出力 を参照してください。

複数の入力ファイルが指定されるなら、これらは、対応するフィルタによって順番に処理されます。

ASCII 出力

デフォルトである、 -T ascii によって生成された出力は、 ascii(7) に文書化されている標準 7 ビット ASCII で表現されます。

フォントスタイルは、下線文字‘c’が‘_\[bs]c’として表現されるようにエンコードされたバックスペースを使用することによって適用されます、ここで、‘\[bs]’は、バックスペース文字番号 8 です。エンボーデン (embolden) された文字は、‘c\[bs]c’として表現されれます。

mandoc_char(7) で文書化された特殊文字は、ASCII 同等文字の最善の方法で表示されます。同等なものが見つからないなら、‘?’が代わりに使用されます。

出力幅は、リテラルの入力行が、この制限を越えていなければ、 78 の可視カラムに制限されます。

次の -O 引数が受け付けられます:

indent= indent
通常テキストのための左マージンは、 mdoc(7) に対しては、5 のデフォルト man(7) に対しては、7 の代わりに indent (段付け) 空白文字に設定されます。これを増加させることは、推奨されません。それは、低下された書式の結果となります、例えば、あふれる行、または見苦しい改行。
width= width
出力の幅は、≥60 に正規化される width に設定されます。

HTML 出力

-T html によって生成された出力は、厳格な HTML-4.01 に適合します。

example.style.css ファイルは、出力のカスタマイズのために利用可能なスタイルシートクラスを文書化しています。スタイルシートが -Ostyle で指定されないなら、 -Thtml は、あらゆるグラフィックまたはテキストベースの web ブラウザで読み込み可能な単純な出力をデフォルトとします。

特殊文字は、10 進数にデコードされた UTF-8 で表示されます。

次の -O 引数が受け付けられます:

fragment
<!DOCTYPE>宣言と<html>, <head>と<body>要素を省略して、<body>要素より下のサブツリーのみを出力します。 style 引数は、無視されます。これは、既存のドキュメント内にマニュアルの内容を組み込むとき、役に立ちます。
includes= fmt
文字列 fmt 例えば、 ../src/%I.html は、(通常、‘In’マクロによって) リンクされたヘッダファイルのためのテンプレートとして使用されます。‘%I’のインスタンスは、インクルード (include) ファイル名と置き換えられます。デフォルトは、ハイパーリンク (hyperlink) を提示ことはありません。
man= fmt
文字列 fmt 例えば、 ../html%S/%N.%S.html は、(通常、‘Xr’マクロによって) リンクされたマニュアルのためのテンプレートとして使用されます。‘%N’と‘%S’のインスタンスは、それぞれ、リンクされたマニュアルの名前とセクションと置き換えられます。セクションが含まれていないなら、セクション 1 が仮定されます。デフォルトは、ハイパーリンク (hyperlink) を提示ことはありません。
style= style.css
ファイル style.css は、外部のスタイルシートのために使用されます。これは、有効な絶対値または相対値の URI でなければなりません。

ロケール出力

ロケール依存の出力のエンコードは、 -T locale でトリガされます。このオプションは、すべてのシステムで利用可能ではありません: ロケールのサポートのないシステム、または内部表現が自然な UCS-4 でないものは、 -T ascii に戻ります。フォントスタイルの仕様と利用可能なコマンドラインの引数については、 ASCII 出力 を参照してください。

man 出力

入力形式を man(7) 出力の形式に変換します。これは、 mdoc(7) のフォーマッタ (formatter) がない古いシステムにマニュアルのソースを配信するために役に立ちます。

mdoc(7) が入力として渡されるなら、 man(7) に変換されます。入力形式が man(7) であるなら、入力は、あらゆる roff(7) の‘so’要求を拡張して、出力にコピーされます。また、パーサ (parser) は、実行され、通常のように、 -W レベルは、 診断 が入力を出力にコピーする前に表示されることを制御します。

PDF 出力

PDF-1.1 出力は、 -T pdf によって生成されます。 -O 引数とデフォルトについては、 PostScript 出力 を参照してください。

PostScript 出力

PostScript “Adobe-3.0” Level-2 ページは、 -T ps によって生成されます。出力ページは、レター (letter) サイズをデフォルトとし、 Times フォントファミリ、11 ポイントで表示されます。マージンは、1/9 のページ長と幅として計算されます、行の高さは、1.4m です。

特殊文字は、 ASCII 出力 のように表示されます。

次の -O 引数が受け付けられます:

paper= name
用紙サイズ name は、 a3, a4, a5, legal または letter のうちの 1 つを指定できます。また、ミリメートル単位の高さで NNxNN として手動でデメンジョン (dimension) を指定することができます。未知の値に遭遇するなら、 letter が使用されます。

UTF-8 出力

UTF-8 ロケールを強制するためには、 -T utf8 を使用します。詳細とオプションについては、 ロケール出力 を参照してください。

XHTML 出力

厳格な XHTML-1.0 に適合する -T xhtml によって生成された出力。

詳細については、 HTML 出力 を参照してください。 HTML タグの代わりに XHTML タグを生成すること以上に、これらの出力モードは、同一です。

終了ステータス

mandoc ユーティリティは、 -W オプションに関連したメッセージ level によって制御される次の値のうちの 1 つで終了します:

0
警告またはエラーが生じませんでした、または、それらが要求された level より低かったので、行ったものが無視されました。
2
少なくとも 1 つの警告が生じましたが、エラーはなく、 -W warning が指定されました。
3
少なくとも 1 つの解析エラーが生じましたが、致命的なエラーはなく、 -W error または -W warning が指定されました。
4
致命的な解析エラーが生じました。
5
無効のコマンドライン引数が指定されました。入力ファイルが読み込まれていません。
6
オペレーティングシステムエラーが生じました、例えば、メモリの使い果たし、または入力ファイルをアクセスするエラーです。そのようなエラーによって、 mandoc は、恐らく解析しているかファイルをフォーマットしている最中に、直ちに終了します。

-Tlint 出力モードを選択することは、 -Wwarning を意味することに注意してください。

使用例

端末にマニュアルをページ付けするためには、次の通りです:

$ mandoc -Wall,stop mandoc.1 2>&1 | less
$ mandoc mandoc.1 mdoc.3 mdoc.7 | less

スタイルシートとして style.css で HTML マニュアルを生成するためには、次の通りです:

$ mandoc -Thtml -Ostyle=style.css mdoc.7 > mdoc.7.html

マニュアルの大きな一式をよく調べるためには、次の通りです:

$ mandoc -Tlint `find /usr/src -name \*\.[1-9]`

A4 用紙のための一連の PostScript マニュアルを生成するためには、次の通りです:

$ mandoc -Tps -Opaper=a4 mdoc.7 man.7 > manuals.ps

mdoc(7) パーサ (parser) がないシステムで使用するためには、最新の mdoc(7) マニュアルを古い man(7) 形式に変換します:

$ mandoc -Tman foo.mdoc > foo.man

診断

エラーを解析することを報告する標準エラーメッセージは、次のものが前に付けられます:

file: line: column:  level:

ここで、フィールドは、次の意味があります:

file
メッセージを引き起こす入力ファイルの名前。
line
その入力ファイルの行番号。行番号は、1 で始まります。
column
その入力ファイルのカラム番号。カラム番号は、1 で始まります。問題が単語によって引き起こされるなら、カラム番号は、通常単語の最初の文字を指します。
level
大文字で印刷されるメッセージレベル。

メッセージレベルには、次の意味があります:

fatal
パーサは、与えられた入力ファイルをまったく解析することができません。書式化された出力は、その入力ファイルから生成されません。
error
入力ファイルは、それが無効であるので、または mandoc がまだそれをまだ実装していないので、安全に解釈することができない構文を含んでいます。入力の一部の廃棄または失われたトークンの挿入によって、パーサは、継続することができ、エラーは、書式化された出力の生成を防ぎませんが、一般的に、その出力の準備は、情報損失、壊れた文書構造または意図されない書式化を含んでいます。
warning
入力ファイルが時代遅れ、抑制されているか、または移植性のない構文を使用しています。同様に、入力の意味は、明白で、正確な表現を生成することができます。 mandoc の代わりに他の書式化ツールを使用するとき、警告を起こす文書は、貧弱に表示するかもしれません。

warning と error レベルのメッセージは、それらのレベル、またはより低いレベルが -W オプションまたは -Tlint 出力モードを使用して要求されないなら隠されます。

また、 mandoc ユーティリティは、例えば、メモリが使い果たすか、または入力ファイルを読み込むことができないとき、無効のコマンドライン引数またはオペレーティングシステムエラーと関連するメッセージを印刷しますそのようなメッセージは、上に記述された接頭辞を持ち運びません。

互換性

このセクションは、GNU troff との mandoc の互換性を要約しています。各入力と出力の形式は、別々に注記されています。

ASCII 互換性

  • ‘\[uNNNN]’エスケープで指定される表示可能でない unicode のコードポイント (codepoint) は、 mandoc で‘?’として印刷 (表示) されます。 GNU troff では、これらは、エラーを起こします。
  • -Tascii の mdoc(7) の‘Bd -literal’と‘Bd -unfilled’マクロは、-filled と-ragged と同意語です。
  • 歴史的な GNU troff で、‘Pa’ mdoc(7) マクロは、「関連ファイル」ファイルセクションの‘It’の下でスコープ (scope) されたとき、強調され (下線が引かれ) ません。これは、 mandoc で正確に振る舞います。
  • -Tascii の‘Ss’ mdoc(7) マクロに続くリストまたは表示は、‘Sh’でちょうど、それを行わないように、先の垂直 (prior vertical) のブレークをアサートしません。
  • -Tascii の‘na’ man(7) マクロには、効果がありません。
  • 単語は、ハイフンで結ばれません。

HTML/XHTML 互換性

  • ‘\fP’エスケープは、決め打ちの代わりに CSS によって今指示される最後に表示された装飾ではなく、前の‘\f’エスケープへのフォントに戻ります。または、それは、同じ理由で現在の範囲を過ぎてスパン (span) しません。 ASCII 出力 モードでは、これがうまくいくことに注意してください。
  • mdoc(7) ‘Bl -hang’と‘Bl -tag’リストタイプは、HTML の制約を表現するために、 (左側を越えて続くブレークがない) 同様に表示されます。
  • man(7) ‘IP’と‘TP’リストは、同様に表示されます。

関連項目

eqn(7), man(7), mandoc_char(7), mdoc(7), roff(7), tbl(7)

作者

mandoc ユーティリティは、 Kristaps Dzonsons, kristaps@bsd.lv によって書かれました。

警告

-T html と -T xhtml では、要素の属性の最大サイズは、通常 1024 バイトである、 BUFSIZ によって決定されます。 -O style= really/long/link のように長いリンクの形式を設定するとき、これに気付いてください。

空の‘B’内の‘br’のような -man の次の行の要素の範囲内の入れ子にされた要素は、 -Thtml と -Txhtml を混乱させ、それは、先の次の行の範囲の書式化を忘れます。

‘'’制御文字は、標準マクロの制御文字の別名で、 GNU troff に規定されるように行のブレークを出力しません。

December 25, 2011 FreeBSD