NAME

man - 格式化手冊(cè)頁(yè)的宏  

總覽 SYNOPSIS

groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title  

描述 DESCRIPTION

此手冊(cè)頁(yè)解釋了 groff tmac.man 宏包 (通常叫做 man 宏包) 以及相關(guān)的創(chuàng)建手冊(cè)頁(yè)的慣例。開(kāi)發(fā)者可以使用這個(gè)宏包來(lái)為 linux 書(shū)寫(xiě)或移植手冊(cè)文檔。它與其他版本的這個(gè)宏包一般是兼容的，因此移植不是一個(gè)大問(wèn)題 (但是 NET-2 BSD 發(fā)布中使用了一個(gè)完全不同的宏包叫做 mdoc，參見(jiàn) mdoc(7)).

注意 NET-2 BSD mdoc 手冊(cè)頁(yè)也可以使用 groff 處理，只要指定 -mdoc 選項(xiàng)而不是 -man 選項(xiàng)。推薦使用 -mandoc 選項(xiàng)，因?yàn)檫@樣會(huì)自動(dòng)判斷應(yīng)當(dāng)使用哪一個(gè)。  

導(dǎo)言 PREAMBLE

一篇手冊(cè)頁(yè)的第一個(gè)命令 (注釋行之后) 應(yīng)當(dāng)是

.TH title section date source manual,

這里：

title

手冊(cè)頁(yè)的標(biāo)題 (例如， MAN).

section

手冊(cè)頁(yè)的章節(jié)號(hào)應(yīng)當(dāng)放在這里 (例如， 7).

date

最后修改日期 -- 記住要在每次修改過(guò)此手冊(cè)頁(yè)之后修改它，這樣可以方便地進(jìn)行版本控制

source

命令的來(lái)源

對(duì)于二進(jìn)制文件，使用這樣的表述： GNU, NET-2, SLS Distribution, MCC Distribution.

對(duì)于系統(tǒng)調(diào)用，使用它適用的內(nèi)核版本來(lái)表述： Linux 0.99.11.

對(duì)于庫(kù)調(diào)用，使用函數(shù)的來(lái)源來(lái)表述： GNU, BSD 4.3, Linux DLL 4.4.1.

manual

手冊(cè)的標(biāo)題 (例如： Linux Programmer's Manual).

注意 BSD mdoc 格式的手冊(cè)頁(yè)以 Dd 命令開(kāi)始，而不是 TH 命令

手冊(cè)章節(jié)傳統(tǒng)上如下定義：

1 Commands

用戶(hù)可從 shell 運(yùn)行的命令

2 System calls

必須由內(nèi)核完成的功能

3 Library calls

大多數(shù) libc 函數(shù)，例如 qsort(3))

4 Special files

/dev) 目錄中的文件

5 File formats and conventions

/etc/passwd 等人類(lèi)可讀的文件的格式說(shuō)明

6 Games

7 Macro packages and conventions

文件系統(tǒng)標(biāo)準(zhǔn)描述，網(wǎng)絡(luò)協(xié)議，ASCII 和其他字符集，還有你眼前這份文檔以及其他東西

8 System management commands

類(lèi)似 mount(8) 等命令，大部分只能由 root 執(zhí)行

9 Kernel routines

這是廢棄的章節(jié)。原來(lái)曾想把一些關(guān)于核心的文件放在這里，但是實(shí)際上只有極少數(shù)可以寫(xiě)成文件放在這里，而且它們也很快過(guò)時(shí)了。核心開(kāi)發(fā)者可以找到其他更好的資源。

段 SECTIONS

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

.SH NAME
chess \- the game of chess

請(qǐng)一定要按照這個(gè)格式來(lái)寫(xiě)，注意在短橫線(xiàn) (dash `-') 前要有個(gè)斜杠 (slash `'). 這種語(yǔ)法結(jié)構(gòu)在 makewhatis(8) 程序?yàn)?whatis(1) 和 apropos(1) 命令建立簡(jiǎn)短命令描述時(shí)要用到。

其他約定段的內(nèi)容應(yīng)為：

總覽 SYNOPSIS

簡(jiǎn)要描述命令或函數(shù)接口。對(duì)命令，顯示他的命令和參數(shù)（包括各種選項(xiàng)）；黑體表示各種參數(shù)，下劃線(xiàn)（或斜體字）表示可以替換的選項(xiàng)；方括號(hào)[]中的是可選項(xiàng)，豎線(xiàn) | 用于把幾個(gè)選項(xiàng)間隔開(kāi)，小括號(hào)()中的部分可以自動(dòng)重復(fù)。對(duì)函數(shù)，顯示需要的數(shù)據(jù)聲明或需 #include 包含的項(xiàng)目，后跟函數(shù)聲明。

描述 DESCRIPTION

解釋命令、函數(shù)或格式的用途。說(shuō)明其如何與文件及標(biāo)準(zhǔn)輸入交互，他們的標(biāo)準(zhǔn)輸出及標(biāo)準(zhǔn)錯(cuò)誤。必須要指明的細(xì)節(jié)。描述一般情況。選項(xiàng)和參數(shù)信息放在 OPTIONS（選項(xiàng)）段。如果有語(yǔ)法說(shuō)明和一些復(fù)雜的設(shè)定，建議把它們放到 USAGE（用法）段（本段中最好只寫(xiě)一個(gè)概要）。

返回值 RETURN VALUE

列出程序或函數(shù)會(huì)返回的值，指出引發(fā)返回值的條件或原因。

退出狀態(tài) EXIT STATUS

列出可能的退出狀態(tài)的值，指出引起返回的程序或原因。

選項(xiàng) OPTIONS

指出程序可用的選項(xiàng)，及其作用。

用法 USAGE

描述程序的較高級(jí)的使用方法。

示例 EXAMPLES

provides one or more examples describing how this function, file or command is used.

文件 FILES

列出程序或函數(shù)使用到的文件，比如配置文件、啟動(dòng)文件和程序直接操作的文件。給出文件的絕對(duì)路徑，使用安裝程序調(diào)整這些路徑以使其與用戶(hù)的實(shí)際情況相符。對(duì)大多數(shù)程序來(lái)說(shuō)，缺省的安裝路徑是 /usr/local，所以你的文件要與此一致。

環(huán)境 ENVIRONMENT

列出影響你的程序的所有環(huán)境變量，并說(shuō)明影響的原因。

診斷 DIAGNOSTICS

寫(xiě)出常會(huì)出現(xiàn)的錯(cuò)誤概述，并說(shuō)明解決的辦法。你無(wú)需解釋系統(tǒng)錯(cuò)誤信息或信號(hào)，除非它們會(huì)影響到您的程序。

安全 SECURITY

討論安全問(wèn)題和相關(guān)話(huà)題。對(duì)應(yīng)予避免的配置和環(huán)境，可能有安全隱患的命令等等給出警告，特別是當(dāng)它們不是很明顯時(shí)。單獨(dú)用一段來(lái)討論安全并不必要；如果比較好理解的話(huà)，把它放在其他段中（比如 描述 或 用法 段）。但是，最好加上它。

遵循 CONFORMING TO

描述它實(shí)現(xiàn)的任何標(biāo)準(zhǔn)或約定

注意 NOTES

提供雜項(xiàng)注意事項(xiàng)

BUGS

列出局限、已知的缺點(diǎn)或不便之處，還有其他可能存在的問(wèn)題。

作者 AUTHOR

列出程序或文件作者，聯(lián)系辦法等。

參見(jiàn) SEE ALSO

以字母順序列出相關(guān)的手冊(cè)頁(yè)（man pages)。通常來(lái)講，這是一個(gè)手冊(cè)頁(yè)的最后一段。

字體 FONTS

雖然在 UNIX 世界中有各種對(duì)手冊(cè)頁(yè)（man pages)的不同約定，但在 linux 系統(tǒng)下存在一個(gè)字體的標(biāo)準(zhǔn)：

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

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

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

專(zhuān)用宏，一般大寫(xiě)表示，用黑體（如： MAXINT).

列舉錯(cuò)誤代號(hào)時(shí)，代號(hào)用黑體（這種列舉通常使用 .TP 宏命令）。

對(duì)其他手冊(cè)頁(yè)的引用（或本頁(yè)中某主體的引用）用黑體。手冊(cè)章節(jié)號(hào)用普通體（如： man(7)). 設(shè)置字體的宏命令如下：

.B

黑體

.BI

黑體和下劃線(xiàn)（或斜體）交替（描述函數(shù)時(shí)非常有用）

.BR

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

.I

下劃線(xiàn)（或斜體）

.IB

下劃線(xiàn)（或斜體）和黑體交替

.IR

普通體和下劃線(xiàn)（或斜體）交替

.RB

普通體和下劃線(xiàn)（或斜體）交替

.RI

小號(hào)字和黑體交替

.SB

小號(hào)字和黑體交替

.SM

小號(hào)字（用于縮寫(xiě)）

按照慣例，每個(gè)命令最多可以有六個(gè)小節(jié)的參數(shù)，但是 GNU 去除了這個(gè)限制。小節(jié)之間以空格隔開(kāi)。如果某小節(jié)含有空格，則需要給其加上雙引號(hào)。各小節(jié)在顯示時(shí)無(wú)間隔，所以 .BR 命令可以指定一個(gè)黑體的詞，后跟一個(gè)普通體的標(biāo)點(diǎn)。如果命令后無(wú)參數(shù)，則命令作用于下一行。  

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

下面是其他一些相關(guān)的宏和預(yù)定義的字符串。除非指明，否則所有的宏在本行文本結(jié)束時(shí)終止。多數(shù)宏使用“流行縮進(jìn)”（prevailing indent)方式。 “流行縮進(jìn)”的值由緊跟著宏命令的 i 值指定，如果不指定，那就會(huì)使用當(dāng)前的“流行縮進(jìn)”值。這樣，連續(xù)的縮進(jìn)段就可使用相同的縮進(jìn)值而不需要重新指定。普通段（不縮進(jìn)）將“流行縮進(jìn)”值重值為缺省值（0.5 英寸）。缺省時(shí)，縮進(jìn)是有規(guī)則的 en(s)：用 en(s) 或者 em(s) 作為縮進(jìn)的單位，因?yàn)樗鼈儠?huì)自動(dòng)地調(diào)整字體的大小。 (注：度量距離有不同的單位，當(dāng)請(qǐng)求需要用到不同的距離時(shí)，可以使用默認(rèn)類(lèi)型來(lái)修飾數(shù)字，度量單位是英寸，厘米，pica,en,em,點(diǎn)，unit和垂直行距。 1pica等于1/6英寸，1em等于字母m的寬度，默認(rèn)寬度取決于troff中使用的字體。En是em的一半。) 其他宏命令定義如下：  

普通段（無(wú)縮進(jìn)） Normal Paragraphs

.LP

與 .PP 相同（開(kāi)始一個(gè)新段）

.P

與 .PP 相同（開(kāi)始一個(gè)新段）

.PP

開(kāi)始一個(gè)新段，重置“流行縮進(jìn)”值。

相對(duì)縮進(jìn) Relative Margin Indent

.RS i

開(kāi)始相對(duì)縮進(jìn) -- 把左邊界右移 i
 (如果不指定  i 值，則使用“流行縮進(jìn)”值 ）。同時(shí)設(shè)定“流行縮進(jìn)”值為 0.5 英寸。直到使用 .RE 結(jié)束這些設(shè)定。

.RE

結(jié)束相對(duì)縮進(jìn)同時(shí)把“流行縮進(jìn)”恢復(fù)原值。

縮進(jìn) Indented Paragraph Macros

.HP i

開(kāi)始懸掛式縮進(jìn)（段的第一行從左邊揭開(kāi)時(shí)，其余縮進(jìn)顯示）

.IP x i

在段上標(biāo)簽 x 。如果不指定 x ，則整個(gè)段縮進(jìn) i 。如果指定了 x ，則 x 之前的段不縮進(jìn)，之后的段縮進(jìn)（有些象 .TP ，不過(guò) x 是跟在命令后面而不是在下一行）。如果 x 太長(zhǎng)，后面的文本會(huì)挪到下一行（文本不會(huì)丟 失或割斷）。

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

.TP i

在段上懸掛標(biāo)簽。標(biāo)簽在下一行指定，但是結(jié)果和 .IP 相像。

超文本鏈接宏 Hypertext Link Macros

.UR u

建立一個(gè)超文本鏈接到 URI (URL) u; 并以 UE 結(jié)束。當(dāng)轉(zhuǎn)換為 HTML 格式時(shí)，他會(huì)轉(zhuǎn)換為 <A HREF="u">. 有個(gè)例外：如果 u 是特殊字符 “ ：”，則之后不能建立任何超級(jí)鏈接，直到以 UE 結(jié)束（這用來(lái)在不需要超級(jí)鏈接時(shí)禁止他）。 LALR(1) 這個(gè)宏比較新，很多程序可能并不對(duì)他進(jìn)行處理。但是由于很多工具 (包括 troff) 簡(jiǎn)單地忽略未定義宏 (或者最壞的將它們插入到文本中), 插入它們是安全的

.UE

結(jié)束相應(yīng)的 UR 超級(jí)鏈接。轉(zhuǎn)換為HTML后是 </A>.

.UN u

給超級(jí)聯(lián)接指定名稱(chēng)為 u; 不需要以 UE UE 結(jié)束。轉(zhuǎn)換為 HTML 后為： <A NAME="u" id="u">&nbsp;</A> (the &nbsp; is optional if support for Mosaic is unneeded).

雜項(xiàng)宏 Miscellaneous Macros

.DT

重置 tab 值為缺省(每一個(gè)0.5英寸)。不引起中斷。

.IX ...

插入索引信息（方便搜索系統(tǒng)工作，或打印索引列表）。在頁(yè)中索引信息不能正常顯示。如果只有一個(gè)參數(shù)，參數(shù)作為獨(dú)立的索引項(xiàng)指向手冊(cè)頁(yè)的內(nèi)容。如果有兩個(gè)參數(shù)，他可能是 Perl 手冊(cè)頁(yè)格式；第一個(gè)參數(shù)指定類(lèi)型名（命令名，標(biāo)題 ，題頭，子段貨源素之一），第二個(gè)參數(shù)指明自己的索引名。另外，長(zhǎng)索引形式：每個(gè)參數(shù)是一個(gè)索引項(xiàng)，次級(jí)索引項(xiàng)，再次級(jí)索引項(xiàng)，等等直到以空參數(shù)結(jié)束，然后是程序名參數(shù)，\m，還有一小段描述。還可能在跟上一個(gè)空參數(shù)，有可能是頁(yè)控制信息（如： PAGE START)。舉例如下： "programmingtools""make""""make--- build programs".

.PD d

在段中間垂直距離空開(kāi) d (如果不指定，則缺省為 d=0.4v)，不引起中斷。

.SS t

子標(biāo)題 t 象是 .SH, 但是作為段中的字標(biāo)題使用）

預(yù)定義字符串 Predefined Strings

man 預(yù)定義了下列字符串

\*R

注冊(cè)符號(hào): ®

\*S

改變成缺省字體大小

\*(Tm

商標(biāo)符號(hào):

\*(lq

左雙引號(hào): ``

\*(rq

右雙引號(hào): ''

安全子集 SAFE SUBSET

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

你還可能使用 troff 轉(zhuǎn)義字符（這些轉(zhuǎn)移符號(hào)以 \ 開(kāi)始）。但你要在文本中顯示反斜線(xiàn)時(shí)，用\e。其他轉(zhuǎn)義字符包括： \', \`, \-, \., \ , \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, 和 \f(xx. 其中 x、xx 是任意字符，N 是任意數(shù)字不要使用轉(zhuǎn)義字符來(lái)畫(huà)圖。

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

如果你是用更多的功能，用各種程序仔細(xì)察看一下結(jié)果。如果你肯定某功能是安全的，請(qǐng)告訴我們，以便把他增加到這個(gè)列表中。  

注意 NOTES

盡量在文本中包含完整的 URL（或URIs）；一些工具軟件（如： man2html(1) ）能夠自動(dòng)把它們轉(zhuǎn)換為超級(jí)鏈接。您也可用 UR 命令指定鏈接到相關(guān)信息。輸入完整的 URL(如：<http://www.kernel-notes.org> )。

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

有些 man 以'\"和空格再加字符列開(kāi)始，表示他的預(yù)處理方法。為了 troff 翻譯器程序處理起來(lái)簡(jiǎn)單一些，您僅應(yīng)使用 tbl(1), 而不是其他什么東東，Linux 可以檢測(cè)到這一點(diǎn)。不過(guò)，你或許想要包含這些信息以使其可以在其他系統(tǒng)得到處理。下面是預(yù)處理調(diào)用的定義：

e

eqn(1)

g

grap(1)

p

pic(1)

r

refer(1)

t

tbl(1)

v

vgrind(1)

文件 FILES

/usr/share/groff/[*/]tmac/tmac.an
/usr/man/whatis  

BUGS

大多數(shù)宏命令描述的是格式（比如：字體和空格）而不是內(nèi)容描述（比如： 這段文字指向另外一頁(yè)），與 mdoc 和 DocBook 正好相反（HTML 也有比較多的內(nèi)容描述）。這使得 man 難以轉(zhuǎn)換為其他形式，不容易與其他文件組合或自動(dòng)插入交叉引用。遵照以上的安全說(shuō)明，就比較容易在將來(lái)把他轉(zhuǎn)換為其他格式。

The Sun macro TX 下不能用。  

作者 AUTHORS

---

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.

參見(jiàn) SEE ALSO

apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), whatis(1)

#p#

NAME

man - macros to format man pages  

SYNOPSIS

groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title  

DESCRIPTION

This manual page explains the groff tmac.an macro package (often called the man macro package) and related conventions for creating manual (man) pages. This macro package should be used by developers when writing or porting man pages for Linux. It is fairly compatible with other versions of this macro package, so porting man pages should not be a major problem (exceptions include the NET-2 BSD release, which uses a totally different macro package called mdoc; see mdoc(7)).

Note that NET-2 BSD mdoc man pages can be used with groff simply by specifying the -mdoc option instead of the -man option. Using the -mandoc option is, however, recommended, since this will automatically detect which macro package is in use.  

PREAMBLE

The first command in a man page (after comment lines) should be

.TH title section date source manual,

where:

title

The title of the man page (e.g., MAN).

section

The section number the man page should be placed in (e.g., 7).

date

The date of the last revision---remember to change this every time a change is made to the man page, since this is the most general way of doing version control.

source

The source of the command.

For binaries, use something like: GNU, NET-2, SLS Distribution, MCC Distribution.

For system calls, use the version of the kernel that you are currently looking at: Linux 0.99.11.

For library calls, use the source of the function: GNU, BSD 4.3, Linux DLL 4.4.1.

manual

The title of the manual (e.g., Linux Programmer's Manual).

Note that BSD mdoc-formatted pages begin with the Dd command, not the TH command.

The manual sections are traditionally defined as follows:

1 Commands

Those commands that can be executed by the user from within a shell.

2 System calls

Those functions which must be performed by the kernel.

3 Library calls

Most of the libc functions, such as qsort(3).

4 Special files

Files found in /dev.

5 File formats and conventions

The format for /etc/passwd and other human-readable files.

6 Games

7 Conventions and miscellaneous

A description of the standard file system layout, network protocols, ASCII and other character codes, this man page, and other things.

8 System management commands

Commands like mount(8), many of which only root can execute.

9 Kernel routines

This is an obsolete manual section. Once it was thought a good idea to document the Linux kernel here, but in fact very little has been documented, and the documentation that exists is outdated already. There are better sources of information for kernel developers.

SECTIONS

Sections are started with .SH followed by the heading name. If the name contains spaces and appears on the same line as .SH, then place the heading in double quotes. Traditional or suggested headings include: NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR HANDLING, ERRORS, OPTIONS, USAGE, EXAMPLES, FILES, ENVIRONMENT, DIAGNOSTICS, SECURITY, CONFORMING TO, NOTES, BUGS, AUTHOR, and SEE ALSO. Where a traditional heading would apply, please use it; this kind of consistency can make the information easier to understand. However, feel free to create your own headings if they make things easier to understand. The only required heading is NAME, which should be the first section and be followed on the next line by a one line description of the program:

.SH NAME
chess \- the game of chess

It is extremely important that this format is followed, and that there is a backslash before the single dash which follows the command name. This syntax is used by the makewhatis(8) program to create a database of short command descriptions for the whatis(1) and apropos(1) commands.

Some other traditional sections have the following contents:

SYNOPSIS

briefly describes the command or function's interface. For commands, this shows the syntax of the command and its arguments (including options); boldface is used for as-is text and italics are used to indicate replaceable arguments. Brackets ([]) surround optional arguments, vertical bars (|) separate choices, and ellipses (...) can be repeated. For functions, it shows any required data declarations or #include directives, followed by the function declaration.

DESCRIPTION

gives an explanation of what the command, function, or format does. Discuss how it interacts with files and standard input, and what it produces on standard output or standard error. Omit internals and implementation details unless they're critical for understanding the interface. Describe the usual case; for information on options use the OPTIONS section. If there is some kind of input grammar or complex set of subcommands, consider describing them in a separate USAGE section (and just place an overview in the DESCRIPTION section).

RETURN VALUE

gives a list of the values the library routine will return to the caller and the conditions that cause these values to be returned.

EXIT STATUS

lists the possible exit status values or a program and the conditions that cause these values to be returned.

OPTIONS

describes the options accepted by the program and how they change its behavior.

USAGE

describes the grammar of any sublanguage this implements.

EXAMPLES

provides one or more examples describing how this function, file or command is used.

FILES

lists the files the program or function uses, such as configuration files, startup files, and files the program directly operates on. Give the full pathname of these files, and use the installation process to modify the directory part to match user preferences. For many programs, the default installation location is in /usr/local, so your base manual page should use /usr/local as the base.

ENVIRONMENT

lists all environment variables that affect your program or function and how they affect it.

DIAGNOSTICS

gives an overview of the most common error messages and how to cope with them. You don't need to explain system error messages or fatal signals that can appear during execution of any program unless they're special in some way to your program.

SECURITY

discusses security issues and implications. Warn about configurations or environments that should be avoided, commands that may have security implications, and so on, especially if they aren't obvious. Discussing security in a separate section isn't necessary; if it's easier to understand, place security information in the other sections (such as the DESCRIPTION or USAGE section). However, please include security information somewhere!

CONFORMING TO

describes any standards or conventions this implements.

NOTES

provides miscellaneous notes.

BUGS

lists limitations, known defects or inconveniences, and other questionable activities.

AUTHOR

lists authors of the documentation or program so you can mail in bug reports.

SEE ALSO

lists related man pages in alphabetical order, possibly followed by other related pages or documents. Conventionally this is the last section.

FONTS

Although there are many arbitrary conventions for man pages in the UNIX world, the existence of several hundred Linux-specific man pages defines our font standards:

For functions, the arguments are always specified using italics, even in the SYNOPSIS section, where the rest of the function is specified in bold:

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

Filenames are always in italics (e.g., /usr/include/stdio.h), except in the SYNOPSIS section, where included files are in bold (e.g., #include <stdio.h>).

Special macros, which are usually in upper case, are in bold (e.g., MAXINT).

When enumerating a list of error codes, the codes are in bold (this list usually uses the .TP macro).

Any reference to another man page (or to the subject of the current man page) is in bold. If the manual section number is given, it is given in Roman (normal) font, without any spaces (e.g., man(7)).

The commands to select the type face are:

.B

Bold

.BI

Bold alternating with italics (especially useful for function specifications)

.BR

Bold alternating with Roman (especially useful for referring to other manual pages)

.I

Italics

.IB

Italics alternating with bold

.IR

Italics alternating with Roman

.RB

Roman alternating with bold

.RI

Roman alternating with italics

.SB

Small alternating with bold

.SM

Small (useful for acronyms)

Traditionally, each command can have up to six arguments, but the GNU implementation removes this limitation (you might still want to limit yourself to 6 arguments for portability's sake). Arguments are delimited by spaces. Double quotes can be used to specify an argument which contains spaces. All of the arguments will be printed next to each other without intervening spaces, so that the .BR command can be used to specify a word in bold followed by a mark of punctuation in Roman. If no arguments are given, the command is applied to the following line of text.  

OTHER MACROS AND STRINGS

Below are other relevant macros and predefined strings. Unless noted otherwise, all macros cause a break (end the current line of text). Many of these macros set or use the "prevailing indent." The "prevailing indent" value is set by any macro with the parameter i below; macros may omit i in which case the current prevailing indent will be used. As a result, successive indented paragraphs can use the same indent without re-specifying the indent value. A normal (non-indented) paragraph resets the prevailing indent value to its default value (0.5 inches). By default a given indent is measured in ens; try to ens or ems as units for indents, since these will automatically adjust to font size changes. The other key macro definitions are:  

Normal Paragraphs

.LP

Same as .PP (begin a new paragraph).

.P

Same as .PP (begin a new paragraph).

.PP

Begin a new paragraph and reset prevailing indent.

Relative Margin Indent

.RS i

Start relative margin indent - moves the left margin i to the right (if i is omitted, the prevailing indent value is used). A new prevailing indent is set to 0.5 inches. As a result, all following paragraph(s) will be indented until the corresponding .RE.

.RE

End relative margin indent and restores the previous value of the prevailing indent.

Indented Paragraph Macros

.HP i

Begin paragraph with a hanging indent (the first line of the paragraph is at the left margin of normal paragraphs, and the rest of the paragraph's lines are indented).

.IP x i

Indented paragraph with optional hanging tag. If the tag x is omitted, the entire following paragraph is indented by i. If the tag x is provided, it is hung at the left margin before the following indented paragraph (this is just like .TP except the tag is included with the command instead of being on the following line). If the tag is too long, the text after the tag will be moved down to the next line (text will not be lost or garbled). For bulleted lists, use this macro with \(bu (bullet) or \(em (em dash) as the tag, and for numbered lists, use the number or letter followed by a period as the tag; this simplifies translation to other formats.

.TP i

Begin paragraph with hanging tag. The tag is given on the next line, but its results are like those of the .IP command.

Hypertext Link Macros

.UR u

Begins a hypertext link to the URI (URL) u; it will end with the corresponding UE command. When generating HTML this should translate into the HTML command <A HREF="u">. There is an exception: if u is the special value ":", then no hypertext link of any kind will be generated until after the closing UE (this permits disabling hypertext links in phrases like LALR(1) when linking is not appropriate). These hypertext link "macros" are new, and many tools won't do anything with them, but since many tools (including troff) will simply ignore undefined macros (or at worst insert their text) these are safe to insert.

.UE

Ends the corresponding UR command; when generating HTML this should translate into </A>.

.UN u

Creates a named hypertext location named u; do not include a corresponding UE command. When generating HTML this should translate into the HTML command <A NAME="u" id="u">&nbsp;</A> (the &nbsp; is optional if support for Mosaic is unneeded).

Miscellaneous Macros

.DT

Reset tabs to default tab values (every 0.5 inches); does not cause a break.

.PD d

Set inter-paragraph vertical distance to d (if omitted, d=0.4v); does not cause a break.

.SS t

Subheading t (like .SH, but used for a subsection inside a section).

Predefined Strings

The man package has the following predefined strings:

\*R

Registration Symbol: ®

\*S

Change to default font size

\*(Tm

Trademark Symbol:

\*(lq

Left angled doublequote: ``

\*(rq

Right angled doublequote: ''

SAFE SUBSET

Although technically man is a troff macro package, in reality a large number of other tools process man page files that don't implement all of troff's abilities. Thus, it's best to avoid some of troff's more exotic abilities where possible to permit these other tools to work correctly. Avoid using the various troff preprocessors (if you must, go ahead and use tbl(1), but try to use the IP and TP commands instead for two-column tables). Avoid using computations; most other tools can't process them. Use simple commands that are easy to translate to other formats. The following troff macros are believed to be safe (though in many cases they will be ignored by translators): \ , ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.

You may also use many troff escape sequences (those sequences beginning with \). When you need to include the backslash character as normal text, use \e. Other sequences you may use, where x or xx are any characters and N is any digit, include: \', \`, \-, \., \ , \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, and \f(xx. Avoid using the escape sequences for drawing graphics.

Do not use the optional parameter for bp (break page). Use only positive values for sp (vertical space). Don't define a macro (de) with the same name as a macro in this or the mdoc macro package with a different meaning; it's likely that such redefinitions will be ignored. Every positive indent (in) should be paired with a matching negative indent (although you should be using the RS and RE macros instead). The condition test (if,ie) should only have 't' or 'n' as the condition. Only translations (tr) that can be ignored should be used. Font changes (ft and the \f escape sequence) should only have the values 1, 2, 3, 4, R, I, B, P, or CW (the ft command may also have no parameters).

If you use capabilities beyond these, check the results carefully on several tools. Once you've confirmed that the additional capability is safe, let the maintainer of this document know about the safe command or sequence that should be added to this list.  

NOTES

By all means include full URLs (or URIs) in the text itself; some tools such as man2html(1) can automatically turn them into hypertext links. You can also use the new UR macro to identify links to related information. If you include URLs, use the full URL (e.g., <http://www.kernelnotes.org>) to ensure that tools can automatically find the URLs.

Tools processing these files should open the file and examine the first non-whitespace character. A period (.) or single quote (') at the beginning of a line indicates a troff-based file (such as man or mdoc). A left angle bracket (<) indicates an SGML/XML-based file (such as HTML or Docbook). Anything else suggests simple ASCII text (e.g., a "catman" result).

Many man pages begin with '\" followed by a space and a list of characters, indicating how the page is to be preprocessed. For portability's sake to non-troff translators we recommend that you avoid using anything other than tbl(1), and Linux can detect that automatically. However, you might want to include this information so your man page can be handled by other (less capable) systems. Here are the definitions of the preprocessors invoked by these characters:

e

eqn(1)

g

grap(1)

p

pic(1)

r

refer(1)

t

tbl(1)

v

vgrind(1)

FILES

/usr/share/groff/[*/]tmac/tmac.an
/usr/man/whatis  

BUGS

Most of the macros describe formatting (e.g., font type and spacing) instead of marking semantic content (e.g., this text is a reference to another page), compared to formats like mdoc and DocBook (even HTML has more semantic markings). This situation makes it harder to vary the man format for different media, to make the formatting consistent for a given media, and to automatically insert cross-references. By sticking to the safe subset described above, it should be easier to automate transitioning to a different reference page format in the future.

The Sun macro TX is not implemented.  

AUTHORS

---

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

apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), whatis(1)