man

總覽 SYNOPSIS

groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title

描述 DESCRIPTION

此手冊頁解釋了 groff tmac.man 宏包 (通常叫做 man 宏包) 以及相關的建立手冊頁的慣例。開發者可以使用這個宏包來為 linux 書寫或移植手冊文件。它與其他版本的這個宏包一般是相容的，因此移植不是一個大問題 (但是 NET-2 BSD 釋出中使用了一個完全不同的宏包叫做 mdoc，參見 mdoc(7)).

注意 NET-2 BSD mdoc 手冊頁也可以使用 groff 處理，只要指定 -mdoc 選項而不是 -man 選項。推薦使用 -mandoc 選項，因為這樣會自動判斷應當使用哪一個。

導言 PREAMBLE

一篇手冊頁的第一個命令 (註釋行之後) 應當是

.TH title section date source manual,

這裡：

title: 手冊頁的標題 (例如， MAN).

section: 手冊頁的章節號應當放在這裡 (例如， 7).

date: 最後修改日期 -- 記住要在每次修改過此手冊頁之後修改它，這樣可以方便地進行版本控制

source: 命令的來源對於二進位制檔案，使用這樣的表述： GNU, NET-2, SLS Distribution, MCC Distribution. 對於系統呼叫，使用它適用的核心版本來表述： Linux 0.99.11. 對於庫呼叫，使用函式的來源來表述： GNU, BSD 4.3, Linux DLL 4.4.1.

manual: 手冊的標題 (例如： Linux Programmer's Manual).

注意 BSD mdoc 格式的手冊頁以 Dd 命令開始，而不是 TH 命令

手冊章節傳統上如下定義：

1 Commands: 使用者可從 shell 執行的命令

2 System calls: 必須由核心完成的功能

3 Library calls: 大多數 libc 函式，例如 qsort(3))

4 Special files: /dev) 目錄中的檔案

5 File formats and conventions: /etc/passwd 等人類可讀的檔案的格式說明

6 Games

7 Macro packages and conventions: 檔案系統標準描述，網路協議，ASCII 和其他字符集，還有你眼前這份文件以及其他東西

8 System management commands: 類似 mount(8) 等命令，大部分只能由 root 執行

9 Kernel routines: 這是廢棄的章節。原來曾想把一些關於核心的檔案放在這裡，但是實際上只有極少數可以寫成檔案放在這裡，而且它們也很快過時了。核心開發者可以找到其他更好的資源。

段以 .SH 開始，後跟標題名。如果標題包含空格並且和 .SH 在同一行，則需在標題上加雙引號。傳統的或建議的標題包括： NAME, 總覽 SYNOPSIS, 描述 DESCRIPTION, 返回值 RETURN VALUE, 退出狀態 EXIT STATUS, 錯誤處理 ERROR HANDLING, 錯誤 ERRORS, 選項 OPTIONS, 用法 USAGE, 示例 EXAMPLES, 檔案 FILES, 環境 ENVIRONMENT, 診斷 DIAGNOSTICS, 安全 SECURITY, 遵循 CONFORMING TO, 注意 NOTES, BUGS, 作者 AUTHOR, 和參見 SEE ALSO. 在適合使用約定標題的地方，請使用它；這樣做可以使文章更易讀、易懂。不過，只要您的標題能夠增加易懂性，請放心使用。唯一必須的標題是 NAME, 他應是手冊頁的第一段，後面應緊跟對該命令的簡單描述。比如：

.SH NAME

chess \- the game of chess

請一定要按照這個格式來寫，注意在短橫線 (dash `-') 前要有個斜槓 (slash `´). 這種語法結構在 makewhatis(8) 程式為 whatis(1) 和 apropos(1) 命令建立簡短命令描述時要用到。

其他約定段的內容應為：

總覽 SYNOPSIS: 簡要描述命令或函式介面。對命令，顯示他的命令和引數（包括各種選項）；黑體表示各種引數，下劃線（或斜體字）表示可以替換的選項；方括號[]中的是可選項，豎線 | 用於把幾個選項間隔開，小括號()中的部分可以自動重複。對函式，顯示需要的資料宣告或需 #include 包含的專案，後跟函式宣告。

描述 DESCRIPTION: 解釋命令、函式或格式的用途。說明其如何與檔案及標準輸入互動，他們的標準輸出及標準錯誤。必須要指明的細節。描述一般情況。選項和引數資訊放在 OPTIONS（選項）段。如果有語法說明和一些複雜的設定，建議把它們放到 USAGE（用法）段（本段中最好只寫一個概要）。

返回值 RETURN VALUE: 列出程式或函式會返回的值，指出引發返回值的條件或原因。

退出狀態 EXIT STATUS: 列出可能的退出狀態的值，指出引起返回的程式或原因。

選項 OPTIONS: 指出程式可用的選項，及其作用。

用法 USAGE: 描述程式的較高階的使用方法。

示例 EXAMPLES: provides one or more examples describing how this function, file or command is used.

檔案 FILES: 列出程式或函式使用到的檔案，比如配置檔案、啟動檔案和程式直接操作的檔案。給出檔案的絕對路徑，使用安裝程式調整這些路徑以使其與使用者的實際情況相符。對大多數程式來說，預設的安裝路徑是 /usr/local，所以你的檔案要與此一致。

環境 ENVIRONMENT: 列出影響你的程式的所有環境變數，並說明影響的原因。

診斷 DIAGNOSTICS: 寫出常會出現的錯誤概述，並說明解決的辦法。你無需解釋系統錯誤資訊或訊號，除非它們會影響到您的程式。

安全 SECURITY: 討論安全問題和相關話題。對應予避免的配置和環境，可能有安全隱患的命令等等給出警告，特別是當它們不是很明顯時。單獨用一段來討論安全並不必要；如果比較好理解的話，把它放在其他段中（比如描述或用法段）。但是，最好加上它。

遵循 CONFORMING TO: 描述它實現的任何標準或約定

注意 NOTES: 提供雜項注意事項

BUGS: 列出侷限、已知的缺點或不便之處，還有其他可能存在的問題。

作者 AUTHOR: 列出程式或檔案作者，聯絡辦法等。

參見 SEE ALSO: 以字母順序列出相關的手冊頁（man pages)。通常來講，這是一個手冊頁的最後一段。

字型 FONTS

雖然在 UNIX 世界中有各種對手冊頁（man pages)的不同約定，但在 linux 系統下存在一個字型的標準：

: 對函式，其引數通常用下劃線（或斜體）， 在總覽（SYNOPSIS)中也是這樣 ，其他部分用黑體。例如

int myfunction(int argc, char **argv);

: 檔名用下劃線（或斜體），例如，.IR "/usr/include/stdio.h" ), 但在總覽（SYNOPSIS)中，包含的檔案用黑體，例如 #include <stdio.h>).

: 專用宏，一般大寫表示，用黑體（如： MAXINT).

: 列舉錯誤代號時，代號用黑體（這種列舉通常使用 .TP 宏命令）。

: 對其他手冊頁的引用（或本頁中某主體的引用）用黑體。手冊章節號用普通體（如： ). 設定字型的宏命令如下：

.B: 黑體

.BI: 黑體和下劃線（或斜體）交替（描述函式時非常有用）

.BR: 黑體和普通體交替（描述引用時非常有用）

.I: 下劃線（或斜體）

.IB: 下劃線（或斜體）和黑體交替

.IR: 普通體和下劃線（或斜體）交替

.RB: 普通體和下劃線（或斜體）交替

.RI: 小號字和黑體交替

.SB: 小號字和黑體交替

.SM: 小號字（用於縮寫）

按照慣例，每個命令最多可以有六個小節的引數，但是 GNU 去除了這個限制。小節之間以空格隔開。如果某小節含有空格，則需要給其加上雙引號。各小節在顯示時無間隔，所以 .BR 命令可以指定一個黑體的詞，後跟一個普通體的標點。如果命令後無引數，則命令作用於下一行。

其他宏命令和字串 OTHER MACROS AND STRINGS

下面是其他一些相關的宏和預定義的字串。除非指明，否則所有的宏在本行文字結束時終止。多數宏使用“流行縮排”（prevailing indent)方式。 “流行縮排”的值由緊跟著宏命令的 i 值指定，如果不指定，那就會使用當前的“流行縮排”值。這樣，連續的縮排段就可使用相同的縮排值而不需要重新指定。普通段（不縮排）將“流行縮排”值重值為預設值（0.5 英寸）。預設時，縮排是有規則的 en(s)：用 en(s) 或者 em(s) 作為縮排的單位，因為它們會自動地調整字型的大小。 (注：度量距離有不同的單位，當請求需要用到不同的距離時，可以使用預設型別來修飾數字，度量單位是英寸，釐米，pica,en,em,點，unit和垂直行距。 1pica等於1/6英寸，1em等於字母m的寬度，預設寬度取決於troff中使用的字型。En是em的一半。) 其他宏命令定義如下：

普通段（無縮排） Normal Paragraphs

.LP: 與 .PP 相同（開始一個新段）

.P: 與 .PP 相同（開始一個新段）

.PP: 開始一個新段，重置“流行縮排”值。

相對縮排 Relative Margin Indent

.RS i: 開始相對縮排 -- 把左邊界右移 i
(如果不指定 i 值，則使用“流行縮排”值）。同時設定“流行縮排”值為 0.5 英寸。直到使用 .RE 結束這些設定。

.RE: 結束相對縮排同時把“流行縮排”恢復原值。

縮排 Indented Paragraph Macros

.HP i: 開始懸掛式縮排（段的第一行從左邊揭開時，其餘縮排顯示）

.IP x i: 在段上標籤 x 。如果不指定 x ，則整個段縮排 i 。如果指定了 x ，則 x 之前的段不縮排，之後的段縮排（有些象 .TP ，不過 x 是跟在命令後面而不是在下一行）。如果 x 太長，後面的文字會挪到下一行（文字不會丟失或割斷）。

做公告列表，可以用 \(bu (bullet) 或 \(em (em dash). 要用數字或字母列表, 可以用.IP 1. 或 .IP A. 這樣轉換成其他格式就簡單了。

.TP i: 在段上懸掛標籤。標籤在下一行指定，但是結果和 .IP 相像。

超文字連結宏 Hypertext Link Macros

.UR u: 建立一個超文字連結到 URI (URL) u; 並以 UE 結束。當轉換為 HTML 格式時，他會轉換為 <A HREF="u">. 有個例外：如果 u 是特殊字元 “ ：”，則之後不能建立任何超級連結，直到以 UE 結束（這用來在不需要超級連結時禁止他）。 : LALR(1)

這個宏比較新，很多程式可能並不對他進行處理。但是由於很多工具 (包括 troff) 簡單地忽略未定義宏 (或者最壞的將它們插入到文字中), 插入它們是安全的

.UE: 結束相應的 UR 超級連結。轉換為HTML後是 </A>.

.UN u: 給超級聯接指定名稱為 u; 不需要以 UE UE 結束。轉換為 HTML 後為： <A NAME="u" id=" u"> </A> (the   is optional if support for Mosaic is unneeded).

雜項宏 Miscellaneous Macros

.DT: 重置 tab 值為預設(每一個0.5英寸)。不引起中斷。

.IX ...: 插入索引資訊（方便搜尋系統工作，或列印索引列表）。在頁中索引資訊不能正常顯示。如果只有一個引數，引數作為獨立的索引項指向手冊頁的內容。如果有兩個引數，他可能是 Perl 手冊頁格式；第一個引數指定型別名（命令名，標題，題頭，子段貨源素之一），第二個引數指明自己的索引名。另外，長索引形式：每個引數是一個索引項，次級索引項，再次級索引項，等等直到以空引數結束，然後是程式名引數，\m，還有一小段描述。還可能在跟上一個空引數，有可能是頁控制資訊（如： PAGE START)。舉例如下： "programmingtools""make""""make— build programs".

.PD d: 在段中間垂直距離空開 d (如果不指定，則預設為 d=0.4v)，不引起中斷。

.SS t: 子標題 t 象是 .SH, 但是作為段中的字標題使用）

預定義字串 Predefined Strings

man 預定義了下列字串

\*R: 註冊符號: ®

\*S: 改變成預設字型大小

\*(Tm: 商標符號: (Tm)

\*(lq: 左雙引號: “

\*(rq: 右雙引號: ”

安全子集 SAFE SUBSET

理論上 man 是一個 troff 宏命令包，實際上很多工具程式沒有支援所有的 man 宏命令。因此，為了這些程式可以正常工作最好忽略 troff 的一些比較另類的宏。避免使用各種不同的 troff 預處理程式（如果必須的話，用 tbl(1) 吧，但是在建立雙列表時請使用 IP 和 TP 命令）。避免使用計算；大多數其他程式不能處理他。使用簡單的命令比較容易轉換為其他格式。下面的宏命令一般認為是安全的（雖然多數時候他們都被忽略了）： \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.

你還可能使用 troff 跳脫字元（這些轉移符號以 \ 開始）。但你要在文字中顯示反斜線時，用\e。其他跳脫字元包括： \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, 和 \f(xx. 其中 x、xx 是任意字元，N 是任意數字不要使用跳脫字元來畫圖。

不要隨意使用 bp （break page(中斷頁））。 sp （vertical space(垂直距離）只應使用正值。不要用 (de) （define（定義）定義與現有的宏同名的宏（無論 man 或 mdoc)；這種重新定義可能會被忽略。每個正縮排 (in) 應對應一個負縮排（即使在使用 RS 和 RE 是也不例外）。 The condition test (if,ie) should only have 't' or 'n' as the condition. 可以使用的只有可忽略的轉換 (tr). 改變字型命令 (ft 和 \f 轉義序列) 只能帶如下引數： 1, 2, 3, 4, R, I, B, P, or CW (ft 命令也可以不帶引數)。

如果你是用更多的功能，用各種程式仔細察看一下結果。如果你肯定某功能是安全的，請告訴我們，以便把他增加到這個列表中。

注意 NOTES

儘量在文字中包含完整的 URL（或URIs）；一些工具軟體（如： man2html(1) ）能夠自動把它們轉換為超級連結。您也可用 UR 命令指定連結到相關資訊。輸入完整的 URL(如：<http://www.kernel-notes.org> )。

Tools processing these files should open the file and examine the first non-whitespace character. 以(.)或（')開始一行，表明是基於 troff 的檔案（如： man 或 mdoc)。如果是（<）表明基於 SGML/XML (如：HTML 或 Docbook)．其他可能是純文字。(例如 "catman" 的結果)

有些 man 以'\"和空格再加字元列開始，表示他的預處理方法。為了 troff 翻譯器程式處理起來簡單一些，您僅應使用 tbl(1), 而不是其他什麼東東，Linux 可以檢測到這一點。不過，你或許想要包含這些資訊以使其可以在其他系統得到處理。下面是預處理呼叫的定義：