G.5. スタイルガイド

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

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

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

名前

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

概要

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

説明

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

オプション

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

終了ステータス

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

使用法

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

環境

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

ファイル

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

診断

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

備考

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

事例

事例を記載します。

更新履歴

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

関連項目

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

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