Update LDP man-pages part of JM guide

diff --git a/guide/LDP_man-pages.rst b/guide/LDP_man-pages.rst
index a0b8a7c..062dc29 100644 (file)
--- a/guide/LDP_man-pages.rst
+++ b/guide/LDP_man-pages.rst
@@ -2,53 +2,63 @@
 LDP man-pages 翻訳ガイド
 ========================
 
+LDP man-pages では、翻訳に po4a を利用しています。
+そのため、手順が他の翻訳方法と少し異なっています。
+
 .. _ldp_preparation:
 
 準備
 ====
 
-LDP man-pages のマニュアルのレポジトリは git の submodule になっています。
-作業時は以下のように submodule を展開します。
+po4a を利用しているので、インストールしておきます。
+以下は Debian/Ubuntu の場合。
+他のディストリビューションの場合も po4a をインストールすれば大丈夫だと思います。
 
 .. code-block:: console
 
-   git://scm.osdn.jp/gitroot/linuxjm/jm.git
-   cd jm
-   git submodule update --init --recursive
+   $ apt-get install po4a
 
-また、po4a を利用しているので、インストールしておきます。
+翻訳更新の動作確認を行っておきます。
+全ファイルを処理するので多少時間がかかります (2〜3分くらい)。
 
 .. code-block:: console
 
-   apt-get install po4a
+   $ cd manual/LDP_man-pages
+   $ make jm-setup
+   $ make
+   $ git status
+
+全部のコマンドがエラーなく終了すること、
+最後の ``git status`` コマンドで更新されているファイルがないこと、
+を確認してください。
+``git status`` の出力で更新されているファイルがある場合は、
+そのまま翻訳作業を進めると、意図しないファイルも更新してしまうことがあるので、
+メーリングリストで相談するなどして対応を検討しましょう。
+作業漏れ以外の可能性もあり、たとえば、 po4a のバージョンが変わって
+PO ファイルへの抜き出し方法が変わることもあります。
 
 翻訳方法
 ========
 
 LDP man-pages では、翻訳に po4a を利用しています。
 
-roff ファイルと po4a ファイルの変換には、LDP man-pages のフランス語翻訳チームが
-公開している perkamon を利用しています。
-perkamon を git submodule として利用しているため、手順が少し複雑になっています。
-
-前準備
-------
-
-git repository の top directory で以下のコマンドを実行します。
+roff ファイルと PO ファイルの変換には、 roff ファイルと PO ファイルが 1:1
+になっているわけではなく、 po4a ファイルはカテゴリー毎に用意され、
+ひとつの po4a ファイルには複数の roff ファイルが含まれています。
 
-.. code-block:: console
-
-   cd $JM_REPO_TOP
-   git submodule update --init
-
-po4a 環境を用意します。
-
-.. code-block:: console
+おおまかな流れは以下のようになります。
 
-   cd manual/LDP_man-pages
-   make jm-setup
+1. 翻訳したい man page に対応する PO ファイルを特定する
+2. PO ファイルで翻訳を行う
+3. draft の man page を生成する
 
-これで po4a で作業して draft に反映する準備が整いました。
+ファイルの対応付けがこのようになっているのは、
+似た roff ファイルには似た文が含まれていてカテゴリー単位の方が翻訳が
+効率化されること、逆に全 roff ファイルを一つの PO ファイルにまとめて
+しまうと本来違う意味で解釈すべき文が同じエントリーになってしまう可能性
+があり、それを回避するため、という点からです。
+この対応付けは、もともと LDP man-pages のフランス語翻訳チームが
+公開していた perkamon をベースにしています。
 
 翻訳と draft への変換
 ---------------------
@@ -85,21 +95,32 @@ ja.po から draft を生成するには以下のいずれかを実行します
 
 .. code-block:: console
 
-   make
-   make translate
+   $ make
+
+または
+
+.. code-block:: console
+
+   $ make translate
 
-初めて実行する際には、全ての ja.po が変換対象になるので、時間がかかります。
 どのファイルが更新されたかは git status で確認して下さい。
 
 .. code-block:: console
 
-   git status .
+   $ git status .
 
 デフォルトでは、翻訳率 80% 以上のページが生成されます。
 80% にしている理由は、ある程度日本語混じりの draft page を見ながら翻訳する方が
 全体の文脈をつかみやすいためです。全部翻訳できたかは、下記の「翻訳状況の確認」
 の方法で確認できるので、翻訳率 100% を閾値にする必要はないと考えています。
 
+生成された draft page を man コマンドで整形して、内容を確認します。
+修正を行う際は、 ja.po を更新 -> draft page の生成 -> 内容の確認、を繰り返します。
+
+.. code-block:: console
+
+   $ man -l draft/man3/strptime.3
+
 翻訳状況の確認
 --------------
 
@@ -143,6 +164,11 @@ ja.po の diff は以下のコマンドで取得できます。 time の ja.po 
 
    git diff po4a/time/po/ja.po
 
+.. note::
+
+   レビュー方法は改善の余地がいろいろあると思います。
+   たとえば、プルリクエストを使うなど。
+
 リリース
 --------
 
@@ -157,5 +183,5 @@ ja.po の diff は以下のコマンドで取得できます。 time の ja.po 
 
 更新後は通常のリリース手順と同じです。
 
-* release ファイルを git add -u → git commit
+* release ファイルを git add → git commit
 * (必要に応じて) www/index.m4, www/news/index.m4 を更新

diff --git a/guide/LDP_man-pages_update.rst b/guide/LDP_man-pages_update.rst
index 66b4067..b729017 100644 (file)
--- a/guide/LDP_man-pages_update.rst
+++ b/guide/LDP_man-pages_update.rst
@@ -12,47 +12,68 @@ LDP man-pages 管理ガイド
 原文の更新方法
 ==============
 
-Git Repo 以下はきれいな状態にした状態で始めること。
-
-作業手順は以下の通り。
+手順は以下の通り。
 
 1. perkamon の更新
 2. 原文の更新作業
 3. 単純な fuzzy の更新
 
+0. 事前準備
+-----------
+
+Git レポジトリの LDP_man-pages 以下はきれいな状態にした状態で始めること。
+
+.. code-block:: console
+
+   $ cd manual/LDP_man-pages
+   $ make clean-setup
+   $ git status
+
 1. perkamon の更新
 ------------------
 
+このセクションの操作はすべて ``perkamon`` ディレクトリーで行う。
+ここでは、新しいバージョンの LDP man-pages が po4a で正常に行えることの
+確認までを行う。
+
 .. code-block:: console
 
-   cd perkamon
-   git remote add upstream git://gitorious.org/perkamon/man-pages.git
-   git remote update
-   git checkout master
-   git merge upstream/master
-   git push origin
-   cd -
+   $ cd perkamon
+
+LDP man-pages のバージョン番号を更新する。
+
+.. code-block:: console
+
+   $ vi Makefile
+
+   (一番上のバージョン番号を更新する)
+   # Upstream version
+   V = 3.79
+
+   (必要に応じてダウンロード用の URL を調整)
+   man-pages-$(V).tar.xz:
+           wget https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/Archive/$@
+
+配布されている LDP man-pages の原文に対して
+ローカルの workaround を適用するファイル ``po4a-fixes.patch`` を削除しておく。
 
-現状 JM 用の perkamon は amotoki が管理する GitHub Repository
-https://github.com/amotoki/perkamon.git にあります。
-Commit 権が必要であれば Collaborator に登録しますので、連絡下さい。
+.. code-block:: console
 
-オリジナルが更新されていない場合は自分で更新する
+   $ rm -f po4a-fixes.patch
 
 .. code-block:: console
 
-   cd perkamon
-   vi Makefile
-   (Update the version number at the top)
-   rm -f stamp-*
-   make setup
+   $ make setup
    (build 以下が更新される)
-   make print-new-files
+   $ make print-new-files
    (何か表示されたら、po4a/*/*.cfg に追加)
-   make disable-removed
+   $ make disable-removed
    (何かないか確認)
-   git status
-   (更新があれば git commit & git push origin)
+   $ git status
+   (更新があるはずなので、ここで一度 commit を作成しておくとよい)
+   $ git add ....
+   $ git commit
+   $ cd ..
 
 2. 原文の更新作業
 -----------------
@@ -61,42 +82,46 @@ perkamon 作業ディレクトリに最新版に対応した展開する
 
 .. code-block:: console
 
-   make upgrade
+   (manual/LDP_man-pages 以下で実行)
+   $ make upgrade
+
+このコマンドでは、以下の作業が行われる。
 
-以下の作業が行われる。
+1. [make jm-setup]
 
-* [make jm-setup]
+   * 最新版の man-pages の tarball が perkamon/ 直下にダウンロードされる。
+   * tarball が perkamon/man-pages ディレクトリに展開される。
+   * po4a 作業用の source lang が build/C として用意される。
 
-  * 最新版の man-pages の tarball が perkamon/ 直下にダウンロードされる。
-  * tarball が perkamon/man-pages ディレクトリに展開される。
-  * po4a 作業用の source lang が build/C として用意される。
+     * 実際にコンテンツがあるファイルが build/C/man? 以下に man-pages 以下から
+       コピーされる。
+     * po4a-fixes.patch がある場合には、build/C/ 以下のファイルに適用される。
+     * リンクファイルは build/C/link に一覧が作成される。
 
-    * 実際にコンテンツがあるファイルが build/C/man? 以下に man-pages 以下から
-      コピーされる。
-    * po4a-fixes.patch がある場合には、build/C/ 以下のファイルに適用される。
-    * リンクファイルは build/C/link に一覧が作成される。
+2. original 以下にコピーする
 
-* original 以下にコピーする
+3. COLOPHON 以下を削除する。
 
-* COLOPHON 以下を削除する。
+   ``translation_list`` を更新する際に、変更点のみを抽出するために行う。
+   COLOPHON 部分はリリース毎にバージョン番号が更新されてしまうので、
+   original に登録する際には、この節を削除しておく。
 
-  translation\_list を更新する際に、変更点のみを抽出するために行う。
-  COLOPHON 部分はリリース毎にバージョン番号が更新されてしまうので、
-  original に登録する際には、この節を削除しておく。
+4. original 以下を git で stage する。
+5. ``translation_list`` の更新
+6. POT の更新
+7. 翻訳統計情報の更新
 
-* original 以下を git で stage する。
-* translation\_list の更新
-* POT の更新
-* 翻訳統計情報の更新
+8. Git commit
 
-* Git commit
+   この段階のコミットにより、とりあえず原文更新直後の状態が
+   一度コミットされることになる。
 
-  .. code-block:: none
+   .. code-block:: none
 
-     git add translation_list
-     git commit -m "LDP: Update original to LDP v3.XX"
-     git add po4a/ stats/ untrans.html
-     git commit -m "LDP: Update POT and ja.po to LDP v3.XX"
+      git add translation_list
+      git commit -m "LDP: Update original to LDP v3.XX"
+      git add po4a/ stats/ untrans.html
+      git commit -m "LDP: Update POT and ja.po to LDP v3.XX"
 
 3. 単純な fuzzy の更新
 ----------------------
@@ -104,16 +129,67 @@ perkamon 作業ディレクトリに最新版に対応した展開する
 COLOPHON が更新されているので、fuzzy が少なくとも一つできる。
 ja.po で fuzzy を探してバージョンを更新する。
 
+COLOPHON 以外でも、翻訳に直接関係ないマイナーな更新があれば、
+この段階で修正してしまってもよい。
+量が多ければ個々の翻訳更新作業の中で行えばよい。
+
+以下では、 PO ファイル更新後に、ドラフトページの生成と翻訳統計を
+更新している。内容を確認後、コミットを行う。分かりやすさとファイルの量を
+考慮し、ドラフトページとそれ以外を分けてコミットしている。
+
+.. code-block:: console
+
+   $ make
+   $ git add -u po4a/ stats/ untrans.html
+   $ git commit -m "LDP: Update the version to 3.XX in PO files"
+
+   $ git add draft/
+   $ git commit -m "LDP: Update draft pages based on LDP 3.XX release"
+
+公開用のリリースページも一気に更新してしまう場合は以下も実行する。
+
 .. code-block:: console
 
-   make
-   git add -u po4a/ stats/ untrans.html
-   git commit -m "LDP: Update the version to 3.XX in PO files"
+   $ make release
+   $ git add release/
+   $ git add -u translation_list
+   $ git commit -m "LDP: Update release pages based on LDP 3.XX release"
+
+perkamon について
+-----------------
 
-   git add draft/
-   git commit -m "LDP: Update draft pages based on LDP 3.XX release"
+perkamon は LDP man-pages の po4a への変換を支援するスクリプトです。
+
+po4a で翻訳する際に、オプション、変換ルール、対象となるファイルなどを
+po4a の cfg (`具体例 <https://osdn.net/users/amotoki/pf/jm/scm/blobs/master/manual/LDP_man-pages/perkamon/po4a/aio/aio.cfg>`__)
+として書いておいて、以下のような形で一括で変換することができます。
+
+.. code-block:: console
 
-   make release
-   git add release/
-   git add -u translation_list
-   git commit -m "LDP: Update release pages based on LDP 3.XX release"
+   $ po4a -k 80  --variable langs='ja' --previous --srcdir . --destdir .  po4a/wchar/wchar.cfg
+
+perkamon がやっていることは、以下の通り。
+
+* この po4a cfg ファイル群を提供
+  po4a cfg を使った翻訳生成用の Makefile の提供
+  (make translate や make translate-aio などで翻訳できるようにする)
+* LDP man-pages から po ファイルへの変換の前作業
+  例えば、 link ファイルの除外など。
+* LDP man-pages 更新時の po4a cfg 更新の helper script の提供
+  (make disable-removed や make print-new-files)
+* po4a cfg の中で、翻訳時に追加する header や footer の定義なども含まれている。
+  (JM では昔の copyright や翻訳履歴を生成した man に入れるのに使っている)
+
+JM の LDP_man-pages レポジトリの Makefile は perkamon の wrapper になっている。
+perkamon のフォルダーで直接作業するのは LDP man-pages のバージョンを更新する
+ときのみ。
+
+perkamon という別ディレクトリになっているのは、 LDP man-pages の po4a での管理を
+始めた当初、フランス語の翻訳チームがかなり積極的に新しい LDP man-pages に追従
+しており、po4a cfg の更新とかもいつの間にか行われていて、JM 側はそれを利用する
+だけ、というメリットがあったためです。
+
+ツール群が perkamon という別ディレクトリになっているため、
+LDP_man-pages/Makefile では symlink を作成するなど手順が煩雑になっている点は
+あります。 perkamon ディレクトリも含めて、JM のレポジトリに取り込んだ現在では、
+もう少し単純化できるかもしれませんが、そこはみなさんの判断にお任せします。