Man ページ

マニュアルページはソフトウェアとともにインストールされるリファレンス文書です。セクション番号で対象を区別します。セクション 1 はユーザーコマンド、2 はシステムコール、3 はライブラリ関数、4 はデバイスと特殊ファイル、5 はファイル形式と規約、7 は概要とプロトコル、8 は管理コマンドを記載します。セクションを指定した検索で目的のページを選択します。

man 2 open
man 3 printf
man 5 passwd

セクション、名前、概要 #

同じ名前がコマンド、関数、ファイルを表すことがあるため、名前とセクションの両方でページを選択します。ページソースとインストール済みファイル名は、printf.1 や printf.3 のように慣例的に name.section を使用します。NAME セクションには name \- one-line description を記載し、apropos などのツールがその行を索引化します。SYNOPSIS は、コマンドにはコマンドライン表記を、API には宣言表記を使用します。

慣例的なセクションには NAME、SYNOPSIS、DESCRIPTION、OPTIONS または PARAMETERS、RETURN VALUE、ERRORS、ENVIRONMENT、FILES、ATTRIBUTES、STANDARDS、HISTORY または VERSIONS、EXAMPLES、NOTES、BUGS、SEE ALSO、AUTHORS があります。該当するセクションだけを含めますが、暗黙にせず、観測可能な失敗と互換性の境界を記載します。Linux API ページでは ATTRIBUTES を使ってスレッド安全性などの特性を記録します。

roff による作成 #

マニュアルページは、意味構造を持つ mdoc マクロパッケージまたは man マクロパッケージによる roff 入力を使用します。mandoc(1) は両方の形式を解析、検証、レンダリングします。mdoc の語彙は関数名、オプション、引数、相互参照などの意味構造を記録し、端末、HTML、PostScript で一貫した出力を可能にします。

A minimal mdoc document identifies its name, synopsis, description, options, exit status, and references:

.Dd August 7, 2026
.Dt EXAMPLE 1
.Os
.Sh NAME
.Nm example
.Nd print an example message
.Sh SYNOPSIS
.Nm
.Op Fl q
.Sh DESCRIPTION
The .Nm utility writes a message to standard output.

roff 入力行の先頭では、. と ' がリクエストを導入します。リテラルの先頭制御文字は \& でエスケープします。リテラルのバックスラッシュは \(rs またはマクロパッケージで文書化されたエスケープで記述し、コマンドオプションの意味上のマイナス記号には \- を使用します。フォント変更よりも mdoc の .Fl、.Ar、.Fn、.Xr などの意味マクロを優先します。レンダラーが出力形式間で意味を保持できるためです。

Cross-references identify both name and section, for example .Xr open 2 in mdoc or open(2) in man markup. The SEE ALSO list should cite the command, API, configuration file, or specification that defines related behavior.

リントとレンダリング #

mandoc -T lint file.1 で構造上の問題を検出し、mandoc -T utf8 file.1 で端末出力を確認します。GNU roff では groff -man -Tutf8 file.1 または groff -mdoc -Tutf8 file.1 が対応するマクロ言語をレンダリングします。ソースメタデータからページを生成するプロジェクトでも、生成入力がマクロ構文やエスケープ規則に違反する可能性があるため、検証済みのレンダリング経路が必要です。

Linux man-pages プロジェクトは、Linux カーネルのユーザー空間 ABI と多数の libc インターフェイスを文書化します。各パッケージは、自身のコマンドとファイル形式のドキュメントを管理します。規格、最初に適用されるバージョン、相違点、エラー条件、スレッド安全性の特性は、1 台のマシンから推測せず、責任を持つ上流ソースから記録します。