參考頁面應該遵循標準的版面配置。這樣使用者可以更快地找到所需的資訊,並且也鼓勵作者記錄命令的所有相關方面。不僅希望 PostgreSQL 參考頁面之間保持一致,也希望與作業系統和其他套件提供的參考頁面保持一致。因此,制定了以下指南。它們在很大程度上與各種作業系統建立的類似指南一致。
描述可執行命令的參考頁面應包含以下章節,依此順序排列。不適用的章節可以省略。只有在特殊情況下才應使用其他頂層章節;通常這些資訊屬於 “用法” 章節。
此章節會自動產生。它包含命令名稱和對其功能的簡短描述。
此章節包含命令的語法圖。概要通常不應列出每個命令列選項;這在下面會說明。相反地,列出命令列的主要組成部分,例如輸入和輸出檔案的位置。
幾個段落解釋命令的作用。
描述每個命令列選項的清單。如果有大量選項,可以使用小節。
如果程式使用 0 表示成功,非零表示失敗,則您不需要記錄它。如果不同的非零退出代碼背後有含義,請在此處列出它們。
描述程式的任何子語言或執行階段介面。如果程式不是互動式的,通常可以省略此章節。否則,此章節是用於描述執行階段功能的總括章節。如果適當,請使用小節。
列出程式可能使用的所有環境變數。盡量完整;即使是看似微不足道的變數(例如 SHELL
)也可能對使用者有幫助。
列出程式可能隱式存取的任何檔案。也就是說,不要列出在命令列上指定的輸入和輸出檔案,而是列出組態檔案等。
解釋程式可能產生的任何異常輸出。避免列出所有可能的錯誤訊息。這需要大量工作,並且在實務中用途不大。但是,如果錯誤訊息具有使用者可以解析的標準格式,則可以在此處進行說明。
任何不適合放在其他地方的東西,特別是錯誤、實作缺陷、安全性考量、相容性問題。
範例
如果程式的歷史中有一些重要的里程碑,可以在此處列出。通常,可以省略此章節。
作者(僅在 contrib 章節中使用)
交叉參考,按以下順序排列:其他 PostgreSQL 命令參考頁面、PostgreSQL SQL 命令參考頁面、引用 PostgreSQL 手冊、其他參考頁面(例如,作業系統、其他套件)、其他文件。同一群組中的項目按字母順序列出。
描述 SQL 命令的參考頁面應包含以下章節:名稱、概要、描述、參數、輸出、註解、範例、相容性、歷史、參見。“參數”章節與“選項”章節類似,但對於可以列出的命令子句有更大的自由度。只有當命令傳回預設命令完成標籤以外的內容時,才需要“輸出”章節。“相容性”章節應說明此命令在多大程度上符合 SQL 標準,或者與哪個其他資料庫系統相容。SQL 命令的“參見”章節應在交叉參考到程式之前列出 SQL 命令。
如果您在文件中發現任何不正確、與您對特定功能的體驗不符或需要進一步澄清的地方,請使用 此表格 報告文件問題。