\*(R". For the sake of simplicity, we assume that the document is well formatted, i.e. that '
' tags are the only tags present, and that this tag is at the very beginning of each paragraph. .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; \& \& # \- push to output the leading tag (untranslated) and the \& # rest of the paragraph (translated) \& $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
Once you've implemented the parse function, you can use your document
class, using the public interface presented in the next section.
.SH "PUBLIC INTERFACE for scripts using your parser"
.IX Header "PUBLIC INTERFACE for scripts using your parser"
.SS "Constructor"
.IX Subsection "Constructor"
.IP "process(%)" 4
.IX Item "process(%)"
This function can do all you need to do with a po4a document in one
invocation. Its arguments must be packed as a hash. \s-1ACTIONS:\s0
.RS 4
.IP "a." 3
.IX Item "a."
Reads all the \s-1PO\s0 files specified in po_in_name
.IP "b." 3
.IX Item "b."
Reads all original documents specified in file_in_name
.IP "c." 3
.IX Item "c."
Parses the document
.IP "d." 3
.IX Item "d."
Reads and applies all the addenda specified
.IP "e." 3
.IX Item "e."
Writes the translated document to file_out_name (if given)
.IP "f." 3
.IX Item "f."
Writes the extracted \s-1PO\s0 file to po_out_name (if given)
.RE
.RS 4
.Sp
\&\s-1ARGUMENTS,\s0 beside the ones accepted by \fBnew()\fR (with expected type):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
List of filenames where we should read the input document.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Charset used in the input document (if it isn't specified, it will try
to detect it from the input document).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Filename where we should write the output document.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Charset used in the output document (if it isn't specified, it will use
the \s-1PO\s0 file charset).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
List of filenames where we should read the input \s-1PO\s0 files from, containing
the translation which will be used to translate the document.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Filename where we should write the output \s-1PO\s0 file, containing the strings
extracted from the input document.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
List of filenames where we should read the addenda from.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Charset for the addenda.
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Create a new po4a document. Accepted options (in the hash passed as a parameter):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Sets the verbosity.
.IP "debug ($)" 4
.IX Item "debug ($)"
Sets the debugging.
.RE
.RS 4
.RE
.SS "Manipulating document files"
.IX Subsection "Manipulating document files"
.IP "read($$)" 4
.IX Item "read($$)"
Add another input document data at the end of the existing array
\&\f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR. The argument is the filename to read. If a second
argument is provided, it is the filename to use in the references.
.Sp
This array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR holds this input document data as an
array of strings with alternating meanings.
* The string \f(CW$textline\fR holding each line of the input text data.
* The string \f(CW\*(C`$filename:$linenum\*(C'\fR holding its location and called as
\*(L"reference\*(R" (\f(CW\*(C`linenum\*(C'\fR starts with 1).
.Sp
Please note that it does not parse anything. You should use the \fBparse()\fR
function when you're done with packing input files into the document.
.IP "write($)" 4
.IX Item "write($)"
Write the translated document to the given filename.
.Sp
This translated document data are provided by:
* \f(CW\*(C`$self\->docheader()\*(C'\fR holding the header text for the plugin, and
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR holding each line of the main translated text in the array.
.SS "Manipulating \s-1PO\s0 files"
.IX Subsection "Manipulating PO files"
.IP "readpo($)" 4
.IX Item "readpo($)"
Add the content of a file (which name is passed as argument) to the
existing input \s-1PO.\s0 The old content is not discarded.
.IP "writepo($)" 4
.IX Item "writepo($)"
Write the extracted \s-1PO\s0 file to the given filename.
.IP "\fBstats()\fR" 4
.IX Item "stats()"
Returns some statistics about the translation done so far. Please note that
it's not the same statistics than the one printed by msgfmt
\&\-\-statistic. Here, it's stats about recent usage of the \s-1PO\s0 file, while
msgfmt reports the status of the file. It is a wrapper to the
Locale::Po4a::Po::stats_get function applied to the input \s-1PO\s0 file. Example
of use:
.Sp
.Vb 1
\& [normal use of the po4a document...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "We found translations for $percent\e% ($hit from $queries) of strings.\en";
.Ve
.SS "Manipulating addenda"
.IX Subsection "Manipulating addenda"
.IP "addendum($)" 4
.IX Item "addendum($)"
Please refer to \fBpo4a\fR\|(7) for more information on what addenda are,
and how translators should write them. To apply an addendum to the translated
document, simply pass its filename to this function and you are done ;)
.Sp
This function returns a non-null integer on error.
.SH "INTERNAL FUNCTIONS used to write derivative parsers"
.IX Header "INTERNAL FUNCTIONS used to write derivative parsers"
.SS "Getting input, providing output"
.IX Subsection "Getting input, providing output"
Four functions are provided to get input and return output. They are very
similar to shift/unshift and push/pop of Perl.
.PP
.Vb 4
\& * Perl shift returns the first array item and drop it from the array.
\& * Perl unshift prepends an item to the array as the first array item.
\& * Perl pop returns the last array item and drop it from the array.
\& * Perl push appends an item to the array as the last array item.
.Ve
.PP
The first pair is about input, while the second is about output. Mnemonic: in
input, you are interested in the first line, what shift gives, and in output
you want to add your result at the end, like push does.
.IP "\fBshiftline()\fR" 4
.IX Item "shiftline()"
This function returns the first line to be parsed and its corresponding
reference (packed as an array) from the array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR and
drop these first 2 array items. Here, the reference is provided by a string
\&\f(CW\*(C`$filename:$linenum\*(C'\fR.
.IP "unshiftline($$)" 4
.IX Item "unshiftline($$)"
Unshifts the last shifted line of the input document and its corresponding
reference back to the head of \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP "pushline($)" 4
.IX Item "pushline($)"
Push a new line to the end of \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP "\fBpopline()\fR" 4
.IX Item "popline()"
Pop the last pushed line from the end of \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.SS "Marking strings as translatable"
.IX Subsection "Marking strings as translatable"
One function is provided to handle the text which should be translated.
.IP "translate($$$)" 4
.IX Item "translate($$$)"
Mandatory arguments:
.RS 4
.IP "\-" 2
A string to translate
.IP "\-" 2
The reference of this string (i.e. position in inputfile)
.IP "\-" 2
The type of this string (i.e. the textual description of its structural role;
used in \fBLocale::Po4a::Po::gettextization()\fR; see also \fBpo4a\fR\|(7),
section \fBGettextization: how does it work?\fR)
.RE
.RS 4
.Sp
This function can also take some extra arguments. They must be organized as
a hash. For example:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP "\fBwrap\fR" 4
.IX Item "wrap"
boolean indicating whether we can consider that whitespaces in string are
not important. If yes, the function canonizes the string before looking for
a translation or extracting it, and wraps the translation.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
the column at which we should wrap (default: 76).
.IP "\fBcomment\fR" 4
.IX Item "comment"
an extra comment to add to the entry.
.RE
.RS 4
.Sp
Actions:
.IP "\-" 2
Pushes the string, reference and type to po_out.
.IP "\-" 2
Returns the translation of the string (as found in po_in) so that the
parser can build the doc_out.
.IP "\-" 2
Handles the charsets to recode the strings before sending them to
po_out and before returning the translations.
.RE
.RS 4
.RE
.SS "Misc functions"
.IX Subsection "Misc functions"
.IP "\fBverbose()\fR" 4
.IX Item "verbose()"
Returns if the verbose option was passed during the creation of the
TransTractor.
.IP "\fBdebug()\fR" 4
.IX Item "debug()"
Returns if the debug option was passed during the creation of the
TransTractor.
.IP "detected_charset($)" 4
.IX Item "detected_charset($)"
This tells TransTractor that a new charset (the first argument) has been
detected from the input document. It can usually be read from the document
header. Only the first charset will remain, coming either from the
\&\fBprocess()\fR arguments or detected from the document.
.IP "\fBget_out_charset()\fR" 4
.IX Item "get_out_charset()"
This function will return the charset that should be used in the output
document (usually useful to substitute the input document's detected charset
where it has been found).
.Sp
It will use the output charset specified in the command line. If it wasn't
specified, it will use the input \s-1PO\s0's charset, and if the input \s-1PO\s0 has the
default \*(L"\s-1CHARSET\*(R",\s0 it will return the input document's charset, so that no
encoding is performed.
.IP "recode_skipped_text($)" 4
.IX Item "recode_skipped_text($)"
This function returns the recoded text passed as argument, from the input
document's charset to the output document's one. This isn't needed when
translating a string (\fBtranslate()\fR recodes everything itself), but it is when
you skip a string from the input document and you want the output document to
be consistent with the global encoding.
.SH "FUTURE DIRECTIONS"
.IX Header "FUTURE DIRECTIONS"
One shortcoming of the current TransTractor is that it can't handle
translated document containing all languages, like debconf templates, or
\&.desktop files.
.PP
To address this problem, the only interface changes needed are:
.IP "\-" 2
take a hash as po_in_name (a list per language)
.IP "\-" 2
add an argument to translate to indicate the target language
.IP "\-" 2
make a pushline_all function, which would make pushline of its content for
all languages, using a map-like syntax:
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
Will see if it's enough ;)
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 3
\& Denis Barbier