參考頁應遵循標準佈局。這使得使用者能夠更快地找到所需資訊,同時也鼓勵作者記錄命令的所有相關方面。一致性不僅體現在 PostgreSQL 參考頁之間,還應與作業系統和其他軟體包提供的參考頁保持一致。因此,我們制定了以下指南。這些指南在很大程度上與各作業系統制定的類似指南一致。
描述可執行命令的參考頁應按以下順序包含以下部分。不適用的部分可以省略。除非有特殊情況,否則不應使用額外的頂級部分;通常這些資訊屬於“Usage”(用法)部分。
此部分自動生成。它包含命令名稱及其功能的半句話摘要。
此部分包含命令的語法圖。概要通常不應列出每個命令列選項;該資訊在下面列出。相反,應列出命令列主要元件,例如輸入和輸出檔案的位置。
幾段解釋該命令的功能。
列出並描述每個命令列選項。如果選項很多,可以使用子部分。
如果程式使用 0 表示成功,非零表示失敗,則無需記錄。如果不同的非零退出碼有特定含義,請在此列出。
描述程式的任何子語言或執行時介面。如果程式不是互動式的,通常可以省略此部分。否則,此部分是描述執行時功能的“集裝箱”。如有必要,請使用子部分。
列出程式可能使用的所有環境變數。儘量詳盡;即使是像 SHELL
這樣看似微不足道的變數也可能引起使用者的興趣。
列出程式可能隱式訪問的任何檔案。也就是說,不要列出在命令列中指定的輸入和輸出檔案,而是列出配置檔案等。
解釋程式可能產生的任何不尋常的輸出。避免列出每個可能的錯誤訊息。這工作量很大,實際用處不大。但是,如果錯誤訊息具有使用者可以解析的標準格式,則應在此解釋。
任何不適合放在其他地方的內容,特別是 bug、實現缺陷、安全注意事項、相容性問題。
示例
如果程式在歷史上有一些重要的里程碑,可以列在這裡。通常可以省略此部分。
作者(僅用於 contrib 部分)
交叉引用,按以下順序排列:其他 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 命令,然後列出對程式的交叉引用。
如果您在文件中發現任何不正確、與您在該特定功能上的經驗不符或需要進一步澄清的內容,請使用 此表單 報告文件問題。