PostgreSQL日本語マニュアルについて

noborus
（ PostgreSQL Advent Calendar 2015の12月7日の記事 - 翌年2月の更新も含みます - からの転載です）

今回は私が参加しているPostgreSQLの日本語マニュアルプロジェクトについて書きます。

PostgreSQLの日本語マニュアルは新しいバージョンが出ると（時期にバラツキはありますが）最新版に追従されています。ずっと維持されているのは素晴らしいことですね。
しかし、この分量のドキュメントを維持していくのは、かなり大変な作業なので一人でも多くの方に参加して頂けるように呼びかけています。少しでも興味を持っていただけたら幸いです。

本家のマニュアル

まず日本語マニュアルの話の前に前提となる話を少しします。

PostgreSQLの一番元となる管理をここでは「本家」と呼びます。
本家のマニュアルはもちろん英語で書かれています。

本家のマニュアルは「ソースコードと同じレポジトリ」のgitで管理されています。URLは以下です。
git.postgresql.org

PostgreSQLのレポジトリ内の構成は大まかに以下のようになっています。

フォルダ	説明
src/	ソースコード
*doc/*	*ドキュメント*
config/	m4などビルドに必要なマクロ等
contrib/	追加モジュールのソースコード

ソースとドキュメントが一緒に管理されているので、基本的にリリースされたときに（英語版は）ドキュメントが古いままということが無いようになっています。

さらにいくつか前提となる知識を上げます。

マニュアルはdocの中のdoc/src/sgml/以下にあるsgmlという拡張子のファイルで書かれています（doc/src/sgml/refにも同様のsgmlファイルがあります）。
このsgml拡張子のファイルはSGML形式で書かれています。
SGMLとは、とりあえずHTMLやXMLのようなタグで挟むマークアップ言語で、HTMLやXMLの親と考えてもらえれば良いです。
さらにその中のDocBook形式で書かれていて、SGMLのDocBook形式ということになります。
http://www.postgresql.org/docs/current/static/ で公開されているドキュメントは、このSGML形式からHTMLに変換されて公開されています。

このSGMLファイルを日本語に翻訳されたファイルに書き換えることで、日本語マニュアルを作成しています。

日本語マニュアル

本家で管理されているソースコードに日本語マニュアルは含まれていません。日本語マニュアルは本家とは別で管理されています。

本家と同じように日本語のマニュアルもgitで、日本語マニュアルの方はGitHubで管理されています。
（日本語マニュアルがgit&githubで管理されるようになったのは9.4からで最近のことです）。

日本語マニュアルのソースは、以下のGitHubプロジェクトから取得できます。

https://github.com/pgsql-jp/jpug-doc

日本語マニュアルのレポジトリでは翻訳されたドキュメントだけでなく、すべてのソースコードが含まれていて、日本語マニュアルのビルドに必要な修正があらかじめ含まれています。

つまり日本語マニュアルのレポジトリは、本家のレポジトリをミラー（コピー）して日本語マニュアルを追加、変更する形で構成されています。

この構成は、本家のレポジトリのブランチは変更せずに日本語マニュアル用のブランチを追加して作成しています。

本家レポジトリ	日本語マニュアル	説明
master	master	masterのミラー
REL9_3_STABLE	REL9_3_STABLE	9.3ブランチのミラー
	doc_ja_9_3	9.3.xの日本語マニュアル
REL9_4_STABLE	REL9_4_STABLE	9.4ブランチのミラー
	doc_ja_9_4	9.4.xの日本語マニュアル
REL9_5_STABLE	REL9_5_STABLE	9.5ブランチのミラー
	doc_ja_9_5	9.5.xの日本語マニュアル

（ミラーと書いてありますが、同期するタイミングは翻訳開始に合わせておこなわれるので、常に最新の状態という訳ではありません）。

（doc_ja_9_3はgit管理のために9.3.2の時点のものをインポートされただけです）

少し前まで、日本語マニュアルはEUC-JPで書かれていました。そのため、doc_ja_9_3はEUC-JPで書かれています。doc_ja_9_4も9.4.0時点ではEUC-JPで書かれています。9.4.1時点からUTF-8に変更されています。そのため、これらのバージョン間で差分を取るのが難しくなっています。

doc_ja_9_4を例に取ると、本家を含めたリリースから翻訳の流れは以下のようになります。

REL9_4_STABLEが更新され9.4.xのtag(REL9_4_x)が付けられる。
日本語マニュアルがREL9_4_STABLEを同期する。
doc_ja_9_4にREL9_4_xの内容を取り込む（マージ）。
取り込んで変更された部分を翻訳。

9.5が出た時はdoc_ja_9_5が最新として管理されることになります。

それから注意点として、英語版ではすべての新しいリリース毎にマニュアルが用意されていますが、日本語マニュアルでは今のところ新しいメジャーバージョンがリリースされると古いメジャーバージョンの分は更新されていません。

ここまでをまとめると

日本語のマニュアルは https://github.com/pgsql-jp/jpug-doc から取得できる。
doc_ja_x_xブランチに日本語マニュアルの最新がある。（9.5のときはdoc_ja_9_5）。
日本語マニュアルは現在UTF-8で書かれている。
翻訳されるのは最新のメジャーバージョンのみ。

ということになります。

そして、このSGMLファイルは変換ソフトによりHTMLやその他の形式に変換することが出来ます。これをマニュアルのビルドと呼びます。

マニュアルのビルドのための準備

上で書いたようにマニュアルはソースと同じレポジトリで管理されています。そのため、PostgreSQLをソースからビルド（コンパイル）できる環境が必要です。さらにマニュアルのビルドでは、ソースのビルドとは違うソフトが必要となります。

必要なソフト

PostgreSQLのソースをビルドするためのソフト

PostgreSQLのソースをビルドするための必要なソフトは、実はマニュアルに書かれています。「PostgreSQL日本語マニュアル必要条件」

PostgreSQLは伝統的な./configure; makeでビルドするようになっていますので、./configureが通るまで必要なソフトをインストールすることになります。

マニュアルのビルドに必要なソフト

さらに、マニュアルのビルドに必要なソフトのインストールも、実はマニュアルに書かれています。「PostgreSQL日本語マニュアルツールセット」。

また日本語マニュアルのプロジェクトのwikiにも書いてあります。「ドキュメントビルド手順」。

日本語マニュアルは既にUTF-8になっているので、「UTF 8ドキュメントをビルドする際の注意事項(RedHat系)」も参照してください。

OS環境によってはこれらの準備が一番苦労することになりますが、仮想マシンやDockerを使用したりしてビルドできる環境を用意してください。

もし、慣れたLinux環境がなく仮想マシンを作成する場合は、DebianやUbuntuがおすすめです。
「apt-get build-dep パッケージ名」でビルドに必要なパッケージがインストール出来ます。

# apt-get build-dep postgresql-9.3

※ 9.3は適宜変えてください。ビルドに必要なパッケージはほぼ変わらないので標準のパッケージのバージョンを指定すれば良いです。

また日本語マニュアルのソースはgitで管理されているので、ビルド環境にgitのインストールをしておいた方がよいでしょう。

日本語マニュアルのソースの取得

日本語マニュアルのソースの取得は、他のGitHubのプロジェクトのソースの取得と同じです。

Forkせずに取得することも出来ますが、せっかくならPull Requestを送れるように自分のレポジトリにForkして管理しましょう。

https://github.com/pgsql-jp/jpug-doc をブラウザで開き、右上のForkボタンを押します。GitHubにログインしていない場合はログイン画面に遷移しますので、ログインしてから続けましょう。

Fork出来たら、jpug-docの自分のページが表示されます。この画面で[HTTPS]か[SSH]を選択して、右のボタンを押せばレポジトリのURLがクリップボードに入るので、ペーストすれば簡単です。

urlcopy

コマンドラインでは以下のように「git clone」の後にURLをペーストします。

$ git clone git@github.com:noborus/jpug-doc.git（URLをペースト）
Cloning into 'jpug-doc'...
remote: Counting objects: 461142, done.
remote: Total 461142 (delta 0), reused 0 (delta 0), pack-reused 461142
Receiving objects: 100% (461142/461142), 158.93 MiB | 245.00 KiB/s, done.
Resolving deltas: 100% (386167/386167), done.
Checking connectivity... done.

jpug-doc というフォルダに一式ダウンロードされています。デフォルトのブランチとしてdoc_ja_x_xが指定されているので、doc_ja_x_xというブランチになっているはずです。

$ cd jpug-doc
$ git branch
* doc_ja_x_x

$ ls
COPYRIGHT       HISTORY   README      aclocal.m4  configure     contrib  src
GNUmakefile.in  Makefile  README.git  config      configure.in  doc

上記のようになっていればダウンロード出来ています。

pgsql-jp/jpug-docプロジェクトと同期しよう

jpug-docからダウンロード出来ましたが、pgsql-jp/jpug-docは他の方がどんどん更新していきます。それらを取り込んだ上で作業をしないと誰かが既に修正した箇所を直していたなんてことになりかねません。

gitは分散バージョン管理として上流の指定が複数あっても良いようになっています。そこで、もうひとつリモートのgitレポジトリを名前をつけて管理します。

$ git remote add upstream git@github.com:pgsql-jp/jpug-doc.git

これで追加されました。確認するには以下のようにします。

$ git remote -v
origin  git@github.com:noborus/jpug-doc.git (fetch)
origin  git@github.com:noborus/jpug-doc.git (push)
upstream    git@github.com:pgsql-jp/jpug-doc.git (fetch)
upstream    git@github.com:pgsql-jp/jpug-doc.git (push)

originが自分のプロジェクト
upstreamがpgsql-jpのプロジェクト

他の方の更新を取り込むのはupstreamを指定してpull(fetch)します。

$ git pull upstream doc_ja_x_x

Forkしたあとに他の方の更新があれば、これで取り込まれます。
（fetchしてmergeする他の手順もあります）。

この更新を自分のプロジェクトにpushすることができます。

$ git push origin doc_ja_x_x

マニュアルのビルド

マニュアルをビルドするには、ソースのビルドと同様にまず ./configureを実行します。./configureは、ドキュメントビルド手順で書いてあるように「--enable-nls --with-libxml --with-libxslt」を付けて実行します。

$ ./configure --enable-nls --with-libxml --with-libxslt
checking build system type... x86_64-unknown-linux-gnu
checking host system type... x86_64-unknown-linux-gnu
checking which template to use... linux
checking whether to build with 64-bit integer date/time support... yes
checking whether NLS is wanted... no
....（略）

エラーが出ずに終了していれば成功で、makeを実行できるようになります。ここではソースのコンパイルが目的ではなく、マニュアルをビルドしたいので「make html」と打ちます。

$ make html

./configureのチェックではマニュアルのビルドに必要なソフトが無くてもエラーにならない場合があります。その場合make時にエラーとなります。エラーとなった場合は再度必要なソフトがインストールされているかチェックしてください。

以下はjade（またはopenjade）というソフトが見つからずにエラーとなった例です。

$ make html
make -C doc html
make[1]: ディレクトリ `/home/noborus/git/jpug-doc/doc' に入ります
make -C src html
make[2]: ディレクトリ `/home/noborus/git/jpug-doc/doc/src' に入ります
make -C sgml html
make[3]: ディレクトリ `/home/noborus/git/jpug-doc/doc/src/sgml' に入ります
SP_CHARSET_FIXED=1 SP_ENCODING=UTF-8 jade  -wall -wno-unused-param -wno-empty -wfully-tagged -D . -D . -c /usr/share/sgml/docbook/stylesheet/dsssl/modular/catalog -d stylesheet.dsl -t sgml -i output-html -V html-index postgres.sgml
/bin/sh: 1: jade: not found
make[3]: *** [HTML.index] エラー 127

この場合インストールし直して再度./configureから実行し直します。

エラーが出ずに終了すれば htmlファイルが出来ているはずです。場所はjpug-doc内のdoc/src/sgml/html/というフォルダの中です。

Webブラウザがインストールされている場合は、以下のように直接見ることができます。

$ google-chrome doc/src/sgml/html/index.html

html

インストールされていない場合は doc/src/sgml/html/ を共有フォルダ等見られる場所にコピーします（継続してビルドするなら、このdoc/src/sgml を共有設定するのが良いでしょう）。

doc/src/sgml/html/ にはスタイルファイルもコピーされているので、ほぼ
日本語マニュアルのサイトで見るのと同じように見えているはずです。ビルドされたhtmlはこの中で完結するようになっていますので、「目次」や「次のページ」などのリンクはそのまま使用できます。

htmlがうまく出来ていれば完了です。これで修正していく準備が整いました。

どのファイルを修正すれば良いのか？

doc/src/sgml/にsgmlファイルがあり、「make html」を実行するとdoc/src/sgml/html/にhtmlファイルが作成されると説明しました。

しかしdoc/src/sgml/にあるsgmlファイルと作成されたhtml/内にあるhtmlファイルを見比べてみると1対1で作成されていないことに気づくでしょう。だいたい1つのsgmlから複数のhtmlへ変換されています。

では今まで見ていたhtmlファイルは、どのsgmlファイルから作られたものでしょう？
実は、htmlファイルだけ見ても元のsgmlファイルがわかるようになっていません。

sgml内の記述のルールに沿ってhtmlファイルが生成されるようになっています。
それは、sgmlのあるレベル以上の「節(sect)」のid名からhtmlファイルが生成されています。

例えば「wal-configuration.html」は拡張子「.html」を省いた「wal-configuration」というid名を使用しているsgmlファイルを探せば良いことになります。

実際にgrepで探してみると

grep 'id="wal-configuration"' *sgml
wal.sgml: <sect1 id="wal-configuration">

wal.sgmlだということがわかります。

このwal.sgmlのwal-configuration節を変更してビルドし直せばwal-configuration.htmlに反映されることになります。

変更してみる

中身はともかく実際に反映されそうなところを変更してみましょう。

wal.sgmlのwal-configurationの節を変更してみます。最初の文の後に「！ワッショイ！」と意味不明な文を入れてみました。表示されている日本語の間なので、そのまま表示されると期待できます。

diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index e08c788..d5feef7 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -670,7 +670,7 @@ WALライタは稼働中に一回ページ全体を書き込むように設計
    Consult <xref linkend="runtime-config"> for general information about
    setting server configuration parameters.
 -->
-データベースの性能に影響するような<acronym>WAL</>に関連した設定パラメータが複数あります。
+データベースの性能に影響するような<acronym>WAL</>に関連した設定パラメータが複数あります。！ワッショイ！
 本節では、その使い方を説明します。
 サーバ設定パラメータの設定方法についての詳細は<xref linkend="runtime-config">
を参照してください。
   </para>

注意点としてはUTF-8で保存することです。文字コードを変えてしまうと全行変更になってしまうので、自分が変更した行以外が変更されていないかは注意しておきましょう。

再びビルドしてブラウザで見てみます。

$ make html
$ google-chrome doc/src/sgml/html/wal-configuration.html

ワッショイ

変更されていますね。ここまででくれば、もう誤字脱字ぐらいだったら修正できますね！

コミットしてプルリクエスト

修正できたらコミットしてプルリクエストを送ってしまいましょう。
手順としては以下なのですが

git add doc/src/sgml/wal.sgml
git commit
git push origin wasshoi（自分のGitHubへ送信）
GitHubでプルリクエストを作成

※ 1.と2.はcommit -aで一気にできます。

この作業はトピックブランチを作成しておこなうことが推奨されています。

トピックブランチ名をwasshoiとすると

$ git checkout -b wasshoi

でブランチを作成し、そのブランチに移動します。そこで上記の1.〜3.までを実行します。

2.のコミットのときにコミットメッセージを書く必要があります。今はUTF-8で統一されているので、日本語で書いてOKです。

3.でのプッシュ先はclone対象がoriginとデフォルトで入っています（設定により変わっていることがあります）ので、clone元のwasshoiブランチにpushすることになります。

$ git push origin wasshoi
Counting objects: 51, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 604 bytes | 0 bytes/s, done.
Total 6 (delta 4), reused 0 (delta 0)
To https://github.com/nobotest/jpug-doc.git
 * [new branch]      wasshoi -> wasshoi

成功したらGitHubの自分のページを開いてみましょう。
手際よく進んでいれば、プルリクエストのボタンが表示されています（表示されていない場合「New pull request」を押してブランチを選択肢ます）。

この「Compare & pull request」ボタンを押すと、次のページに遷移します。
プルリクエスト2

このページを下の方にスクロールしていくと変更したところがわかりやすく表示されています。
プルリクエスト3

確認して問題なければ、「Create pull request」を押せば完了です。

よく考えてみると意味なく「！ワッショイ！」と入れるのはマニュアルにふさわしくなかったので実際には送りませんでした。送っていても速攻却下されていたでしょうね。

プルリクエストを送った後

意味のないプルリクエストはキャンセルして、「パラーメータ」と書いてあるところを見つけたので、「パラメータ」に修正してプルリクエストを送ってみました。

プルリクエストを送るとGitHubのPull requestタブで見ることができます。送ったすぐは、メッセージの後に●マークが表示されています。そして少し経つ（だいたい3分ぐらい）と✓マークか×マークに変わります。

これはTravisCIのサービスを利用して、ビルドのテストをおこなった結果が表示されています。

●の時にはビルドテストの実行中で、終わると✓か×に変わります。✓の場合はテスト成功なのでmergeしても問題ないことを示しています。×の場合はテスト失敗を表しています。

テストは実際にhtmlをビルドするテストを実行していますので、失敗した場合は日本語の
内容の問題ではなく、タグの整合などがおかしくなってしまったことが原因です（例えば、「<para>内容</para>」のところを「<para>内容</par>」のようにしてしまうとビルドに失敗します）。

このマークのところは、travisci の結果へのリンクになっていますので、クリックすると結果の詳細を見ることができます。

もしビルドテストに失敗していた場合は、そのままではマージされることは無いので修正またはPull Requestの取り消しをして再度出し直してください。

後はマージされるのを待つだけですが、プルリクエストが出された状態で、人によるレビューがおこなわれます。マージされる前にコメントで意見が寄せられるので、コメントを返したり、再度修正したりしてマージされるようにがんばりましょう。

レビューしよう

ここまで修正してプルリクエストを送りレビューしてもらうまでを書きましたが、他の人が書いたプルリクエストのレビューも重要な役割です。

リリースとリリースの間の時期は、新しい翻訳文章がなく、間違いの修正程度ですが、新しいバージョンがリリース後に翻訳が本格的に始まると多くのプルリクエストが送られます。
間違いを見つけたら遠慮せずにガンガン指摘しましょう。

pgsql-jp/jpug-docのGitHub右上にあるWatchを押せば、更新されたら通知をメールで受け取ることができます。
是非Watchして、レビューに役立ててください。

また、Slackのpostgresql-jpというTeamでは#jpug-docの部屋があり、GitHubの通知が流されるようになっています。こちらも役立ててください。

レビューしておかしなところがあったらプルリクエストにコメントをします。普通にプルリクエストを指定してコメントを書くか、差分表示のところでカーソルを持っていくと「青い＋」マークが表示されるのでクリックするとコメント入力欄が現われます。指定行に対してコメントしたい場合はこちらの方が便利でしょう。

エディタ

ここまで見てきた通りマニュアルのビルドにはいろいろ必要でしたが、sgmlファイルはテキストファイルなので、普通のエディタで編集できます。

とはいえ、たくさん編集するときはSGMLに対応したエディタが欲しくなりますが、最近のエディタではSGMLに対応したエディタというのは少なくなってきています（emacsであればSGMLに対応したモードがあるのでこまりません）。その場合は、.sgmlをHTMLモードで表示するようにするとハイライト表示ぐらいは良い感じになるのでお勧めです。

SGML文書の構成

やっとここまできてSGML文書の中身の話に入ります。
というのも翻訳では新たにタグを使用したりせずに元のタグ構成を維持するように書くため、タグの意味を知らなくても作業可能なので、作成されるHTMLとの対応を見ながら確認しているぐらいです。

ほとんど唯一知っておかなければならいのは、で囲まれた中身はコメントとなり表示されないということです（この形式はHTMLと同じですね）。

<!--
コメント
-->

さらにコメントの注意点として「ハイフン２つ(--)をコメントの中に書けない」という問題があります。
既に翻訳があり、日本語部分の修正をしているときはほとんど気にする必要はありませんが、新しく翻訳をするときにはよく入れてしまうことがあります。ハイフン２つをいれるときは、「 -- 」に置き換えることになっています。

もうお気づきでしょうが、PostgreSQL日本語マニュアルのソース(sgml)では、英語を日本語に書き換える際、英語をコメントで囲み「」その下に日本語の翻訳を書きます。

 <para>
<!--
  This book is the official documentation of
  <productname>PostgreSQL</productname>.  It has been written by the
  <productname>PostgreSQL</productname> developers and other
  volunteers in parallel to the development of the
  <productname>PostgreSQL</productname> software.  It describes all
  the functionality that the current version of
  <productname>PostgreSQL</productname> officially supports.
-->
本書は<productname>PostgreSQL</productname>のオフィシャルドキュメントです。
<productname>PostgreSQL</productname>ソフトウェアの開発と並行して<productname>PostgreSQL</productname>開発者とそれ以外のボランティアにより書かれてきました。
現在のバージョンの<productname>PostgreSQL</productname>が公式にサポートする全ての機能を網羅しています。
 </para>

この形式になっていると本家（英語）との差分をとった時に日本語マニュアルで変更した部分が識別しやすくなります。本家のREL9_4_5タグと日本語マニュアルのpg945docタグでdiffをとってみましょう。

$ git diff REL9_4_5 pg945doc doc/src/sgml/intro.sgml
  <para>
+<!--
   This book is the official documentation of
   <productname>PostgreSQL</productname>.  It has been written by the
   <productname>PostgreSQL</productname> developers and other
@@ -11,80 +15,117 @@
   <productname>PostgreSQL</productname> software.  It describes all
   the functionality that the current version of
   <productname>PostgreSQL</productname> officially supports.
+-->
+本書は<productname>PostgreSQL</productname>のオフィシャルドキュメントです。
+<productname>PostgreSQL</productname>ソフトウェアの開発と並行して<productname>PostgreSQL</productname>開発者とそれ以外のボランティアにより書かれてきました。
+現在のバージョンの<productname>PostgreSQL</productname>が公式にサポートする全ての機能を網羅しています。
  </para>

いかかでしょう？コメントの開始と終了と日本語マニュアル部分が追加行として表示されています。もしこれ以外に差分が表示されるようであれば、英語のマニュアル部分に変更をしてしまっていることになります。
（先ほどのハイフン２つは変更する必要があるので、ここで差分として表示されます）。

日本語マニュアルにも<productname>PostgreSQL</productname>というsgmlのタグを入れていますが、英語のマニュアルの同じ部分を持ってきているだけなので戸惑うことは無いと思います。

ということで、ここまでまとめると

英語の部分はできるだけ変更せずに前後にの行入れてコメントにする。
ハイフン２つは例外として書き変える。
日本語翻訳を下に書く。
sgmlのタグは同じになるように維持する。

となります。

ここまで把握出来ればかなりの作業が可能になっています。

新しいバージョンの対応

ここまでは修正する作業でした。PostgreSQLの新しいバージョンが出た場合の対応方法を書きます。ただ、まだ手順が不確定の部分があり、ガラッと変わるかもしれません。

新しいバージョンが出た時は、本家のリリースブランチと古いバージョンの日本語マニュアルのブランチをマージさせます。これにより、これまでの翻訳した部分を新しいバージョンに対応させます（コンフリクトが少なからず発生しますが、現在どう解決するか対応方法を試している段階です）。

コンフリクトが解消された時点で、日本語マニュアルブランチとして翻訳の開始が宣言されます。新しいファイルは、英語のままのファイルから始めることがあります。既存のファイルでも追加された部分が英語のままになっています。

翻訳が開始されると、担当が被らないようにドキュメント翻訳担当リストに自分で担当するファイルを書いてから作業を開始します。

今まで担当したことがない方は、まず先にメーリングリストで相談していただくのが良いでしょう。方針等の話し合いはまだメーリングリストでおこなわれることが多いです。

メーリングリストの登録方法はJPUG DOCの翻訳活動への参加方法(初めての方向け)を参照してください。

作業は修正のときとそれほど変わりませんが、英語の部分を自分でコメント「」で囲む作業が必要になります。

翻訳の注意点は、翻訳のTipsとしてまとめられていますが、まだ明文化されていないこともあるので、他の翻訳されたマニュアルを参考に進めていく必要があります。

対訳集

用語については、対訳集でまとめはじめています。

対訳集はまだ複数の語が記載されていて整理しきれていません。複数の訳語が載っているのは現在の翻訳マニュアルから抽出して作成しているので、実際に翻訳マニュアルで用語が統一されていない用語である可能性が高いです（中には場面により使い分けている用語もあります）。

いわゆるカタカナの末尾の長音問題については、現在のところ長音を省く方針になっていますので、方針にしたがって統一するようにします。
（現在末尾の長音がある用語は修正対象です）。

他の形式の作成

実は、DocBook(SGML)はHTML以外の形式も作成することができますので、いくつか紹介します。
以下のmake実行はdoc/src/sgml上でおこないます。

man

manコマンドで見られるマニュアルです。これは doc/src/sgml/ref/にあるファイルを対象にmanファイルを作成します。

$ make man

doc/src/sgml/の中に man1 man3 man7 が作成されます。さらに make installを実行すると、（デフォルトでは/usr/local/pgsql/share/man）に
インストールされます。

インストールされたパスを環境変数MANPATHに設定するとmanコマンドでSQLを引くことができます。

$ man 7 select

PDF

PDFはjadetexとApache-FOPによる作成方法があります。Apache-FOPのインストールが別途必要になりますが、Apache-FOPによる方法で日本語が表示できるように最近調整作業をしているのでそちらをお勧めします。
PDFを作るにはpostgres-A4-fop.pdfを指定してmakeを実行します。

$ make postgres-A4-fop.pdf

単一ファイルで postgres-A4-fop.pdfが作成されます。

参考に私が作ったPDFが http://noborus.github.io/etc/postgres-A4-fop.pdf
に置いてあります。

EPUB

EPUBも作成できます。dbtoepubというコマンドが必要になります。別途インストールしてください。作成は以下のようにします。

$ make epub

postgres.epubファイルが作成されています。
こちらも以下に置いてあります。
http://noborus.github.io/etc/postgres.epub

xhtml

make htmlでHTMLが作成できますが、html4で作成されます。xhtmlで作成できるようになっていますので、公開版をこちらに置き換えるか検討されています（ただし作成時間が10倍ぐらいかかります）。

$ make xslthtml

make htmlと同じようにhtml/フォルダ内に作成されます。
見た目は変わりませんが、htmlのソースを見ると大きく変わっています。

xslt(stylesheet.xslの変更）でカスタマイズが可能なので、レビューするために英語と日本語が両方表示されるhtmlが作成可能になっています。
これを作成するには以下のようにします。

$ make ORIGINAL=1 xslthtml

これで作成されたhtmlがプロジェクトのGitHub Pagesで公開されています。。

テキスト

プレーンテキストも作成可能です。

make postgres.txt

まとめ

ということで、PostgreSQLの日本語マニュアルについて、あれやこれやと書きました。
もしPostgreSQLの翻訳を始めようと始めようと思ったらメーリングリストに参加するのが良いですよ！その上で自分が出来そうなところから始めるのがお勧めです。