.. _ldp_original_update:

========================
LDP man-pages 管理ガイド
========================

ここでは、原文の更新方法について説明する。

手順は以下の通り。

1. po4a 環境の更新
2. 原文の更新作業
3. 単純な fuzzy の更新

0. 事前準備
===========

:ref:`ldp_preparation` を参照してください。

Git リポジトリの LDP_man-pages 以下はきれいな状態にした状態で始めること。

.. code-block:: console

   $ cd manual/LDP_man-pages
   $ make clean
   $ git status

1. po4a 環境の更新
==================

ここでは、新しいバージョンの LDP man-pages が po4a で正常に行えることの
確認までを行う。

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/$@

配布されている LDP man-pages の原文に対して
ローカルの workaround を適用するファイル ``workaround.patch`` を削除しておく。
最新版の LDP man-pages には不要であったり、適用できない可能性があるため。

.. code-block:: console

   $ rm -f workaround.patch

以下のコマンドを実行すると、指定された LDP man-pages がダウンロードされ、
po4a による POT/PO ファイルへの変換の準備が行われる。
``build/C`` 以下に用意されたファイルが po4a による変換で使用される。

.. code-block:: console

   $ make setup

以下のコマンドで、削除されたページの反映を行う。
削除されたページがある場合は、 ``po4a/*/*.cfg`` の該当ページに対応する
エントリーがコメントアウトされる。
コメントアウトされたエントリーは不要なので、手動で削除する。

.. code-block:: console

   $ make disable-removed

以下のコマンドを実行し、追加されたページを確認する。

.. code-block:: console

   $ make print-new-files

追加されたページがあれば、標準出力に ``po4a/*/*.cfg`` に追加する内容が
表示される。ページの内容を確認し、関連が深い po4a cfg ファイルに追加する。
明確な基準はないが、 追加ページの SEE ALSO などを見て、関連性を判断する。

以下のコマンドを実行し、po4a による変換が行えるかを確認する。

.. code-block:: console

   $ make translate

po4a が対応している書式が含まれていてエラーが表示される場合がある。
その場合は :ref:`po4a-error` を参考にして対処する。

上記の作業が一通り終わったら、再度最初に戻して動作確認を行う。

.. code-block:: console

   $ make clean
   $ make setup
   $ make print-new-files
   $ make disable-removed
   $ make translate

これで po4a 環境の更新は終了です。
更新があるはずなので、ここで一度コミットしておくとよい。

.. code-block:: console

   $ git status
   $ git add ....
   $ git commit

.. _po4a-error:

po4a で変換エラーが出た場合の対処
---------------------------------

po4a が対応している書式が含まれていてエラーが表示される場合がある。
その場合は po4a のマニュアル (``man po4a``) や ``Locale::Po4a::Man``
(``perldoc Locale::Po4a::Man``) を見て対処方法を検討する。

例えば、 LDP man-pages 5.10 の tzfile.5 では以下のようなエラーが出たので、
``Locale::Po4a::Man`` を参考にして ``po4a/time/time.cfg`` の ``tzfile.5``
のエントリーに ``opt`` 設定を追加した。

.. code-block:: console

   $ make
   ...
   po4a -k 100 --variable langs='' --previous --srcdir . --destdir . po4a/time/time.cfg
   build/C/man5/tzfile.5:10: (po4a::man)
       This page uses conditionals with '.ie'. Since po4a is not a real groff parser, this is not supported.

   build/C/man5/tzfile.5:34: (po4a::man)
       Unknown macro '.q "TZif"'. Remove it from the document, or refer to the Locale::Po4a::Man manpage to see how po4a can handle new macros.

.. code-block:: ini
   :caption: po4a/time/time.cfg
   :emphasize-lines: 3

   [type: man] build/C/man5/tzfile.5 \
        $lang:build/$lang/man5/tzfile.5 \
        opt:"-o groff_code=verbatim -o inline=UR,UE,q" \
        add_$lang:?@po4a/add_$lang/lists/local-pre.list \

po4a のオプションでは対応できず、翻訳上も必要な場合は、
原文の roff ファイルを変更する手もある。
その場合は ``build/C/manN/xxxx.N`` を直接変更し、変更後の内容を確認する。
変更内容は ``workaround.patch`` に反映する
(``diff -u man-pages/manN/xxxx.N build/C/manN/xxxx.N`` の出力)。

なお、 ``.\`` で始まる行がある場合は以下のようなメッセージが表示されるが、
JM ではコメント行は翻訳していないので、無視してよい。

.. code-block:: console

   This file contains the line '.\" autogenerated headers with the name "__NR__llseek" (i.e., "_llseek").'. You should translate the source file, but continuing anyway.

2. 原文の更新作業
=================

``manual/LDP_man-pages`` で以下のコマンドを実行する。

.. code-block:: console

   $ make upgrade

このコマンドでは、以下の作業が行われる。

1. [make jm-setup]

   * 最新版の man-pages の tarball がダウンロードされる。
   * tarball が ``man-pages`` ディレクトリに展開される。
   * po4a 作業用の source lang が ``build/C`` として用意される。

     * 実際にコンテンツがあるファイルが ``build/C/man?`` 以下に
       ``man-pages`` 以下からコピーされる。
     * ``workaround.patch`` がある場合には ``build/C/`` 以下のファイルに
       適用される。
     * リンクファイルは ``build/C/link`` に一覧が作成される。

2. 新しい原文を ``original`` 以下にコピーする。

3. ``original`` 以下を git で stage する。

.. warning::

   git のバージョンによっては ``git2upd`` が期待通り動作しない場合があるため、
   以下の 4. 以降は現在 Makefile でコメントアウトしている。
   :doc:`upstream_update` の ``git2upd`` に関する注意を考慮した上で、
   以下を手動で実行すること。

4. ``translation_list`` の更新

   LDP man-pages の翻訳は、翻訳が完了していない状態でも英語混じりで公開する
   ことにしていて、かつ翻訳の進捗状況は ``untrans.html`` で確認できるので、
   ``translation_list`` では翻訳ステータスの更新はせず、バージョン番号を
   更新するだけになっている。バージョン番号はページ公開時に参照されるので
   更新が必要。この点は他のマニュアルと異なるので注意。

5. POT/PO の更新

   ``po4a/<category>/po/`` 以下の ``<category>.pot`` (POT ファイル) と
   ``ja.po`` が更新される。

6. 翻訳統計情報の更新

7. Git commit

   この段階のコミットにより、とりあえず原文更新直後の状態が
   一度コミットされることになる。

   .. code-block:: none

      git add translation_list
      git commit -m "LDP: Update original to LDP N.MM"
      git add po4a/ stats/ untrans.html
      git commit -m "LDP: Update POT and ja.po to LDP N.MM"

上記の処理が ``make upgrade`` の中で行われる。

3. 単純な fuzzy の更新
======================

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 N.MM in PO files"

   $ git add draft/
   $ git commit -m "LDP: Update draft pages based on LDP N.MM release"

公開用のリリースページも一気に更新してしまう場合は以下も実行する。

.. code-block:: console

   $ make release
   $ git add release/
   $ git add -u translation_list
   $ git commit -m "LDP: Update release pages based on LDP N.MM release"

perkamon について
=================

.. note::

   このセクションの内容は過去の覚書です。
   perkamon の Makefile の内容は manual/LDP_man-pages/Makefile に統合されました。

perkamon は LDP man-pages の po4a への変換を支援するスクリプトです。

po4a で翻訳する際に、オプション、変換ルール、対象となるファイルなどを
po4a の cfg (`具体例 <https://osdn.net/projects/linuxjm/scm/git/jm/blobs/master/manual/LDP_man-pages/po4a/aio/aio.cfg>`__)
として書いておいて、以下のような形で一括で変換することができます。

.. code-block:: console

   $ 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 のリポジトリに取り込んだ現在では、
もう少し単純化できるかもしれませんが、そこはみなさんの判断にお任せします。
