LDP man-pages 管理ガイド
========================
-準備
-====
+ここでは、原文の更新方法について説明する。
+
+手順は以下の通り。
+
+1. po4a 環境の更新
+2. 原文の更新作業
+3. 単純な fuzzy の更新
+
+0. 事前準備
+===========
:ref:`ldp_preparation` を参照してください。
-原文の更新方法
-==============
+Git リポジトリの LDP_man-pages 以下はきれいな状態にした状態で始めること。
-Git Repo 以下はきれいな状態にした状態で始めること。
+.. code-block:: console
-作業手順は以下の通り。
+ $ cd manual/LDP_man-pages
+ $ make clean
+ $ git status
-1. perkamon の更新
-2. 原文の更新作業
-3. 単純な fuzzy の更新
+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
-1. perkamon の更新
-------------------
+ $ 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
- 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 -
+ $ make print-new-files
+
+追加されたページがあれば、標準出力に ``po4a/*/*.cfg`` に追加する内容が
+表示される。ページの内容を確認し、関連が深い po4a cfg ファイルに追加する。
+明確な基準はないが、 追加ページの SEE ALSO などを見て、関連性を判断する。
+
+以下のコマンドを実行し、po4a による変換が行えるかを確認する。
+
+.. code-block:: console
+
+ $ make translate
+
+po4a が対応している書式が含まれていてエラーが表示される場合がある。
+その場合は :ref:`po4a-error` を参考にして対処する。
+
+上記の作業が一通り終わったら、再度最初に戻して動作確認を行う。
+
+.. code-block:: console
-現状 JM 用の perkamon は amotoki が管理する GitHub Repository
-https://github.com/amotoki/perkamon.git にあります。
-Commit 権が必要であれば Collaborator に登録しますので、連絡下さい。
+ $ make clean
+ $ make setup
+ $ make print-new-files
+ $ make disable-removed
+ $ make translate
-オリジナルが更新されていない場合は自分で更新する
+これで po4a 環境の更新は終了です。
+更新があるはずなので、ここで一度コミットしておくとよい。
.. code-block:: console
- cd perkamon
- vi Makefile
- (Update the version number at the top)
- rm -f stamp-*
- make setup
- (build 以下が更新される)
- make print-new-files
- (何か表示されたら、po4a/*/*.cfg に追加)
- make disable-removed
- (何かないか確認)
- git status
- (更新があれば git commit & git push origin)
+ $ 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. 原文の更新作業
------------------
+=================
-perkamon 作業ディレクトリに最新版に対応した展開する
+``manual/LDP_man-pages`` で以下のコマンドを実行する。
.. code-block:: console
- make upgrade
+ $ 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`` に一覧が作成される。
-* [make jm-setup]
+2. 新しい原文を ``original`` 以下にコピーする。
- * 最新版の man-pages の tarball が perkamon/ 直下にダウンロードされる。
- * tarball が perkamon/man-pages ディレクトリに展開される。
- * po4a 作業用の source lang が build/C として用意される。
+3. ``original`` 以下を git で stage する。
- * 実際にコンテンツがあるファイルが build/C/man? 以下に man-pages 以下から
- コピーされる。
- * po4a-fixes.patch がある場合には、build/C/ 以下のファイルに適用される。
- * リンクファイルは build/C/link に一覧が作成される。
+.. warning::
-* original 以下にコピーする
+ git のバージョンによっては ``git2upd`` が期待通り動作しない場合があるため、
+ 以下の 4. 以降は現在 Makefile でコメントアウトしている。
+ :doc:`upstream_update` の ``git2upd`` に関する注意を考慮した上で、
+ 以下を手動で実行すること。
-* COLOPHON 以下を削除する。
+4. ``translation_list`` の更新
- translation\_list を更新する際に、変更点のみを抽出するために行う。
- COLOPHON 部分はリリース毎にバージョン番号が更新されてしまうので、
- original に登録する際には、この節を削除しておく。
+ LDP man-pages の翻訳は、翻訳が完了していない状態でも英語混じりで公開する
+ ことにしていて、かつ翻訳の進捗状況は ``untrans.html`` で確認できるので、
+ ``translation_list`` では翻訳ステータスの更新はせず、バージョン番号を
+ 更新するだけになっている。バージョン番号はページ公開時に参照されるので
+ 更新が必要。この点は他のマニュアルと異なるので注意。
-* original 以下を git で stage する。
-* translation\_list の更新
-* POT の更新
-* 翻訳統計情報の更新
+5. POT/PO の更新
-* Git commit
+ ``po4a/<category>/po/`` 以下の ``<category>.pot`` (POT ファイル) と
+ ``ja.po`` が更新される。
- .. code-block:: none
+6. 翻訳統計情報の更新
- 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"
+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 3.XX in PO files"
+ $ 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"
- git add draft/
- git commit -m "LDP: Update draft pages based on LDP 3.XX 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
- 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 のリポジトリに取り込んだ現在では、
+もう少し単純化できるかもしれませんが、そこはみなさんの判断にお任せします。
OSDN Git Service
