I.5. 風(fēng)格指導(dǎo)

I.5.1. 參考頁(yè)

參考頁(yè)應(yīng)該遵循標(biāo)準(zhǔn)的布局。這樣就允許用戶更快地找出自己需要的信息，并且也可以鼓勵(lì)作者把一條命令的所有相關(guān)方面都記錄在案。一致性不僅僅是 PostgreSQL 參考頁(yè)的需求，也是操作系統(tǒng)和其它頁(yè)面提供的東西。因此設(shè)計(jì)了下面的指導(dǎo)方針。它們在大多數(shù)時(shí)候是與各種操作系統(tǒng)建立起來(lái)的類似的風(fēng)格是一致的。

描述可執(zhí)行命令的參考頁(yè)應(yīng)該包含下面的小節(jié)，并且是按照這里的順序。不適用的小節(jié)可以忽略。額外的頂級(jí)小節(jié)應(yīng)該只用在特殊的環(huán)境下；通常那些信息屬于"Usage" 小節(jié)。

名稱: 這個(gè)小節(jié)是自動(dòng)生成的。它包含命令名和一個(gè)半句話的摘要，介紹該命令的功能。
綱要: 這個(gè)小節(jié)包含該命令的語(yǔ)法圖表。大綱通常應(yīng)該不列出每個(gè)命令行選項(xiàng)；那些東西在后面做。大綱應(yīng)該列出命令行的主要組件，比如應(yīng)該把輸入和輸出文件放在哪里等。
描述: 幾個(gè)段落，用于描述該命令是做什么的。
選項(xiàng): 一個(gè)列表，描述每個(gè)命令行選項(xiàng)。如果有許多選項(xiàng)，可以用子小節(jié)。
退出狀態(tài): 如果程序用 0 表示成功，非零表示失敗，那么你不需要為此寫(xiě)文檔。如果在每個(gè)非零值的后面有不同的含義，那么在這里列出它們。
用法: 描述任意子語(yǔ)言或者程序的運(yùn)行時(shí)接口。如果程序不是交互的，那么本節(jié)通?？梢允÷?。否則，本節(jié)是用于描述所有運(yùn)行時(shí)特性的地方。如果合適，可以使用子小節(jié)。
環(huán)境: 列出所有程序可能使用的環(huán)境變量。盡量完整；即使是那些看起來(lái) 很瑣碎的變量，比如 SHELL 都可能讓讀者感興趣。
文件: 列出所有程序可能隱含訪問(wèn)的文件。也就是說(shuō)，不要列出在命令行上聲明的輸入和輸出文件。但是列出配置文件等等。
診斷: 解釋任何程序可能生成的不正常的輸出。避免列出所有可能的錯(cuò)誤信息。這樣做工作量很大但沒(méi)有太多實(shí)際用途。但是如果說(shuō)錯(cuò)誤信息有一種用戶可以分析的標(biāo)準(zhǔn)格式，那么這里可能就是解釋它的地方。
注意: 任何在其它地方放都不合適的東西，尤其是臭蟲(chóng)、實(shí)現(xiàn)缺陷、安全考量、兼容性問(wèn)題等。
例子: 例子
歷史: 如果在程序的歷史中有一些主要的里程碑，那么可以在這里列出。通常，這個(gè)小節(jié)可以省略。
又見(jiàn): 交叉引用，按照下面的順序列出：其它 PostgreSQL 命令的參考頁(yè)、 PostgreSQL SQL命令參考頁(yè)、參考 PostgreSQL 手冊(cè)、其它參考頁(yè)(比如，操作系統(tǒng)、其它包)、其它文檔。在同一組里的條目按照字母順序列出。

描述 SQL 命令的參考頁(yè)應(yīng)該包含下面的小節(jié)：名稱、大綱、描述、參數(shù)、用法、診斷、注意、例子、兼容性、歷史、又見(jiàn)。參數(shù)小節(jié)類似選項(xiàng)小節(jié)，但是有更多自由可以選擇該命令的哪個(gè)子句可以列出。兼容性小節(jié)應(yīng)該解釋此命令遵循 SQL 標(biāo)準(zhǔn)的哪個(gè)擴(kuò)展，或者它兼容哪種其它數(shù)據(jù)庫(kù)系統(tǒng)。 SQL 命令的"又見(jiàn)"小節(jié)應(yīng)該在交叉引用其它程序之前列出 SQL 命令。

前の記事：次の記事：