2025年9月25日: PostgreSQL 18 釋出!
支援的版本: 當前 (18) / 17 / 16 / 15 / 14 / 13
開發版本: devel
不再支援的版本: 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4

J.6. 風格指南 #

J.6.1. 參考頁 #

參考頁應遵循標準佈局。這使得使用者能夠更快地找到所需資訊,同時也鼓勵作者記錄命令的所有相關方面。一致性不僅體現在 PostgreSQL 參考頁之間,還應與作業系統和其他軟體包提供的參考頁保持一致。因此,我們制定了以下指南。這些指南在很大程度上與各作業系統制定的類似指南一致。

描述可執行命令的參考頁應按以下順序包含以下部分。不適用的部分可以省略。除非有特殊情況,否則不應使用額外的頂級部分;通常這些資訊屬於“Usage”(用法)部分。

Name(名稱) #

此部分自動生成。它包含命令名稱及其功能的半句話摘要。

Synopsis(概要) #

此部分包含命令的語法圖。概要通常不應列出每個命令列選項;該資訊在下面列出。相反,應列出命令列主要元件,例如輸入和輸出檔案的位置。

Description(描述) #

幾段解釋該命令的功能。

Options(選項) #

列出並描述每個命令列選項。如果選項很多,可以使用子部分。

Exit Status(退出狀態) #

如果程式使用 0 表示成功,非零表示失敗,則無需記錄。如果不同的非零退出碼有特定含義,請在此列出。

Usage(用法) #

描述程式的任何子語言或執行時介面。如果程式不是互動式的,通常可以省略此部分。否則,此部分是描述執行時功能的“集裝箱”。如有必要,請使用子部分。

Environment(環境) #

列出程式可能使用的所有環境變數。儘量詳盡;即使是像 SHELL 這樣看似微不足道的變數也可能引起使用者的興趣。

Files(檔案) #

列出程式可能隱式訪問的任何檔案。也就是說,不要列出在命令列中指定的輸入和輸出檔案,而是列出配置檔案等。

Diagnostics(診斷) #

解釋程式可能產生的任何不尋常的輸出。避免列出每個可能的錯誤訊息。這工作量很大,實際用處不大。但是,如果錯誤訊息具有使用者可以解析的標準格式,則應在此解釋。

Notes(註釋) #

任何不適合放在其他地方的內容,特別是 bug、實現缺陷、安全注意事項、相容性問題。

Examples(示例) #

示例

History(歷史) #

如果程式在歷史上有一些重要的里程碑,可以列在這裡。通常可以省略此部分。

Author(作者) #

作者(僅用於 contrib 部分)

See Also(參見) #

交叉引用,按以下順序排列:其他 PostgreSQL 命令參考頁、PostgreSQL SQL 命令參考頁、PostgreSQL 手冊引用、其他參考頁(例如,作業系統、其他軟體包)、其他文件。同一組中的專案按字母順序排列。

描述 SQL 命令的參考頁應包含以下部分:Name(名稱)、Synopsis(概要)、Description(描述)、Parameters(引數)、Outputs(輸出)、Notes(註釋)、Examples(示例)、Compatibility(相容性)、History(歷史)、See Also(參見)。Parameters(引數)部分類似於 Options(選項)部分,但對命令的哪些子句可以列出有更多自由。只有當命令返回的內容不是預設的命令完成標籤時,才需要 Outputs(輸出)部分。Compatibility(相容性)部分應解釋該命令在多大程度上符合 SQL 標準,或與哪個其他資料庫系統相容。SQL 命令的 See Also(參見)部分應先列出 SQL 命令,然後列出對程式的交叉引用。

提交更正

如果您在文件中發現任何不正確、與您在該特定功能上的經驗不符或需要進一步澄清的內容,請使用 此表單 報告文件問題。