NAME¶

總覽 SYNOPSIS¶

groff -Tps -man file ...

man [section] title

描述 DESCRIPTION¶

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

導言 PREAMBLE¶

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

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

段 SECTIONS¶

其他約定段的內容應爲：

總覽 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¶

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

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

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

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

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

.B

黑體

.BI

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

.BR

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

.I

下劃線（或斜體）

.IB

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

.IR

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

.RB

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

.RI

小號字和黑體交替

.SB

小號字和黑體交替

.SM

小號字（用於縮寫）

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

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

安全子集 SAFE SUBSET¶

你還可能使用 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¶

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 可以檢測到這一點。 不過，你或許想要包含這些信息以使其可以在其他系統得到處理。 下面是預處理調用的定義：

e

eqn(1)

g

grap(1)

p

pic(1)

r

refer(1)

t

tbl(1)

v

vgrind(1)

文件 FILES¶

BUGS¶

The Sun macro TX 下不能用。

作者 AUTHOR S¶

—

James Clark (jjc@jclark.com) wrote the implementation of the macro package.

—

Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of this manual page.

—

Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO (which influenced this manual page).

—

David A. Wheeler (dwheeler@ida.org) heavily modified this manual page, such as adding detailed information on sections and macros.

參見 SEE ALSO¶

[中文版維護人]¶

[中文版最新更新]¶

《中國linux論壇man手冊翻譯計劃》:¶

跋¶