.. _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//po/`` 以下の ``.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 (`具体例 `__) として書いておいて、以下のような形で一括で変換することができます。 .. 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 のリポジトリに取り込んだ現在では、 もう少し単純化できるかもしれませんが、そこはみなさんの判断にお任せします。