手冊頁

手冊頁是隨軟體安裝的參考文件。區段編號區分主題：第 1 節記錄使用者命令，第 2 節記錄系統呼叫，第 3 節記錄函式庫函式，第 4 節記錄裝置與特殊檔案，第 5 節記錄檔案格式與慣例，第 7 節記錄概觀與通訊協定，第 8 節記錄管理命令。限定區段可選取預期的頁面：

man 2 open
man 3 printf
man 5 passwd

區段、名稱與概要 #

請同時依名稱與區段選取頁面，因為相同名稱可能描述命令、函式或檔案。頁面原始碼與安裝後的檔名慣例上使用 name.section，例如 printf.1 與 printf.3。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 撰寫 #

手冊頁使用 roff 輸入，可搭配語意化的 mdoc 巨集套件或 man 巨集套件。mandoc(1) 會剖析、驗證並轉譯兩種格式。mdoc 詞彙記錄函式名稱、選項、引數與交叉參照等語意結構，因此能一致地輸出終端機、HTML 與 PostScript。

最小的 mdoc 文件會識別其名稱、概要、描述、選項、結束狀態與參考資料：

.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 等語意巨集，而不要變更字型，因為轉譯器能在不同輸出格式中保留語意。

交叉參照同時識別名稱與區段，例如 mdoc 中的 .Xr open 2，或 man 標記中的 open(2)。SEE ALSO 清單應引用定義相關行為的命令、API、設定檔或規格。

Lint 與轉譯 #

使用 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 介面。個別套件負責其命令與檔案格式的文件。請從負責的上游來源記錄標準、第一個適用版本、偏差、錯誤條件與執行緒安全性，而不要從單一機器推斷。