G.5. スタイルガイド

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

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

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

名前

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

概要

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

説明

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

オプション

各コマンドラインオプションについて説明するリストです。オプションが数多くある場合、サブセクションが使われることもあります。

終了ステータス

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

使用法

プログラムの副言語またはランタイムインタフェースを全て記載します。 プログラムが対話型でない場合、通常はこのセクションを除外されます。 それ以外の場合、このセクションはランタイム機能の一切を記載するために使用されます。必要に応じてサブセクションを作成してください。

環境

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

ファイル

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

診断

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

備考

特定のバグ、実装の問題点、セキュリティの考慮事項、互換性の問題など、他のセクションに該当しない全てのものを記載します。

事例

事例を記載します。

更新履歴

プログラムの更新履歴に主要な変更点があった場合、ここにリストします。 通常このセクションは除外できます。

関連項目

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

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