man(7)

Date: 1998/11/27
Source: TOYODA Eizi

名称

htroff -man - UNIX オンラインマニュアルのための htroff マクロパッケージ

書式

htroff -man [ -a ] [ -u[d] ] filename...

説明

htroff の man マクロパッケージは UNIX オンラインマニュアルと同じ形式の文書 (たとえばこのマニュアル) を HTML 化するのに用いられます。

以下の文字列レジスタは -man マクロパッケージによって定義されています。

\*R
登録商標の記号 ® なのですが、 htroff では多くの Web ブラウザで表示できるように `(Reg)' に置換されます。
\*S
本来は文字のサイズを元に戻すための文字列なのですが、 現バージョンでは空文字列となります。

コマンドラインオプション

htroff を用いる場合は以下のコマンドラインオプションによって man マクロパッケージの動作を変えることができます。

-a
.TH s n リクエストで出力先ファイル名を自動的に決定します。 ファイル名は s.htm ですが、 -u オプションが指定されておらず引数 n が2から7までの数字で始まる場合は s-n.htm という形式になります。 ただし大文字は小文字に変換されます。 たとえば htroff(1)htroff.htm, man(7)man-7.htm となります。 MS-DOS のファイル名の 8+3 文字制限によって二つのマニュアルページの 出力先が同じになってしまう問題は、まだ対処されていません。
-u
.TH s n リクエストで決定される出力先ファイル名が たとえ 2-7 章であっても章番号 n を含まないようにします。 この場合たとえば man(1) と man(7) の参照が混同されます。
-ud
-u 指定時と似ていますが、カレントディレクトリではなく htmn/s.htm に出力しようとします。このことによって異なる章のマニュアルの参照が より確実にできるようになります。

リクエスト

以下のマクロの引数で t と書かれているもの (たとえば .I .SB の引数) には 0 から 6 語の範囲で複数の語を与えることができます。 語の定義は htroff(1) にあるとおりで、 二重引用符 (") によってスペースを含む語を与えることができます。 もし引数 t に何も与えない場合は特別で、マクロの次の入力行が印字されます。

以下の説明で標準書体とは \fR エスケープシーケンスの後の状態を指し、 元祖 roff でローマン体と呼んでいるものですが、 htroff(1) では HTML でフォント指定を行うわけではなく、 斜体や太字の指定をしていないという意味にすぎません。

.B t
テキスト t (省略時は次の行) を太字で印字します。
.BI t
テキスト t (省略時は次の行) の各語を 交互に太字と斜体を用いて連結し印字します。
.BR t
テキスト t (省略時は次の行) の各語を 交互に太字と標準書体を用いて連結し印字します。 他のマニュアルページへの参照は たとえば man(7) のように .BR を用いて記述します。 他のマニュアルページの参照であることが判ると ハイパーリンクに変換されます。
.DT
何の動作もしません。 本来 UNIX roff ではタブストップをデフォルトに戻すものです。
.HP i
ハンギング・インデント付きの段落をはじめます。 現バージョンでは .TP と何が違うのかよく判らないのでエイリアスとして実装されています。 本来は引数 i は標準インデント幅を指定するためのものですが、 現バージョンでは何の効果もありません。
.I t
テキスト t (省略時は次の行) を斜体にします。
.IB t
テキスト t (省略時は次の行) の各語を 交互に斜体と太字を用いて連結し印字します。
.IP x i
タグ x 付きのインデントされた段落を始めます。 リクエスト .TP の次の行に x を指定するのと等価です。
.IR t
テキスト t (省略時は次の行) の各語を 交互に斜体と標準書体を用いて連結し印字します。
.IX t
現バージョンでは何の動作もしません。 作者は目的を理解していませんが、 SunOS 4.1.x の man マクロパッケージとの互換性のために存在します。
.LP
左づめの段落を始めます。
.PD d
本来は段落間の鉛直間隔 d (省略時は .4v) を指定するものです。 現バージョンでは何の効果もありません。
.PP
リクエスト .LP と等価です。
.RE
相対インデントの終わりです。
.RB t
テキスト t (省略時は次の行) の各語を 交互に標準書体と太字を用いて連結し印字します。
.RI t
テキスト t (省略時は次の行) の各語を 交互に標準書体と斜体を用いて連結し印字します。
.RS i
相対インデントを開始します。 本来、以下の入力行のインデント幅は i だけ増加されるのですが、 現在は .RS から .RE までが <BLOCKQUOTE> タグで囲まれるという 安直な実装になっており、インデント幅の制御はできません。
.SB t
本来はテキスト t を小さな太字にするものですが、 現バージョンでは文字サイズの管理はしていないので .B と等価です。
.SH t
見出し t を持つセクションをはじめます。
.SM t
テキスト t (省略時は次の行) を小さな文字にするものですが、 現バージョンでは文字サイズの管理はしていないので t をそのまま出力します。
.SS t
見出し t を持つサブセクションをはじめます。
.TH n s d f m
マニュアルページのコメント以外の最初のリクエストは .TH でなければ なりません。 これは第 s 章のページ n であることを示します。 もし -a オプションが指定されていれば、 以後の出力先が変更されます。 d は最終変更日付、 f はソース (ドキュメンテーションをした主体)、 m は章のタイトルを表わします。
.TP i
次の入力行をタグとして インデントされた段落をはじめます。 これは <DL><DT>タグ<DD> というマークアップを生み出します (この後の .LP.SH によって自動的に必要な </DL> が挿入されます) タグとなる語を与えない場合は <BR> となります。 引数 i は本来インデント幅を指定するものですが、 現バージョンでは何の効果もありません。
.TX t p
SunOS 4.1.x の man マクロパッケージとの互換性のために存在します。 本来文書の略称 t に対応する題名と 句読点 p を連結して印字するものですが、 現バージョンでは TX(t)p が印字されます。

オンラインマニュアルの構成

マニュアルページのソースファイルの1行目は、 man(1) に対してプリプロセッサの指定を行うためのコメント行です。 たとえば

'\" t

tbl(1) プリプロセッサを必要とすることを伝えます。 このほか eeqn(1) を、ppic(1) を意味します。

コメント以外の最初の行は .TH リクエストです。

その後に以下のようなセクションが書かれます:

.SH 名前
(英語では NAME) ページの名前、ダッシュ (\-) 、そして概要の1行説明を続けます。 このセクションには htroff(1) リクエストやダッシュ以外のエスケープシーケンスを書かないでください。 UNIX ではこのセクションの内容を使って whatis(1) データベースを構築するからです。
.SH 書式
(英語では SYNOPSIS)
コマンドの場合:
コマンドと引数の文法を記述します。 太字はここに示したとおりにタイプしなければならないものを示します。 斜体は置き換えることができる語を示します。 太字や斜体で示した語の引用は、たとえ文頭であっても 小文字を大文字に書き換えてはなりません。
文法的を記述するための記号は標準書体で書きます:
[ ]
ブラケットで囲まれた要素は省略可能であることを示します。
|
縦線で区切られた要素は相互に排他的であることを示します。 つまり、縦線で区切られたリストのうちどれか一つを指定することができます。
...
省略記号 (ピリオド3つ) の前の要素は繰り返すことができます。 省略記号がブラケットの後に続いている場合は ブラケットの中の表現が任意個 (0も可) 指定できることを示します。
C 言語 API の場合:
もし必要ならば、変数の宣言または #include ディレクティブを最初に示し、その後に関数宣言を示します。
それ以外の場合:
条件付きで読み込まれるファイルの書式マニュアルの場合、 そのファイルの読み取りの指示方法を示します。 書くことがなければ「書式」セクションはなくてもかまいません。
.SH 説明
(英語では DESCRIPTION) このセクションは「これは何をするものか」を簡潔に説明するものです。 もしサブコマンドや入力ファイルの文法があるならば、 その詳細は通常「オプション」セクションの後で 別にセクションを立てて記述します。
.SH オプション
(英語では OPTIONS) コマンドならばオプションを列挙し解説します。 Fortran 90 の手続のマニュアルならば、 省略可能な引数はこの節に書かれるべきでしょう。
.SH ファイル
(英語では FILES) 関連したファイルのリストを挙げます。
.SH 参照
(英語では SEE ALSO) 関連したマニュアルページのリストをコンマで区切って挙げます。 ついで他の出版物などへの参照を (あれば) 挙げます。
.SH 診断
(英語では DIAGNOSTICS) エラー・警告などのメッセージが簡潔すぎるならば、 それらを挙げて説明をつけます。 C 言語の関数がエラーを返したときに参照すべきもの (たとえば errno(3) など) があればこのセクションで記述されるべきです。
.SH バグ
(英語では BUGS) 制限または既知の欠陥を記述します。

参照

man(1), htroff(1), mstd(1)

バグ

UNIX roff ではタブストップや段落のインデント幅を即値で指定できるので、 man のマクロの中にもそのような概念を含む仕様のものがありますが、 HTML でインデント幅指定をしようとするのはよいスタイルとは思えないので、 実際には幅の指定に対応する動作は実装されていません。

UNIX troff -man ではフォントを変更したまま段落が終了すると フォントが元に戻るようになっているそうですが、 このようなおせっかいな機能は実装されていません。 文字の大きさの制御は実装されていません。


HTML generated using htroff at 23 March 2010 11:19:21.