" で始まる段落のリストをパースします。簡単にするために、ドキュメントは整形されている、すなわち、現れるタグは '
' のみで、各段落はこのタグで必ず始まると仮定します。 .PP .Vb 2 \& sub parse { \& my $self = shift; \& \& PARAGRAPH: while (1) { \& my ($paragraph,$pararef)=("",""); \& my $first=1; \& my ($line,$lref)=$self\->shiftline(); \& while (defined($line)) { \& if ($line =~ m/
/ && !$first\-\-; ) { \& # Not the first time we see
. \& # Reput the current line in input, \& # and put the built paragraph to output \& $self\->unshiftline($line,$lref); \& \& # Now that the document is formed, translate it: \& # \- Remove the leading tag \& $paragraph =~ s/^
//s; \& \& # \- （翻訳されていない）先頭のタグと \& # （翻訳された）残りの段落を出力に押し込みます \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& next PARAGRAPH;
\& } else {
\& # Append to the paragraph
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # Reinit the loop
\& ($line,$lref)=$self\->shiftline();
\& }
\& # Did not get a defined line? End of input file.
\& return;
\& }
\& }
.Ve
.PP
parse 関数を実装したら、次節で説明するパブリックインターフェースを用いて document クラスを使用できます。
.SH パーサで使用するスクリプトのパブリックインターフェース
.IX Header "パーサで使用するスクリプトのパブリックインターフェース"
.SS コンストラクタ
.IX Subsection "コンストラクタ"
.IP process(%) 4
.IX Item "process(%)"
この関数は、po4a ドキュメントで行うのに必要なすべてを、一度の実行で行います。引数はハッシュとしてパックしなくてはなりません。動作は以下のようになります:
.RS 4
.IP a. 3
.IX Item "a."
po_in_name で指定したすべての PO ファイルの読み込み
.IP b. 3
.IX Item "b."
file_in_name で指定したすべてのオリジナルドキュメントの読み込み
.IP c. 3
.IX Item "c."
ドキュメントのパース
.IP d. 3
.IX Item "d."
指定したすべての追加内容の読み込みと適用
.IP e. 3
.IX Item "e."
翻訳したドキュメントの file_out_name への書き出し (与えられた場合)
.IP f. 3
.IX Item "f."
抽出した PO ファイルの po_out_name への書き出し (与えられた場合)
.RE
.RS 4
.Sp
\&\fBnew()\fR で受け付けるもの以外の引数 (と想定する型):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
読み込むべき入力ドキュメントのファイル名のリストです。
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
入力文書で使用する文字集合です（指定しない場合、UTF\-8を使用）。
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
書き出すべき出力ドキュメントのファイル名です。
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
出力文書で使用する文字集合です（指定しない場合、UTF\-8を使用）。
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
読み込むべき入力 PO ファイル (ドキュメントの翻訳に使用する翻訳) のファイル名のリストです。
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
入力ドキュメントから抽出した文字列を含む、書き出すべき出力 PO ファイルのファイル名です。
.IP "addendum (@)" 4
.IX Item "addendum (@)"
読み込むべき追加内容のファイル名のリストです。
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
追加内容の文字セット。
.RE
.RS 4
.RE
.IP new(%) 4
.IX Item "new(%)"
新規 po4a ドキュメントを作成します。以下の（引数として渡されたハッシュの）オプションを受け取ります：
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
冗長表示を有効にします。
.IP "debug ($)" 4
.IX Item "debug ($)"
デバッグを有効にします。
.IP "wrapcol ($)" 4
.IX Item "wrapcol ($)"
出力文書でテキストを折り返す列です（既定は76）。
.Sp
負値は行を全く折り返さない意味です。
.RE
.RS 4
.Sp
通底するPoファイルは次のオプションも受け付けます。すなわち\fBporefs\fR, \fBcopyright-holder\fR, \fBmsgid-bugs-address\fR, \fBpackage-name\fR, \fBpackage-version\fR, \fBwrap-po\fRです。
.RE
.SS ドキュメントファイルの操作
.IX Subsection "ドキュメントファイルの操作"
.IP read($$$) 4
.IX Item "read($$$)"
既存の配列 \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR の末尾に別の入力文書データを加えます。
.Sp
この関数は2つの必須の実引数と1つの省略できる実引数を取ります。
* ディスクから読むファイル名
* POファイルで参照を構成するときにファイル名として使う名前
* そのファイルを読むために使う文字集合（既定でUTF\-8）
.Sp
この配列 \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR にはこの入力文書のデータが別の意味合いを持つ文字列の配列として保管されています。
* 文字列 \f(CW$textline\fR には入力テキストデータのそれぞれの行が含まれます。
* 文字列 \f(CW\*(C`$filename:$linenum\*(C'\fR には位置が含まれており「参照」と呼ばれます（\f(CW\*(C`linenum\*(C'\fRは1始まりです）。
.Sp
パースは一切行わないことに注意してください。入力ファイルがドキュメントに格納した時点で \fBparse()\fR 関数を使用するべきです。
.IP write($) 4
.IX Item "write($)"
与えたファイル名で翻訳済みドキュメントを書き出します。
.Sp
この翻訳された文書データは以下によって与えられます。
* \f(CW\*(C`$self\->docheader()\*(C'\fR はプラグインのヘッダテキストを保有します。また、
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR は配列に翻訳されたメインのテキストのそれぞれの行を保有します。
.SS "PO ファイルの操作"
.IX Subsection "PO ファイルの操作"
.IP readpo($) 4
.IX Item "readpo($)"
既存の入力 PO に、(引数で渡した名前の) ファイルの内容を追加します。古い内容は破棄されません。
.IP writepo($) 4
.IX Item "writepo($)"
抽出した PO ファイルを与えたファイル名で書き出します。
.IP \fBstats()\fR 4
.IX Item "stats()"
現在までに翻訳した内容に関する統計を返します。msgfmt \-\-statistic が出力する統計とは同じとは限らないことに注意してください。ここでは、PO ファイルの最新の使用法についての統計ですが、msgfmt が報告するのは、ファイルの状態についてです。これは、Locale::Po4a::Po::stats_get 関数を入力した PO ファイルに適用するラッパーです。サンプルは以下のようになります:
.Sp
.Vb 1
\& [po4a ドキュメントの通常の使用...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "$percent\e%（$queries中$hit）の文字列の翻訳があります。\en";
.Ve
.SS 追加内容の操作
.IX Subsection "追加内容の操作"
.IP addendum($) 4
.IX Item "addendum($)"
追加内容とは何か、や、翻訳者はどのように書いたらよいのかといった情報は、\fBpo4a\fR\|(7) を参照してください。翻訳したドキュメントに追加内容を適用するには、この関数に単純にファイル名を渡し、実行するだけです ;)
.Sp
この関数は、エラー時に null 以外の数値を返します。
.SH 派生パーサ作成時に使用する内部関数
.IX Header "派生パーサ作成時に使用する内部関数"
.SS 入力と出力
.IX Subsection "入力と出力"
入力を取得し出力を返すために4つの関数が提供されています。これらはPerlのshift/unshiftとpush/popに大変似ています。
.PP
.Vb 4
\& * Perlのshiftは最初の配列の要素を返し配列からその要素を切り落とします。
\& * Perlのunshiftは配列に要素をその配列の最初の要素として前置します。
\& * Perlのpopは配列の最後の要素を返しそれを配列から切り落とします。
\& * Perlのpushは配列にその配列の最後の要素として後置します。
.Ve
.PP
1つ目の対は入力についてのもので、2つ目は出力についてのものです。覚え方としては、入力ではshiftにより得られる最初の行に関心があり、出力ではpushがするように結果を末尾に加えたいのだ、とできます。
.IP \fBshiftline()\fR 4
.IX Item "shiftline()"
この関数は解析される最初の行と配列\f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fRからの（配列として詰め込まれた）参照を返し、これらの配列の最初2つの要素を除きます。ここで参照は文字列\f(CW\*(C`$filename:$linenum\*(C'\fRによって与えられます。
.IP unshiftline($$) 4
.IX Item "unshiftline($$)"
入力文書の最後にshiftされた行をunshiftして対応する参照を\f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fRの先頭に戻します。
.IP pushline($) 4
.IX Item "pushline($)"
\&\f(CW\*(C`{$self\->{{TT}{doc_out}}\*(C'\fRの末尾に開業を押し込みます。
.IP \fBpopline()\fR 4
.IX Item "popline()"
\&\f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fRの末尾から最後に押し込んだ行を取り出します。
.SS 文字列を翻訳可能としてマーク
.IX Subsection "文字列を翻訳可能としてマーク"
翻訳するべきテキストを扱う関数を一つ用意しています。
.IP translate($$$) 4
.IX Item "translate($$$)"
必須の引数:
.RS 4
.IP \- 2
翻訳する文字列
.IP \- 2
この文字列の参照 (言い換えると、入力ファイルの場所)
.IP \- 2
文字列の型 (つまり構造上の役割をテキストで説明したもの。\fBLocale::Po4a::Po::gettextization()\fR で使用します。 \fBpo4a\fR\|(7) の \fBgettext 化: どのように動作しますか?\fR 節も参照してください)
.RE
.RS 4
.Sp
この関数は、いくつか追加引数を取れます。ハッシュとしてまとめなければなりません。例えば:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP \fBwrap\fR 4
.IX Item "wrap"
文字列中の空白が重要でないとして扱うかどうかを示す真偽値です。重要でない場合、この関数は、翻訳を探したり抽出したりする前の文字列を納め、翻訳を折り返します。
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
折り返す列です（既定ではTransTractor作成時に指定された \fBwrapcol\fR 値か76）。
.Sp
負値は既定値から差し引きます。
.IP \fBcomment\fR 4
.IX Item "comment"
エントリに追加する更なるコメント。
.RE
.RS 4
.Sp
動作:
.IP \- 2
文字列、参照、型を po_out に push します。
.IP \- 2
パーサが doc_out をビルドできるように、文字列の翻訳 (po_in に見つかったもの) を返します。
.IP \- 2
文字列を po_out に送る前や翻訳を返す前に、文字列を再コード化する文字セットを扱います。
.RE
.RS 4
.RE
.SS その他の関数
.IX Subsection "その他の関数"
.IP \fBverbose()\fR 4
.IX Item "verbose()"
TransTractor の生成時に verbose オプションが渡された場合、返します。
.IP \fBdebug()\fR 4
.IX Item "debug()"
TransTractor の生成時に debug オプションが渡された場合、返します。
.IP \fBget_in_charset()\fR 4
.IX Item "get_in_charset()"
この関数はマスター文書の文字集合として与えられる文字集合を返します
.IP \fBget_out_charset()\fR 4
.IX Item "get_out_charset()"
この関数は、出力文書で使用する文字セットを返します（この関数により見付かった入力文書で検出された文字セットを置き換えるのに、大抵の場合で便利です）。
.Sp
コマンドラインで指定した出力文字セットが使われます。指定しない場合は、入力 PO ファイルの文字セットを使用します。入力 PO ファイルにデフォルトの "CHARSET" がある場合は、入力ドキュメントの文字セットを返します。そして、エンコーディングの変換は行われません。
.SH 将来の方向性
.IX Header "将来の方向性"
現在の TransTractor の欠点の一つに、(debconf テンプレートや、.desktop ファイルのような) すべての言語を含む翻訳済みドキュメントを扱えないというものがあります。
.PP
この問題に対処するには、以下のようにインターフェースのみを変更することが必要です:
.IP \- 2
po_in_name (言語ごとのリスト) としてハッシュを取ります
.IP \- 2
対象言語を示すための翻訳する引数を追加します
.IP \- 2
pushline_all 関数を作ります。この関数により全ての言語を対象とする内容のpushlineを生み出します。これにはmapのような構文が使われます。
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
これで十分だといいのですが ;)
.SH 著者
.IX Header "著者"
.Vb 3
\& Denis Barbier