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