# J.5\. 風格指導 ## J.5.1\. 參考頁 參考頁應該遵循標準的布局。這樣就允許用戶更快地找出自己需要的信息， 并且也可以鼓勵作者把一條命令的所有相關方面都記錄在案。一致性不僅僅是 PostgreSQL參考頁的需求，也是操作系統和其它頁面提供的東西。 因此設計了下面的指導方針。它們在大多數時候是與各種操作系統建立起來的類似的風格是一致的。 描述可執行命令的參考頁應該包含下面的小節，并且是按照這里的順序。 不適用的小節可以忽略。額外的頂級小節應該只用在特殊的環境下； 通常那些信息屬于"用法"小節。 名字（Name） 這個小節是自動生成的。它包含命令名和一個半句話的摘要，介紹該命令的功能。 綱要（Synopsis） 這個小節包含該命令的語法圖表。大綱通常不應該列出每個命令行選項；那些東西在后面做。 大綱應該列出命令行的主要組件，比如應該把輸入和輸出文件放在哪里等。 描述（Description） 幾個段落，用于描述該命令是做什么的。 選項（Options） 一個列表，描述每個命令行選項。如果有許多選項，可以用子小節。 退出狀態(Exit Status) 如果程序用 0 表示成功，非零表示失敗，那么你不需要為此寫文檔。 如果在每個非零值的后面有不同的含義，那么在這里列出它們。 用法(Usage) 描述任意子語言或者程序的運行時接口。如果程序不是交互的，那么本節通常可以省略。 否則，本節是用于描述所有運行時特性的地方。如果合適，可以使用子小節。 環境(Environment) 列出所有程序可能使用的環境變量。盡量完整；即使是那些看起來很瑣碎的變量， 比如`SHELL`都可能讓讀者感興趣。 文件(Files) 列出所有程序可能隱含訪問的文件。也就是說，不要列出在命令行上聲明的輸入和輸出文件。 但是列出配置文件等等。 診斷(Diagnostics) 解釋任何程序可能生成的不正常的輸出。避免列出所有可能的錯誤信息。 這樣做工作量很大但沒有太多實際用途。但是如果說錯誤信息有一種用戶可以分析的標準格式， 那么這里可能就是解釋它的地方。 注意(Notes) 任何在其它地方放都不合適的東西，尤其是臭蟲、實現缺陷、安全考量、兼容性問題等。 例子(Examples) 例子 歷史(History) 如果在程序的歷史中有一些主要的里程碑，那么可以在這里列出。通常，這個小節可以省略。 作者（Author） 作者（只在普通發布版中使用） 又見(See Also) 交叉引用，按照下面的順序列出：其它PostgreSQL 命令的參考頁PostgreSQL SQL命令參考頁、 PostgreSQL 手冊的引用、其它引用頁面(比如， 操作系統、其它包)、其它文檔。在同一組里的條目按照字母順序列出。 描述 SQL 命令的參考頁應該包含下面的小節：名字、大綱、描述、參數、輸出、注意、例子、 兼容性、歷史、又見。參數小節類似選項小節，但是有更多自由可以選擇該命令的哪個子句可以列出。 輸出小節只在命令有返回的時候需要，而不是缺省的命令結束標簽。 兼容性小節應該解釋此命令遵循 SQL 標準的哪個擴展，或者它兼容哪種其它數據庫系統。 SQL 命令的"又見"小節應該在交叉引用其它程序之前列出 SQL 命令。