I.5. スタイルガイド

I.5.1. リファレンスページ

リファレンスページは標準のレイアウトに従う必要があります。 このことにより、ユーザが必要な情報を素早く見つけられるようになり、同時にあるコマンドに関連する全ての特徴を文書化する書き手を励ましてもいます。 一貫性は、PostgreSQLの各リファレンスページ間だけでなく、オペレーティングシステムや他のパッケージソフトのリファレンスページとの関係でも求められるものです。 そのために、以下のガイドラインが作成されました。 このガイドラインのほとんどの部分は、様々なオペレーティングシステムで定められている同様のガイドラインと一貫性を持つものです。

実行可能なコマンドを説明するリファレンスページには、以下の節がこの順序で含まれる必要があります。 該当しない節は除外しても構いません。 これらと同レベルの節は特殊な状況でのみ追加すべきです。 そのような情報は多くの場合、"使用法"節に入れることができます。

名前

この節は自動的に生成されます。ここには、コマンドの名前および機能の簡単な概要が入ります。

概要

この節にはコマンドの構文図が入ります。 この概要には、通常、各コマンドラインオプションを記載しません(それらは、以下の節に記載されます)。 その代わり、入出力ファイルの宛先などのコマンドラインの主要なコンポーネントを記載します。

説明

コマンドによって何が行われるかを説明する文章です。

オプション

各コマンドラインオプションについて説明するリストです。 オプションが数多くある場合、副節を使用することができます。

終了ステータス

成功の場合はゼロを使用し、失敗の場合には非ゼロを使用するプログラムでは、この節を記載する必要はありません。 複数の非ゼロの終了コードに異なる意味があれば、ここに記載します。

使用法

プログラムの副言語またはランタイムインタフェースを全て記載します。 プログラムが対話型でない場合、通常はこの節を除外されます。 それ以外の場合、この節は実行時の特徴のすべてを記載するために使用されます。 必要に応じて副節を作成してください。

環境

プログラムが使用する可能性のある全ての環境変数を列挙します。 なるべく完全なリストを作成してください。 SHELLのような些細に見える変数でも、ユーザに必要なことがあります。

ファイル

プログラムが暗黙的にアクセスする可能性のある全てのファイルを列挙します。 つまり、コマンドラインで指定された入出力ファイルではなく、設定ファイルなどを列挙するということです。

診断

プログラムが作成する可能性のある全ての異常な出力についての説明を記載します。 全てのエラーメッセージを列挙することは避けてください。 作業が大変な割に、実際にはほとんど役に立たないからです。 ただし、エラーメッセージにユーザが解析できる標準のフォーマットがあれば、ここに記載してください。

備考

特定の不具合、実装の問題点、セキュリティの考慮事項、互換性の問題など、他の節に該当しない全てのものを記載します。

例を記載します。

更新履歴

プログラムの更新履歴に主要な変更点があった場合、ここに列挙します。 通常この節は省くことができます。

関連項目

次の順序で列挙されるクロスリファレンスです。 他のPostgreSQLコマンドのリファレンスページ、PostgreSQLのSQLコマンドのリファレンスページ、PostgreSQLマニュアルの引用、他のリファレンスページ(オペレーティングシステム、他のパッケージソフトなど)、その他の文書。同一グループに属するものは、アルファベット順に列挙します。

SQLコマンドを説明するリファレンスページには、次の節を含める必要があります。 名前、概要、説明、パラメータ、使用法、診断、備考、例、互換性、更新履歴、関連項目。 パラメータ節はオプション節と似ていますが、リストに加えることのできるコマンドの句についてより自由度が高いものです。 互換性節では、このコマンドがどの程度まで標準SQLに準拠しているか、または、他のどのデータベースシステムに対して互換性があるかを説明します。 SQLコマンドの関連項目節では、プログラムへのクロスリファレンスよりも前にSQLコマンドを記載する必要があります。