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