Practice of Programming

プログラム とか Linuxとかの話題

tranだいたいできた

翻訳のためのバージョン管理ツール「tran」ですが、ある程度、動くようになりました。
http://github.com/ktat/tran/

ガチャガチャ変更したりしていて、当初の config やオリジナルはもう使えません。
一旦全部捨ててください。もう構成の変更はしないつもりです。

% rm -rf ~/.tran/

んで、

% tran init

していただければと思います。


何を変更したかっていうと、

  • オリジナルの保存場所に、リソースの名前を入れることにした
    • .tran/original/cpan/DBIx-Class/ みたいに (cpanがリソース名)
  • オリジナルを保存するときに、pod に変換するとかはやめた
    • それは、Translation以下のクラスでやらせて、translation の repository に保存するときに変換するようにした
  • Perl の distribution に含まれていて、CPANに独立して上がっていないモジュールへの対応
    • ソースにある lib/ ext/ 以下のパスの命名規則って、何なんだ、あれは...。
    • というか、何が distribution にしかないモジュールなのか判断がつかない
  • コマンド追加
    • getコマンド
    • reconfigure コマンド
    • merge コマンド
  • VCSとの連動
    • 微妙というか、あんまりテストしてない

で、このブログに説明を書くつもりで、数日前から下書きしてたんですが、ドキュメント書いちゃいました。

Tran::Manual::JA - tran のマニュアル
Tran::Manual::Extend::JA - tran を拡張する際のマニュアル


てわけで、マニュアルとかぶっているところも多いのですが、せっかく書いたんで、一応残しときます。

とりあえず始めてみる

すでに翻訳があるもので試したい場合は、オリジナルのバージョンを取得するところから始めてください。

% tran get cpan DBIx::Class 0.7006

のようにして、うまく行く場合は、Authorが変わっていない場合です。
配布先のURLを、cpanコマンドで使っているMetafileの情報を元にしているので、昔と今でAuthorが違う場合失敗します。
で、DBICの場合は失敗してしまうので、以下のようにtar.gz の URLを直接指定します。
(CPANにない場合は、backpanを探す...)

% tran get cpan DBIx::Class http://search.cpan.org/CPAN/authors/id/B/BL/BLBLACK/DBIx-Class-0.07006.tar.gz

これで、 .tran/original/cpan/DBIx-Class/0.07006 にオリジナルのファイルが出来上がります。
次に、最新版の翻訳を開始します。

% tran start cpan DBIx::Class

バージョンを与えない場合、Metafileにあるバージョンを取ってきます(ということで、古ければ、最新ではないのだけど...)。
現時点だと、0.08115になります。取得後、以下の3つのバージョンをマージします。

  • .tran/original/cpan/DBIx-Class/0.07006/以下
  • .tran/original/cpan/DBIx-Class/0.08115/以下
  • cvs/perldocjp/docs/modules/DBIx-Class-0.07006/以下

そして、

  • cvs/perldocjp/docs/modules/DBIx-Class-0.08115以下

に、マージされたファイルが出来上がります。
後は、マージされたファイルを直していくだけです。

マージされ具合

実際どんな感じになるのかっていうと。こんな感じ。

<<<<<<< /home/ktat/cvs/perldocjp/docs/modules//DBIx-Class-0.07006/lib/DBIx/Class/Manual/Cookbook.pod
=head1 名前

DBIx::Class::Manual::Cookbook - レシピいろいろ

=head1 レシピ

=head2 検索

=head3 ページ処理された結果セット
======= /home/ktat/.tran/original//cpan/DBIx-Class/0.08115/lib/DBIx/Class/Manual/Cookbook.pod
=encoding utf8

=head1 NAME

DBIx::Class::Manual::Cookbook - Miscellaneous recipes

=head1 SEARCHING

=head2 Paged results
>>>>>>> END

When you expect a large number of results, you can ask L for a
<<<<<<< /home/ktat/.tran/original//cpan/DBIx-Class/0.08115/lib/DBIx/Class/Manual/Cookbook.pod
paged resultset, which will fetch only a defined number of records at a time:
>>>>>>> END

結果セットが膨大になりそうなら、ページ処理された結果をLで取得できます。
一回に、少しのレコードしかとってきません:

   my $rs = $schema->resultset('Artist')->search(
    undef,
    {
      page => 1,  # page to return (defaults to 1)
      rows => 10, # number of results per page
    },
  );

  return $rs->all(); # all records for page 1

<<<<<<< /home/ktat/cvs/perldocjp/docs/modules//DBIx-Class-0.07006/lib/DBIx/Class/Manual/Cookbook.pod
The C attribute does not have to be specified in your search:

C属性は検索に指定する必要はありません:

  my $rs = $schema->resultset('Artist')->search(
    undef,
    {
      rows => 10,
    }
  );

  return $rs->page(1); # DBIx::Class::ResultSet containing first 10 records

In either of the above cases, you can return a L object for the
resultset (suitable for use in e.g. a template) using the C method:
======= /home/ktat/.tran/original//cpan/DBIx-Class/0.08115/lib/DBIx/Class/Manual/Cookbook.pod
  return $rs->page(2); # records for page 2

You can get a L object for the resultset (suitable for use
in e.g. a template) using the C method:
>>>>>>> END

上のケースのいずれでも、結果セットに、Lオブジェクト(テンプレートに使うのに適した)
を得ることができます。Cメソッドを使って:

  return $rs->pager();

<<<<<<< /home/ktat/cvs/perldocjp/docs/modules//DBIx-Class-0.07006/lib/DBIx/Class/Manual/Cookbook.pod
=head3 複雑な WHERE節
======= /home/ktat/.tran/original//cpan/DBIx-Class/0.08115/lib/DBIx/Class/Manual/Cookbook.pod
=head2 Complex WHERE clauses
>>>>>>> END

結構ざっくりな感じですが、まぁ、一応マージされますよって感じです。とはいえ、この部分はましな例。
CGI.pm 2.89 -> 3.48の場合とか見ると、大丈夫かいなって感じではありますが。


マージの仕方は二種類あります。情報多めの cmpmerge と、少なめの cmpmerge_least(デフォルト) というのを実装しています。これは、cmpmerge_least の結果です。いずれのマージ方法もTran::Repository::Translation で実装しています。cmpmerge の方が、衝突した場合に、原文との差分がわかりやすいですが、ちょっとうざいです。設定ファイルの、merge_method で選べます(repository/translation以下)。


マージメソッドは、Tran::Repository::Translationに実装するだけなので、なんかいい感じのものを誰か書いてくれないかな!

JPRPでの翻訳に使う場合の注意点

マージする時のために、ディレクトリ構成をtranが想定している形にあわせてやる必要があります。
Module::Name というモジュールの場合、

 Module-Name-VERSION/lib/Module/Name.pod

のようなディレクトリ構成を想定しています。tran で、新たに start する場合は、問題ないですが、過去のものをうまくマージさせたい場合は、ディレクトリ構成を上記のように合わせてやる必要があります。

この辺の再配置に関しては、Tran::Repository::Translationのサブクラスが担当しています。
JPAの翻訳文書は、また違った配置なので、違ったように配置するように実装しています。

以前のバージョンとディレクトリ構成が違う場合

でも、オリジナルのモジュールのディレクトリ構成が、以前と違う場合、先ほどのことをしてもマージがうまくいきません。
そういう場合のために、手動でマージできるように、merge コマンドを用意しています。

% tran merge jprp-modules cpan/Module-Name/0.01/Hoge.pm cpan/Module-Name/0.02/lib/Hoge.pm Module-Name-0.01/Hoge.pm

みたいな感じで手動でマージ出来ます。引数は、

% tran merge 翻訳リポジトリ名 古いオリジナル 新しいオリジナル 古い翻訳 [新しい翻訳]

最後の引数を与えると、そのファイルに書き込みます。与えないと、標準出力に吐き出します。
オリジナルは、オリジナルリポジトリからの相対パス、翻訳は、翻訳リポジトリからの相対パスです。
もしくは、絶対パスでも大丈夫です。

ただ、これ、引数がめんどっちいので、オリジナルリポジトリと翻訳リポジトリディレクトリ構成を最新のバージョンに合わせてやってから、startすれば良いと思います。

汎用的だったりそうでもなかったり

tranは、別に、Perlのドキュメントを翻訳するのに特化しているわけではないので、Resourcesと、Repository::Translationのサブクラスだけ作ってやれば、他の翻訳にも使える予定です(Tran::Manual::Extend::JA 参照)。Resources::Cpanのgetメソッドは微妙な感じではありますですが...。それは、ちょっといろいろな都合があるってことで。普通はもっと単純でいける気がします(知らんけど)。

使ってみた感想

先日書いた、Test::Simple(Test::Simple, Test::More, Test::Tutorial)と、上にあげた、DBIx::Class::Manual::Cookbookで、やってみました(DBIx::Classは、マージ部分を綺麗にしただけで、終わってますが)。
前者は、cmpmergeのマージ方法やったのですが、情報が出過ぎな感じがしたので、cmpmerge_least をデフォルトにしました。
Test::Simple では、$this -> $got , $that -> $expected みたいな細かい変更が結構あったので、結構変更範囲が大きく取られてしまっていて、それなりに苦労はしたのですが(結局原文を見たりもした)。
DBIx::Classは、head の番号も変わってるし、変更点も大量だったので、うまくマージができてたり出来てなかったりでした。
マージ上で削除したとされている箇所も、一旦切り取ってどっかに保存しておいたほうが良さげでした。
翻訳にも原文残しておいて、原文と翻訳とのdiffを最後にとることで、だいたい抜けてないかなーってのをチェックしてました。

というわけで、まとめると。

  • mergeは改善の余地がありそう
    • でも、0.47 -> 0.94 とか、0.07006 -> 0.08115 みたいな大幅な変更に対してやってるから大変になるっていう話もある
    • マージは選択制なので、マージしないこともできます
  • startは便利
    • 訳したいと思った時に、必要なファイルが必要なところに揃うのは良い
  • 以前よりはバージョンアップ対応をやる気になれる、気がする
    • やるかどうかは、わからないけど
  • Author変わりすぎ&CPANにもない
    • 古いバージョンに関しては、CPANのMetafileが役に立たない
    • CPANにもないという事態が多発
    • site:backpan.perl.org Module-Name-VERSION.tar.gz をググったほうが良いです

TODO

特に優先順位ではありません。

  • test書かないとね...
  • start時に、JPRPのメタXMLを作る
  • ls コマンド欲しい
    • ls --resource cpan/ls --translation jprp-modules
  • start時にマージするバージョン選びたい --merge-from VERSION みたいな
  • finish コマンドを作る(VCSへのコミットとnotify)
  • diff コマンド(オリジナルと翻訳、オリジナル間、翻訳間のdiffを取る)
  • reconfigure の仕組みは別のモジュールにしたい
  • Metafile依存をやめる(Webから取ってくる)
  • VCS周りの改善
    • あんまりテストしてない
  • Webインターフェース...
    • 簡単に作れそうな気もするが、イレギュラー対応がめんどくさそう。
  • ログの出し分けが不適切な感じがする
  • 他のリソース対応
    • perl.com のドキュメントとか(バージョンないけど、どうしようかな。ハッシュ値とかかな)

多いな、おい。

が、ちっと忙しくなりそうなので、しばらく休止かも(いや、別に暇だったわけではないんだけど)