.\" Copyright (c) 1998.
.\"	The FreeBSD Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" %FreeBSD: src/share/man/man7/man.7,v 1.1.4.1 1999/08/29 16:46:59 peter Exp %
.\" jpman %Id: man.7,v 1.3 1999/02/10 13:32:51 horikawa Stab %
.\"
.\" WORD: format		(roffで)書式整形(する)[man.7]
.\" WORD: indent		インデント[man.7]
.\"
.Dd November 30, 1998
.Os
.Dt MAN 7
.Sh 名称
.Nm man
.Nd 
.Nm \-man
マクロパッケージのクイックリファレンスガイド
.Sh 書式
.Nm groff
.Fl m Ns Ar an
.Ar
.Sh 解説
.Nm \-man
パッケージは、
.Ux
マニュアルページの書式整形に使用するマクロの集合です。
.Bx
システムでは、
.Nm
の使用は非推奨とされており、代わりに、それより表現力に富んだ
.Nm mdoc
パッケージが推奨されています。
.Sh 使用法
.Ss 慣習
.Nm
で使用するマクロは、1 文字か 2 文字のアルファベット大文字を用いて名前が
付けられています。
.Xr troff 1
で通常使われる慣習に従い、各マクロリクエストは、行の先頭に
.Li "."
をつけて始まります。
マクロリクエストの引数には、印字可能なテキストをとることが期待されています。
マクロリクエストの引数は、0 個から 6 個までの単語 (word) からなります。マクロリクエスト
によっては、引数をとらないときに次の入力行を処理するものもあります。例えば、
.Li ".I"
リクエストがそれだけで 1 行になっている場合、次の入力行が斜体 (italic) に
なります。
空白やタブ文字 (whitespace characters) は、クォートで囲むことで引数に
含めることができます。各パラグラフが始まる直前
およびフォントサイズ・フォントフェース変更マクロが処理された後では、
フォントとサイズはデフォルト値に戻されます。
.Ss インデント
.\" WORD:	prevailing indent	通常インデント[man.7]
通常インデント (prevailing indent) の間隔は、その後インデント状態の
パラグラフが継続する間、保持されていますが、非インデント状態の
パラグラフに到達するとデフォルト値にリセットされます。インデントに
おけるデフォルトの単位は、
.Dq en
です。
.Ss 前処理 (Preprocessing)
伝統的に、マニュアルページの書式整形と表示には
.Xr man 1
プログラムが用いられます。マニュアルページのソースコードの1行目が、
文字列
.Li \&\'\e"
.\" " bring emacs's font-lock mode back in sync ...
で始まる場合、
その行の残りの文字は、
.Xr troff 1
で文書を整形する前に実行する必要があるプリプロセッサを表します。
サポートしているプリプロセッサ指示子は次のとおりです。
.Bl -column "文字" "プリプロセッサ" -offset indent
.It Em 文字 Ta Em プリプロセッサ
.It e Ta Xr eqn 1
.It g Ta Xr grap 1
.It p Ta Xr pic 1
.It r Ta Xr refer 1
.It t Ta Xr tbl 1
.It v Ta Xr vgrind 1
.El
.Ss 利用可能な文字列
.Nm
パッケージで事前に定義されている文字列は次のとおりです。
.Bl -column "文字列" "XXXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
.It Em 文字列 Ta Em 説明
.It "\e*R" Ta "登録商標のシンボル(registration symbol)"
.It "\e*S" Ta "フォントサイズをデフォルトに戻す"
.It "\e*(Tm" Ta "商標のシンボル(trademark symbol)"
.It "\e*(lq" Ta "左引用符(left quote)"
.It "\e*(rq" Ta "右引用符(right quote)"
.El
.Pp
.Ss 利用可能なマクロ
利用可能なマクロをアルファベット順に説明します。
.Bl -tag -width "XXX XX"
.It ".B" Op Ar words
.Ar words
.\" WORD: typeset	版組みする[man.7]
.\" WORD: line break	(行を)分割する[man.7]
をボールド体で版組みします。行分割は生じません。引数を与えない
場合、次の行が処理の対象になります。
.It ".BI" Op Ar words
ボールド体と斜体を交互にして、
.Ar words
を結合します。行分割は生じません。
引数を与えない場合、次の行が処理の対象になります。
.It ".BR" Op Ar words
ボールド体とローマン体を交互にして、
.Ar words
を結合します。行分割は生じません。
引数を与えない場合、次の行が処理の対象になります。
.It ".DT"
デフォルトのタブ間隔を 0.5 インチに戻します。
行分割は生じません。
.It ".HP" Op Ar indent
パラグラフを、ハンギングインデント (hanging indent) で始め、
以後の通常インデント幅を
.Ar indent
に設定します。このリクエストが実行されると、強制的に行分割が
生じます。
.Ar indent
が指定されない場合、通常インデント幅が使用されます。
.It ".I" Op Ar words
.Ar words
を斜体で版組みします。行分割は生じません。
引数を与えない場合、次の行が処理の対象になります。
.It ".IB" Op Ar words
斜体とボールド体を交互にして、
.Ar words
を結合します。行分割は生じません。
引数を与えない場合、次の行が処理の対象になります。
.It ".IP" Op Ar tag Op Ar indent
インデントされたパラグラフを、タグ
.Ar tag
を付けて始めます。
また、以後の通常インデント幅を
.Ar indent
に設定します。
.Ar tag
が指定されていない場合、
.Ar tag
は空文字列
.Qq ""
と見なされます。
.Ar indent
が指定されない場合、
通常インデント幅と見なされます。
.It ".IR" Op Ar words
斜体とローマン体を交互にして、
.Ar words
を結合します。行分割は生じません。
引数を与えない場合、次の行が処理の対象となります。
.It ".LP"
左整列 (left-aligned) パラグラフを開始します。
通常インデント幅はデフォルト値に設定されます。このリクエスト
が実行されると、強制的に行分割が生じます。
.It "\&.P"
\&.LP の別名です。
.It ".PD" Op Ar distance
パラグラフ間の垂直方向の間隔を
.Ar distance
に設定します。
.Ar distance
が指定されない場合、値 0.4v が使用されます。
.It ".PP"
\&.LP の別名です。
.It ".RE"
相対インデント (以下の \&.RS を参照して下さい) を終了します。
このリクエストが実行されると強制的に行分割が生じ、
通常インデント値が、以前使用されていた値に戻されます。
.It ".RB" Op Ar words
ローマン体とボールド体を交互にして、
.Ar words
を結合します。行分割は生じません。
引数を与えない場合、次の行が処理の対象となります。
.It ".RI" Op Ar words
ローマン体と斜体を交互にして、
.Ar words
を結合します。行分割は生じません。
引数を与えない場合、次の行が処理の対象となります。
.It ".RS" Op Ar indent
相対インデントを開始します。インデント幅を
.Ar indent
だけ増加させます。
引数
.Ar indent
が指定されていない場合、通常インデント幅の値が使用されます。
.It ".SB" Op Ar words
フォントサイズを 1 ポイント小さくしてからボールド体で
.Ar words
を版組みします。行分割は生じません。引数が指定されない場合、
次の行が処理の対象となります。
.It ".SH" Op Ar words
セクションの表題 (section heading) を指定します。このリクエストが
実行されると、
強制的に行分割が生じます。また、通常インデント幅とマージンを
デフォルト値に戻します。
.It ".SM" Op Ar words
フォントサイズを 1 ポイント小さくしてから
.Ar words
を版組みします。行分割は生じません。引数が指定されない場合、
次の行が処理の対象となります。
.It ".SS" Op Ar words
セクション副表題 (section subheading) を指定します。このリクエストが
実行されると、
強制的に行分割が生じます。引数が指定されない場合、次の行が
処理の対象となります。このリクエストは、通常インデント幅とマージンを
デフォルト値に戻します。
.It ".TH" Ar name Ar section Ar date Xo
.Op Ar footer Op Ar center
.Xc
セクション
.Ar section
に属するリファレンスページ
.Ar name
を開始します。
第 3 引数
.Ar date
は、最終更新日です。
.Ar footer
が存在する場合、
これは左側に表示されるページフッタテキストを指定します。さらに、
.Ar center
が存在する場合、
これはページ中央のヘッダテキストを指定します。このリクエストは、
マニュアルページの一番最初のリクエストでなければなりません。
.It ".TP" Op Ar indent
タグ付きのインデントされたパラグラフを
開始します。付加するタグはこのリクエストの次の行で指定します。引数
.Ar indent
を指定すると、通常インデント幅の値を新しく指定できます。
このリクエストが実行されると、強制的に行分割が生じます。
.El
.Sh ページ構造
マニュアルページは、一般的に以下に説明する構造の概略に従うことがほとんどです。
.Bl -tag -width ".SH 名称"
.It ".TH" Ar title Op Ar section-number
マニュアルページの最初のマクロリクエストは、\&.TH でなくてはなりません。
このリクエストを使用することで、マニュアルページのタイトルと名称が決定できます。
\&.TH リクエストでは、マニュアルページのセクション番号も決定できます。
.It ".SH NAME"
コマンドを呼び出す名前、または名前のリストの後には、ダッシュ
.Pq Dq -
とコマンドの動作の要約を一行で続けます。このセクションには
.Nm troff
コマンド、エスケープシーケンス、マクロリクエストを一切置いてはいけません。
この部分は、
.Xr whatis 1
コマンドが使用するデータベースを生成するために使用されます。
.It ".SH SYNOPSIS"
説明するコマンドや関数の用法の簡単な要約を書きます。
.Bl -tag -width "コマンド"
.It コマンド
コマンドと引数の構文を、コマンド行で入力するように記述します。書かれた通りに
入力しなければならない語はボールド体で表します。引数は斜体で
表します。このように引数とコマンド名を表す場合、たとえ文の始まりで
あっても、大文字にしてはいけません。
.Pp
構文上のシンボルとして使用するものはローマン体で表さなくてはなりません。
.Bl -tag -width "XXX"
.It "[]"
角括弧は、オプション扱いの引数を表す際に使用します。
.It "|"
垂直バーは、複数の選択肢から一つだけ選択することを表す際に使用します。垂直バーで区切った
リストの中の項目一つだけを選択すべきということです。
.It "..."
引数の後ろに省略符号を続ける場合、その引数が繰り返し指定可能で
あることを表します。角括弧で囲んだ式の後ろに省略符号を続ける場合、
角括弧内の式が繰り返し指定可能であることを表します。
.El
.It 関数
必要なデータの宣言もしくは
.Li "#include"
指示子を最初に置きます。その後ろに関数宣言を置きます。
.El
.It ".SH DESCRIPTION"
コマンドや関数の外部挙動の概要を記述します。それには、ファイルや
データとのやりとりや、標準入力、標準出力、標準エラー出力がどのように
扱われるかが含まれます。通常、内部挙動や実装の詳細をここでは示しません。
このセクションで解くべき疑問は、「これはなにをするのか?」もしくは、
「これは何のためのものか?」です。
.Pp
リテラルテキスト、ファイル名、リファレンスマニュアルの他の場所にある
項目への参照は、固定幅書体で表さねばなりません。引数は斜体を用いて
表さねばなりません。
.It ".SH OPTIONS"
オプションの一覧を、各オプションがコマンドの挙動にどのような
影響を与えるかの説明と共に与えます。
.It ".SH USAGE"
このセクションはオプションであり、サブコマンドの詳細な説明や、その
コマンドが理解する入力の文法を含めます。
.It ".SH RETURN VALUES"
ライブラリルーチンが呼び出し元へ返しうる戻り値の一覧と、それらの
値が返る原因となる条件を記述します。
.It ".SH EXIT STATUS"
.\" WORD: exit status		終了ステータス
そのコマンドが終了ステータス (exit status) として返す値の一覧と、それらの
値が返る原因となる条件を記述します。
.It ".SH FILES"
そのコマンドや関数に関連するファイルの一覧です。
.It ".SH SEE ALSO"
関連マニュアルページの一覧に続けて、他の参考となる刊行物の一覧を、
コンマで区切って並べます。
.It ".SH DIAGNOSTICS"
診断メッセージと対応する説明の一覧です。
.It ".SH BUGS"
既知の障害や使用上の制限があれば、それを記述します。
.El
.Sh 関連ファイル
.Bl -tag -width "/usr/share/lib/tmac/tmac.groff_an"
.It "/usr/share/lib/tmac/tmac.an"
.Nm
パッケージを定義する初期ファイル。
.It "/usr/share/lib/tmac/tmac.groff_an"
マクロ定義のための
.Nm groff
のソース。
.It "/usr/share/lib/tmac/man.local"
.Nm
パッケージに対するローカルな変更。
.El
.Sh 関連項目
.Xr apropos 1 ,
.Xr groff 1 ,
.Xr man 1 ,
.Xr nroff 1 ,
.Xr troff 1 ,
.Xr whatis 1 ,
.Xr mdoc 7 ,
.Xr mdoc.samples 7
.Sh 歴史
このマニュアルページは
.An "Joseph Koshy"
.Ad Aq jkoshy@freebsd.org
によって記述されました。
.Sh 訳注
この日本語訳マニュアルページにおけるセクションタイトルの英和対応は次の
とおりです。
.Bl -column "RETURN VALUES" "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent
.It Em 英文 Ta Em 和訳
.It NAME Ta 名称
.It SYNOPSIS Ta 書式
.It DESCRIPTION Ta 解説
.It OPTIONS Ta オプション
.It USAGE Ta 使用法
.It RETURN VALUES Ta 戻り値
.It EXIT STATUS Ta 終了ステータス
.It FILES Ta 関連ファイル
.It SEE ALSO Ta 関連項目
.It DIAGNOSTICS Ta 診断
.It BUGS Ta バグ
.El
.\"ZZZ: 3.0-19990129-SNAP by Norihiro Kumagai