Provided by: manpages-zh_1.5-1_all bug

NAME

       man - 格式化手冊隍漣

` SYNOPSIS
       groff -Tascii -man file ...

       groff -Tps -man file ...

       man [section] title

yz DESCRIPTION
       此手冊飧挭壑F    groff    tmac.man    宏包    (通常叫做    man    宏包)
       以及相關的創建手冊隍犖D例。       開發者可以使用這荍誑]來為       linux
       書寫或移植手冊文件。 它與其他版本的這荍誑]一般是相容的,因此移植不是一-
       茪j問題 (但是 NET-2  BSD  發佈中使用了一荍馴不同的宏包叫做  mdoc,參見
       mdoc(7)).

       注意   NET-2   BSD   mdoc  手冊隊]可以使用  groff  處理,只n指定  -mdoc
       選項而不是            -man            選項。推薦使用            -mandoc
       選項,因為這樣會自動判斷應當使用一荂C

 PREAMBLE
       一篇手冊隍熔臚@茤R令 (注釋行之後) 應當是

              .TH title section date source manual,

       這裏:

              title     手冊隍獐陏D (例如, MAN).

              section   手冊隍熙兢`號應當放在這裏 (例如, 7).

              date      最後蚹鴾暾    --   記住n在每次蚹儮L此手冊隊妨戧改它,
                        這樣可以方便地進行版本控制

              source    命令的來源

                        對於二進制檔案,使用這樣的表z:   GNU,   NET-2,    SLS
                        Distribution, MCC Distribution.

                        對於系統調用,使用它適用的核心版本來表z:        Linux
                        0.99.11.

                        對於庫調用,使用函數的來源來表z: GNU, BSD 4.3,  Linux
                        DLL 4.4.1.

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

       注意 BSD mdoc 格式的手冊階H 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
                        檔案系統標準描z,網路協議,ASCII
                        和其他字符集,還有你眼前這份文件以及其他東西

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

              9 Kernel routines
                        這是廢棄的章節。 鴩荋蕙Q把一些關於核心的檔案放在這裏,
                        但是實際上只有極少數可以寫成檔案放在這裏,而且它-
                        怳]很快過時了。 核心開發者可以找到其他更好的資源。

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

              .SH NAME
              chess \- the game of chess

       請一定n按照這荇璁”蚍g,注意在短橫線  (dash `-') 前n有荓袟b (slash `').
       這種語法結構在   makewhatis(8)   程式為   whatis(1)    和    apropos(1)
       命令建立簡短命令描z時n用到。

       其他約定段的內容應為:

      ` SYNOPSIS 簡n描z命令或函數接口。
                     對命令,顯示他的命令和參數(包括各種選項);黑體表示各種參數,
                     下劃線(或斜體字)表示可以替換的選項;
                     方括號[]中的是可選項,豎線    |     用於把幾蚇龠絮★j開,
                     小括號()中的部分可以自動契_。             對函數,顯示需-
                     n的數據聲明或需 #include 包含的項目,後跟函數聲明。

      yz DESCRIPTION
                     解釋命令、函數或格式的用途。
                     說明其如何與檔案及標準輸入交互,他怐獐郱擖X及標準錯誤。
                     必須n指明的細節。描z一般情況。         選項和參數信息放在
                     OPTIONS(選項)段。      如果有語法說明和一些復雜的設定,
                     建議把它怍顐 USAGE(用法)段(本段中最好只寫一虓吵)。

      ^ RETURN VALUE
                     列出程式或函數會返回的A指出引發返回滷囓顝昡因。

      hXA EXIT STATUS
                     列出可能的退出狀態的A指出引起返回的程式或鴞]。

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

      k USAGE    描z程式的較高級的使用方法。

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

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

       ENVIRONMENT
                     列出影響你的程式的所有環境變量,並說明影響的鴞]。

      E DIAGNOSTICS
                     寫出常會出現的錯誤概z,並說明解決的辦法。
                     你無需解釋系統錯誤訊息或信號, 除非它抪|影響到您的程式。

      w SECURITY 討論安全問題和相關話題。對應予避免的配置和環境,
                     可能有安全隱患的命令等等給出警告,            特別是當它-
                     怳ㄛO很明顯時。               單獨用一段來討論安全並不必-
                     n;如果比較好理解的話,把它放在其他段中  (比如  描z   或
                     用法 段)。但是,最好加上它。

      ` CONFORMING TO
                     描z它實現的任何標準或約定

      `N NOTES    提供雜項注意事項

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

      @ AUTHOR   列出程式或檔案作者,聯系辦法等。

       SEE ALSO 以字母順序列出相關的手冊間]man  pages)。通常來講,這是一-
                     茪漭U隍熙怮嶀@段。

r FONTS
       雖然在  UNIX  世界中有各種對手冊間]man  pages)的不同約定,  但在  linux
       系統下存在一茼r型的標準:

              對函數,其參數通常用下劃線(或斜體),
              b`]SYNOPSIS)]Oo ,其他部分用黑體。 例如
              int myfunction(int argc, char **argv);

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

              專用宏,一般大寫表示,用黑體(如: MAXINT).

              列舉錯誤代號時,代號用黑體(這種列舉通常使用 .TP 巨集)。

              對其他手冊隍漱犍峞]或本隊互Y主體的引用)用黑體。
              手冊章節號用普通體(如: man(7)).  設置字型的巨集如下:

       .B  黑體

       .BI 黑體和下劃線(或斜體)交替(描z函數時非常有用)

       .BR 黑體和普通體交替(描z引用時非常有用)

       .I  下劃線(或斜體)

       .IB 下劃線(或斜體)和黑體交替

       .IR 普通體和下劃線(或斜體)交替

       .RB 普通體和下劃線(或斜體)交替

       .RI 小號字和黑體交替

       .SB 小號字和黑體交替

       .SM 小號字(用於縮寫)

       按照慣例,每茤R令最多可以有六茪p節的參數,    但是    GNU    去除了這-
       制。小節之間以空格隔開。      如果某小節含有空格,則需n給其加上雙引號。
       各小節在顯示時無間隔,所以    .BR   命令可以指定一荈藍撉熊,   後跟一-
       荋雲q體的標點。如果命令後無參數,則命令作用於下一行。

LMr OTHER MACROS AND STRINGS
       下惇O其他一些相關的宏和預定義的字符串。
       除非指明,否則所有的宏在本行文本結束時終止。
       多數宏使用「流行縮進」(prevailing    indent)方式。     「流行縮進」的-
       挹繨繺菪邑高   i  定,如果不指定,那就會使用當前的「流行縮進」C
       這樣,連續的縮進段就可使用相同的縮進茪˙愯奐s指定。
       普通段(不縮進)將「流行縮進」偎w設]0.5                   ^寸)。
       預設時,縮進是有規則的  en(s):用  en(s)  或者  em(s)  作為縮進的單位,
       因為它抪|自動地調整字型的大小。    (注:度量距離有不同的單位,當請求需-
       n用到不同的距離時,可以使用預設              類型來袡Ⅳr,度量單位是-
       ^寸,厘米,pica,en,em,點,unit和垂直行距。                1pica等於1/6-
       ^寸,1em等於字母m的寬度,預設寬度取決於troff中使用
       的字型。En是em的一半。) 其他巨集定義如下:

  qq]LYi^ Normal Paragraphs
       .LP.PP 相同(開始一虓s段)

       .P.PP 相同(開始一虓s段)

       .PP      開始一虓s段,姜m「流行縮進」C

  Yi Relative Margin Indent
       .RS i    開始相對縮進 -- 把左邊界右移 i
                 (如果不指定        i        A則使用「流行縮進」       )。
                同時設定「流行縮進」 0.5 ^寸。 直到使用 .RE 結束這些設定。

       .RE      結束相對縮進同時把「流行縮進」恢復噿。

  Yi Indented Paragraph Macros
       .HP i    開始懸掛式縮進(段的第一行從左邊揭開時,其餘縮進顯示)

       .IP x i  在段上標簽 x 。如果不指定 x  ,則整茯q縮進  i  。如果指定了  x
                ,則   x  之前的段不縮進,之後的段縮進(有些像  .TP  ,不過  x
                是跟在命令後惘茪ㄛO在下一行)。     如果      x      太長,後-
                悸漱憟遠|挪到下一行(文本不會丟 失或割斷)。

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

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

  W Hypertext Link Macros
       .UR u    建立一荈W文本鏈接到 URI (URL) u; 並以 UE  結束。當轉換為  HTML
                格式時,他會轉換為  <A  HREF="u">.  有茖狴~:如果 u 是特殊字符
                「         :」,則之後不能建立任何超級鏈接,直到以         UE
                結束(這用來在不需n超級鏈接時禁止他)。       LALR(1)      這-
                荍誘騆新,很多程式可能並不對他進行處理。但是由於很多工具
                (包括 troff) 簡單地忽略未定義宏 (或者最壞的將它抴﹞J到文本中),
                插入它怓O安全的

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

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

   Miscellaneous Macros
       .DT      姜m tab 偎w設(每一0.5^寸)。不引起中斷。

       .IX ...  插入索引信息(方便搜索系統工作,或列印索引列表)。         在-
                隊仁薑獂H息不能正常顯示。                    如果只有一荌捊A
                參數作為獨立的索引項指向手冊隍漱漁e。  如果有兩荌捊A他可能是
                Perl     手冊雅璁﹛F     第一荌捊定類型名    (命令名,標題
                ,題頭,子段貨源素之一),         第二荌捊明自己的索引名。
                另外,長索引形式:每荌捊O一荅薑瑗窗A
                次級索引項,再次級索引項,等等直到以空參數結束,
                然後是程式名參數,\m,還有一小段描z。          還可能在跟上一-
                茠酈捊A有可能是雇惆謍H息  (如:   PAGE   START)。舉例如下:
                "programmingtools""make""""make-- build programs".

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

       .SS t    子標題 t 像是 .SH, 但是作為段中的字標題使用)

  wwqr Predefined Strings
       man 預定義了下列字符串

       \*R    注冊符號: (R)

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

       \*(Tm  商標符號: tm

       \*(lq  左雙引號: "

       \*(rq  右雙引號: "

wl SAFE SUBSET
       理論上 man 是一 troff  巨集套件,實際上很多工具程式沒有支持所有的  man
       巨集。           因此,為了這些程式可以正常工作最好忽略           troff
       的一些比較另類的宏。      避免使用各種不同的      troff      預處理程式
       (如果必須的話,用   tbl(1)  吧,  但是在建立雙列表時請使用  IPTP
       命令)。避免使用p算;大多數其他程式不能處理他。
       使用簡單的命令比較容易轉換為其他格式。                              下-
       悸漸邑陘@般認為是安全的(雖然多數時唹L抭ㄢQ忽略了): \",  .,  ad,  bp,
       br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so,
       sp, ti, tr.

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

       不n隨意使用     bp     (break     page(中斷間^)。    sp    (vertical
       space(垂直距離)只應使用正C                不n用                 (de)
       (define(定義)定義與現有的宏同名的宏(無論   man   或  mdoc);  這種-
       奐s定義可能會被忽略。 每茈螟Y進 (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
       命令也可以不帶參數)。

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

`N NOTES
       盡量在文本中包含完整的  URL(或URIs);  一些工具軟體(如: man2html(1)
       )能夠自動把它斨鉥型偉W級鏈接。  您也可用  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      可以檢測到這一點。       不過,你或許想-
       n包含這些信息以使其可以在其他系統得到處理。 下惇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

       大多數巨集描z的是格式(比如:字型和空格)而不是內容描z(比如:
       這段文字指向另外一間^,   與    mdoc    和    DocBook    正好相反(HTML
       也有比較多的內容描z)。                    這使得                   man
       難以轉換為其他形式,不容易與其他檔案組合或自動插入交叉引用。
       遵照以上的安全說明,就比較容易在將來把他轉換為其他格式。

       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
       apropos(1),  groff(1),  man(1),  man2html(1), mdoc(7), mdoc.samples(7),
       whatis(1)

[]
       RedCandle <redcandle51@chinaren.com>

[]
       2003.11.25

mlinuxan:
       http://cmpp.linuxforum.net