guide/LDP_man-pages_update.rst

   1 .. _ldp_original_update:
   2
   3 ========================
   4 LDP man-pages 管理ガイド
   5 ========================
   6
   7 ここでは、原文の更新方法について説明する。
   8
   9 手順は以下の通り。
  10
  11 1. po4a 環境の更新
  12 2. 原文の更新作業
  13 3. 単純な fuzzy の更新
  14
  15 0. 事前準備
  16 ===========
  17
  18 :ref:`ldp_preparation` を参照してください。
  19
  20 Git レポジトリの LDP_man-pages 以下はきれいな状態にした状態で始めること。
  21
  22 .. code-block:: console
  23
  24    $ cd manual/LDP_man-pages
  25    $ make clean
  26    $ git status
  27
  28 1. po4a 環境の更新
  29 ==================
  30
  31 ここでは、新しいバージョンの LDP man-pages が po4a で正常に行えることの
  32 確認までを行う。
  33
  34 LDP man-pages のバージョン番号を更新する。
  35
  36 .. code-block:: console
  37
  38    $ vi Makefile
  39
  40    (一番上のバージョン番号を更新する)
  41    # Upstream version
  42    V = 3.79
  43
  44    (必要に応じてダウンロード用の URL を調整)
  45    man-pages-$(V).tar.xz:
  46            wget https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/$@
  47
  48 配布されている LDP man-pages の原文に対して
  49 ローカルの workaround を適用するファイル ``workaround.patch`` を削除しておく。
  50 最新版の LDP man-pages には不要であったり、適用できない可能性があるため。
  51
  52 .. code-block:: console
  53
  54    $ rm -f workaround.patch
  55
  56 以下のコマンドを実行すると、指定された LDP man-pages がダウンロードされ、
  57 po4a による POT/PO ファイルへの変換の準備が行われる。
  58 ``build/C`` 以下に用意されたファイルが po4a による変換で使用される。
  59
  60 .. code-block:: console
  61
  62    $ make setup
  63
  64 以下のコマンドで、削除されたページの反映を行う。
  65 削除されたページがある場合は、 ``po4a/*/*.cfg`` の該当ページに対応する
  66 エントリーがコメントアウトされる。
  67 コメントアウトされたエントリーは不要なので、手動で削除する。
  68
  69 .. code-block:: console
  70
  71    $ make disable-removed
  72
  73 以下のコマンドを実行し、追加されたページを確認する。
  74
  75 .. code-block:: console
  76
  77    $ make print-new-files
  78
  79 追加されたページがあれば、標準出力に ``po4a/*/*.cfg`` に追加する内容が
  80 表示される。ページの内容を確認し、関連が深い po4a cfg ファイルに追加する。
  81 明確な基準はないが、 追加ページの SEE ALSO などを見て、関連性を判断する。
  82
  83 以下のコマンドを実行し、po4a による変換が行えるかを確認する。
  84
  85 .. code-block:: console
  86
  87    $ make translate
  88
  89 po4a が対応している書式が含まれていてエラーが表示される場合がある。
  90 その場合は :ref:`po4a-error` を参考にして対処する。
  91
  92 上記の作業が一通り終わったら、再度最初に戻して動作確認を行う。
  93
  94 .. code-block:: console
  95
  96    $ make clean
  97    $ make setup
  98    $ make print-new-files
  99    $ make disable-removed
 100    $ make translate
 101
 102 これで po4a 環境の更新は終了です。
 103 更新があるはずなので、ここで一度コミットしておくとよい。
 104
 105 .. code-block:: console
 106
 107    $ git status
 108    $ git add ....
 109    $ git commit
 110
 111 .. _po4a-error:
 112
 113 po4a で変換エラーが出た場合の対処
 114 ---------------------------------
 115
 116 po4a が対応している書式が含まれていてエラーが表示される場合がある。
 117 その場合は po4a のマニュアル (``man po4a``) や ``Locale::Po4a::Man``
 118 (``perldoc Locale::Po4a::Man``) を見て対処方法を検討する。
 119
 120 例えば、 LDP man-pages 5.10 の tzfile.5 では以下のようなエラーが出たので、
 121 ``Locale::Po4a::Man`` を参考にして ``po4a/time/time.cfg`` の ``tzfile.5``
 122 のエントリーに ``opt`` 設定を追加した。
 123
 124 .. code-block:: console
 125
 126    $ make
 127    ...
 128    po4a -k 100 --variable langs='' --previous --srcdir . --destdir . po4a/time/time.cfg
 129    build/C/man5/tzfile.5:10: (po4a::man)
 130        This page uses conditionals with '.ie'. Since po4a is not a real groff parser, this is not supported.
 131
 132    build/C/man5/tzfile.5:34: (po4a::man)
 133        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.
 134
 135 .. code-block:: ini
 136    :caption: po4a/time/time.cfg
 137    :emphasize-lines: 3
 138
 139    [type: man] build/C/man5/tzfile.5 \
 140         $lang:build/$lang/man5/tzfile.5 \
 141         opt:"-o groff_code=verbatim -o inline=UR,UE,q" \
 142         add_$lang:?@po4a/add_$lang/lists/local-pre.list \
 143
 144 po4a のオプションでは対応できず、翻訳上も必要な場合は、
 145 原文の roff ファイルを変更する手もある。
 146 その場合は ``build/C/manN/xxxx.N`` を直接変更し、変更後の内容を確認する。
 147 変更内容は ``workaround.patch`` に反映する
 148 (``diff -u man-pages/manN/xxxx.N build/C/manN/xxxx.N`` の出力)。
 149
 150 なお、 ``.\`` で始まる行がある場合は以下のようなメッセージが表示されるが、
 151 JM ではコメント行は翻訳していないので、無視してよい。
 152
 153 .. code-block:: console
 154
 155    This file contains the line '.\" autogenerated headers with the name "__NR__llseek" (i.e., "_llseek").'. You should translate the source file, but continuing anyway.
 156
 157 2. 原文の更新作業
 158 =================
 159
 160 ``manual/LDP_man-pages`` で以下のコマンドを実行する。
 161
 162 .. code-block:: console
 163
 164    $ make upgrade
 165
 166 このコマンドでは、以下の作業が行われる。
 167
 168 1. [make jm-setup]
 169
 170    * 最新版の man-pages の tarball がダウンロードされる。
 171    * tarball が ``man-pages`` ディレクトリに展開される。
 172    * po4a 作業用の source lang が ``build/C`` として用意される。
 173
 174      * 実際にコンテンツがあるファイルが ``build/C/man?`` 以下に
 175        ``man-pages`` 以下からコピーされる。
 176      * ``workaround.patch`` がある場合には ``build/C/`` 以下のファイルに
 177        適用される。
 178      * リンクファイルは ``build/C/link`` に一覧が作成される。
 179
 180 2. 新しい原文を ``original`` 以下にコピーする。
 181
 182 3. ``original`` 以下を git で stage する。
 183
 184 .. warning::
 185
 186    git のバージョンによっては ``git2upd`` が期待通り動作しない場合があるため、
 187    以下の 4. 以降は現在 Makefile でコメントアウトしている。
 188    :doc:`upstream_update` の ``git2upd`` に関する注意を考慮した上で、
 189    以下を手動で実行すること。
 190
 191 4. ``translation_list`` の更新
 192
 193    LDP man-pages の翻訳は、翻訳が完了していない状態でも英語混じりで公開する
 194    ことにしていて、かつ翻訳の進捗状況は ``untrans.html`` で確認できるので、
 195    ``translation_list`` では翻訳ステータスの更新はせず、バージョン番号を
 196    更新するだけになっている。バージョン番号はページ公開時に参照されるので
 197    更新が必要。この点は他のマニュアルと異なるので注意。
 198
 199 5. POT/PO の更新
 200
 201    ``po4a/<category>/po/`` 以下の ``<category>.pot`` (POT ファイル) と
 202    ``ja.po`` が更新される。
 203
 204 6. 翻訳統計情報の更新
 205
 206 7. Git commit
 207
 208    この段階のコミットにより、とりあえず原文更新直後の状態が
 209    一度コミットされることになる。
 210
 211    .. code-block:: none
 212
 213       git add translation_list
 214       git commit -m "LDP: Update original to LDP N.MM"
 215       git add po4a/ stats/ untrans.html
 216       git commit -m "LDP: Update POT and ja.po to LDP N.MM"
 217
 218 上記の処理が ``make upgrade`` の中で行われる。
 219
 220 3. 単純な fuzzy の更新
 221 ======================
 222
 223 COLOPHON が更新されているので、fuzzy が少なくとも一つできる。
 224 ja.po で fuzzy を探してバージョンを更新する。
 225
 226 COLOPHON 以外でも、翻訳に直接関係ないマイナーな更新があれば、
 227 この段階で修正してしまってもよい。
 228 量が多ければ個々の翻訳更新作業の中で行えばよい。
 229
 230 以下では、 PO ファイル更新後に、ドラフトページの生成と翻訳統計を
 231 更新している。内容を確認後、コミットを行う。分かりやすさとファイルの量を
 232 考慮し、ドラフトページとそれ以外を分けてコミットしている。
 233
 234 .. code-block:: console
 235
 236    $ make
 237    $ git add -u po4a/ stats/ untrans.html
 238    $ git commit -m "LDP: Update the version to N.MM in PO files"
 239
 240    $ git add draft/
 241    $ git commit -m "LDP: Update draft pages based on LDP N.MM release"
 242
 243 公開用のリリースページも一気に更新してしまう場合は以下も実行する。
 244
 245 .. code-block:: console
 246
 247    $ make release
 248    $ git add release/
 249    $ git add -u translation_list
 250    $ git commit -m "LDP: Update release pages based on LDP N.MM release"
 251
 252 perkamon について
 253 =================
 254
 255 .. note::
 256
 257    このセクションの内容は過去の覚書です。
 258    perkamon の Makefile の内容は manual/LDP_man-pages/Makefile に統合されました。
 259
 260 perkamon は LDP man-pages の po4a への変換を支援するスクリプトです。
 261
 262 po4a で翻訳する際に、オプション、変換ルール、対象となるファイルなどを
 263 po4a の cfg (`具体例 <https://osdn.net/projects/linuxjm/scm/git/jm/blobs/master/manual/LDP_man-pages/po4a/aio/aio.cfg>`__)
 264 として書いておいて、以下のような形で一括で変換することができます。
 265
 266 .. code-block:: console
 267
 268    $ po4a -k 80  --variable langs='ja' --previous --srcdir . --destdir .  po4a/wchar/wchar.cfg
 269
 270 perkamon がやっていることは、以下の通り。
 271
 272 * この po4a cfg ファイル群を提供
 273   po4a cfg を使った翻訳生成用の Makefile の提供
 274   (make translate や make translate-aio などで翻訳できるようにする)
 275 * LDP man-pages から po ファイルへの変換の前作業
 276   例えば、 link ファイルの除外など。
 277 * LDP man-pages 更新時の po4a cfg 更新の helper script の提供
 278   (make disable-removed や make print-new-files)
 279 * po4a cfg の中で、翻訳時に追加する header や footer の定義なども含まれている。
 280   (JM では昔の copyright や翻訳履歴を生成した man に入れるのに使っている)
 281
 282 JM の LDP_man-pages レポジトリの Makefile は perkamon の wrapper になっている。
 283 perkamon のフォルダーで直接作業するのは LDP man-pages のバージョンを更新する
 284 ときのみ。
 285
 286 perkamon という別ディレクトリになっているのは、 LDP man-pages の po4a での管理を
 287 始めた当初、フランス語の翻訳チームがかなり積極的に新しい LDP man-pages に追従
 288 しており、po4a cfg の更新とかもいつの間にか行われていて、JM 側はそれを利用する
 289 だけ、というメリットがあったためです。
 290
 291 ツール群が perkamon という別ディレクトリになっているため、
 292 LDP_man-pages/Makefile では symlink を作成するなど手順が煩雑になっている点は
 293 あります。 perkamon ディレクトリも含めて、JM のレポジトリに取り込んだ現在では、
 294 もう少し単純化できるかもしれませんが、そこはみなさんの判断にお任せします。