B.5. スタイルガイド

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

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

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

名前

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

概要

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

説明

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

オプション

各コマンドラインオプションについて説明するリストです。 オプションが多い場合、サブセクションを作ることもできます。

終了ステータス

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

使用法

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

環境

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

ファイル

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

診断

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

備考

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

例を記載します。

更新履歴

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

関連項目

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

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