
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 ИМЕ

Locale::Po4a::TransTractor - генерички транс(латор екс)трактор.

=head1 ОПИС

Циљ po4a (PO for anything – PO за било шта) пројекта је да поједностави превођење (и што је још интересантније, одржавање превода) употребом gettext алата на деловима на којима се не очекује њихова употреба, као што је документација.

Ова класа је предак сваког po4a парсера који се користи за парсирање документа, за претрагу стрингова који могу да се преведу, за њихово издвајање у PO фајл и њихову замену са својим преводима у излазном документу.

Формалније речено, она узима као улаз следеће аргументе:

=over 2

=item -

документ који се преводи;

=item -

PO фајл са преводима који треба се употребе.

=back

Као излаз, она креира:

=over 2

=item -

други PO фајл, који настаје као резултат издвајања преводивих стрингова из улазног документа;

=item -

преведени документ, са истом структуром као и онај са улаза, али у коме су сви стрингови замењени са преводима пронађеним у PO фајлу који је наведен у улазу.

=back

Ево графичке представе овога:

   Улазни документ --\                             /---> Излазни документ
                      \                           /       (преведен)
                       +-> parse() функција -----+
                      /                           \
   Улазни PO --------/                             \---> Излазни PO
                                                         (издвојен)

=head1 ФУНКЦИЈЕ КОЈЕ БИ ВАШ ПАРСЕР ТРЕБАЛО ДА ПРЕИНАЧИ

=over 4

=item parse()

Ово је место на којем се обавља сав посао: парсирање улазних докумената, генерисање излаза и издвајање преводивих стрингова. Ово је прилично једноставно употребом приложених функција приказаних у одељку B<ИНТЕРНЕ ФУНКЦИЈЕ> испод. Погледајте такође B<СИНОПСИС>, који представља пример.

Ову функцију позива функција process() испод, али ако изаберете да користите функцију new(), и да ручно додате садржај у свој документ, ову функцију ћете морати сами да позовете.

=item docheader()

Ова функција враћа заглавље које би требало да се дода у креирани документ, прописно цитирано тако да буде коментар у циљном језику. Погледајте одељак B<Едуковање девелопера у вези превода>, из L<po4a(7)|po4a.7>, у вези онога за шта је добра ова функција.

=back

=head1 СИНОПСИС

Следећи пример парсира листу пасуса који почињу са „<p>”. Ради једноставности, претпостављамо да је документ добро форматиран, тј. да су ’<p>’ ознаке једине присутне ознаке, и да се ова ознака налази на самом почетку сваког пасуса.

 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/<p>/ && !$first--; ) {
               # Није први пут да видимо <p>.
               # Поново постави текућу линију у улаз,
               # и стави изграђени пасус у излаз
               $self->unshiftline($line,$lref);

               # Сада када је документ формиран, преведи га:
               #   - Уклони водећу ознаку
               $paragraph =~ s/^<p>//s;

               #   - гурни у излаз водећу ознаку (непреведену) као и
               #     остатак пасуса (преведен)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Додај на крај пасуса
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Поново иницијализуј петљу
           ($line,$lref)=$self->shiftline();
       }
       # Није добијена дефинисана линија? Крај улазног фајла.
       return;
   }
 }

Једном када сте имплементирали функцију за парсирање, можете да употребите своју класу документа, користећи јавни интерфејс који је представљен у следећем одељку.

=head1 ЈАВНИ ИНТЕРФЕЈС за скрипте које користе ваш парсер

=head2 Конструктор

=over 4

=item process(%)

Ова функција може да уради све што је потребно да се уради са po4a документом у једном позиву. Њени аргументи морају да се упакују као хеш. АКЦИЈЕ:

=over 3

=item а.

Чита све PO фајлове наведене у po_in_name

=item б.

Чита све оригиналне документе наведене у file_in_name

=item г.

Парсира документ

=item д.

Чита и примењује све наведене додатке

=item ђ.

Уписује преведени документ у file_out_name (ако је задато)

=item е.

Уписује издвојени PO фајл у po_out_name (ако је задато)

=back

АРГУМЕНТИ, уз оне које прихвата new() (са очекиваним типом):

=over 4

=item file_in_name (@)

Листа имена фајлова из којих би требало да прочитамо улазни документ.

=item file_in_charset ($)

Скуп карактера који се користи у улазном документу (ако није наведен, користиће се UTF-8).

=item file_out_name ($)

Име фајла у који би требало да упишемо излазни документ.

=item file_out_charset ($)

Скуп карактера који се користи у излазном документу (ако није наведен, користиће се UTF-8).

=item po_in_name (@)

Листа имена фајлова из којих би требало да се читају PO фајлови, они који садрже преведене стрингове који ће се користити за превод документа.

=item po_out_name ($)

Име фајла у који би требало да упишемо излазни PO фајл, који садржи стрингове издвојене из улазног документа.

=item addendum (@)

Листа имена фајлова из којих треба да се читају додаци.

=item addendum_charset ($)

Скуп карактера за додатке.

=back

=item new(%)

Креира нови po4a документ. Прихватају се опције (у хешу који се прослеђује као параметар):

=over 4

=item verbose ($)

Поставља детаљност извештавања.

=item debug ($)

Поставља режим исправљања грешака.

=item wrapcol ($)

Колона око које би требало да се врши обавијање текста у излазном документу (подразумевано: 76).

Негативна вредност значи да се линије уопште не обавијају.

=back

Такође прихвата и следеће опције за одговарајуће Po-фајлове: B<porefs>, B<copyright-holder>, B<msgid-bugs-address>, B<package-name>, B<package-version>, B<wrap-po>.

=back

=head2 Манипулација фајловима докумената

=over 4

=item read($$$)

Додаје податке из другог улазног документа на крај постојећег низа C<< @{$self->{TT}{doc_in}} >>.

Ова функција узима два обавезна аргумента и један необавезни.
 * Име фајла који се чита са диска;
 * Име које ће се користити као име фајла када се буду изграђивале референце у PO фајлу;
 * Скуп карактера који ће се употребити за читање тог фајла (подразумевано је UTF-8)

Низ C<< @{$self->{TT}{doc_in}} >> чува податке из овог улазни документа
као низ стрингова са наизменичним значењима.
 * Стринг C<$textline> који држи сваку линију улазног текста.
 * Стринг C<< $filename:$linenum >> који држи његову локацију и који се
   зове "reference" (C<linenum> почиње од 1).

Имајте на уму, молим вас, да ово још ништа не парсира. Када завршите са паковањем улазних фајлова у документ, требало би да употребите функцију parse().

=item write($)

Уписује преведени документ у фајл са датим именом.

Ови подаци преведеног документа се добијају из:
 * C<< $self->docheader() >> који чува текст заглавља за модул додатка, и
 * C<< @{$self->{TT}{doc_out}} >> који у низу чува сваку линију главног преведеног текста.

=back

=head2 Манипулација PO фајловима

=over 4

=item readpo($)

Додаје садржај фајла (чије име је прослеђено као аргумент) постојећем улазном PO. Стари садржај се не одбацује.

=item writepo($)

Уписује издвојени PO фајл у дато име фајла.

=item stats()

Враћа неке статистичке податке у вези до сада одрађеног превода. Имајте не уму, молим вас, да ово није иста статистика коју исписује msgfmt --statistic. Овде је то статистика у вези скорашње употребе PO фајла, док msgfmt пријављује статус фајла. То је функција која обавија функцију Locale::Po4a::Po::stats_get function примењену на улазни PO фајл. Пример употребе:

    [нормална употреба po4a документа...]

    ($percent,$hit,$queries) = $document->stats();
    print "Пронашли смо преводе за $percent\%  ($hit од $queries) стрингова.\n";

=back

=head2 Манипулација додацима

=over 4

=item addendum($)

Молимо погледајте L<po4a(7)|po4a.7> за више информација о томе шта су додаци, и како би преводиоци требало да их пишу. Да бисте применили додатак на преведени документ, једноставно проследите име његовог фајла овој функцији и то је то ;)

У случају грешке, ова функција враћа цео број различит од нуле.

=back

=head1 ИНТЕРНЕ ФУНКЦИЈЕ које се користе за писање изведених парсера

=head2 Добављање улаза, обезбеђивање излаза

За преузимање улаза и враћање излаза се користе четири функције. Оне су врло сличне са shift/unshift и push/pop у језику Perl.

 * Perl shift враћа прву ставку низа и уклања је из њега.
 * Perl unshift ставља ставку на почетак низа као прву.
 * Perl pop враћа последњу ставку низа и уклања је из њега.
 * Perl push додаје ставку у низ као последњу.

Први пар се тиче улаза, док је други у вези излаза. Да се лакше упамти: за улаз вам је од интереса прва линија, а то је управо оно што враћа shift, док за излаз желите да свој резултат додате на крај, као што то ради push.

=over 4

=item shiftline()

Ова функција враћа прву линију која треба да се парсира у њену одговарајућу референцу (упаковано као низ) из низа C<< @{$self->{TT}{doc_in}} >> и уклања ове прве 2 ставке низа. Референцу овде обезбеђује стринг C<< $filename:$linenum >>.

=item unshiftline($$)

Unshift-ује последњу shift-овану линију улазног документа и њену одговарајућу референцу назад на почетак C<< {$self->{TT}{doc_in}} >>.

=item pushline($)

Ради push нове линије на крај C<< {$self->{TT}{doc_out}} >>.

=item popline()

Ради pop последње push-оване линије са краја C<< {$self->{TT}{doc_out}} >>.

=back

=head2 Обележавање стрингова као преводивих

Достављена је једна функција која обрађује текст предвиђен за превођење.

=over 4

=item translate($$$)

Обавезни аргументи:

=over 2

=item -

Стринг за превођење

=item -

Референца овог стринга (тј. позиција у улазном фајлу)

=item -

Тип овог стринга (тј. текстуални опис његове структурне улоге; користи се у Locale::Po4a::Po::gettextization(); погледајте такође L<po4a(7)|po4a.7>, одељак B<На који начин програм функционише?>)

=back

И ова функција може да узме неколико додатних аргумената. Они морају да се организују у хеш. На пример:

  $self->translate("string","ref","type",
                   'wrap' => 1);

=over 

=item B<wrap>

логичка вредност која назначава можемо ли претпоставити да празни карактери у стрингу нису битни. Ако је истинита, функција канонизује стринг пре тражења превода или његовог издвајања, и обавија превод.

=item B<wrapcol>

колона око које би требало да се обавија текст (подразумевано: вредност B<wrapcol> наведена током креирања TransTractor или 76).

Негативна вредност ће се одузети од подразумеване.

=item B<comment>

допунски коментар који се додаје ставци.

=back

Акције:

=over 2

=item -

Ради push стринга, референце и типа у po_out.

=item -

Враћа стринг превода (као што је пронађен у po_in) и омогућава да парсер изгради doc_out.

=item -

Обрађује скупове карактера како би се стрингови рекодирали пре него што се пошаљу у po_out и пре враћања превода.

=back

=back

=head2 Разне функције

=over 4

=item verbose()

Враћа информацију да ли је током креирања објекта TransTractor прослеђена опција детаљног извештавања.

=item debug()

Враћа информацију да ли је приликом креирања објекта TransTractor била прослеђена опција детаљнијег извештавања.

=item get_in_charset()

Ова функција враћа скуп карактера који је наведен као мастер скуп карактера

=item get_out_charset()

Ова функција ће да врати скуп карактера који би требало да се користи у излазном документу (обично је корисно за замену скупа карактера детектованог у улазном документу у коме је пронађен).

Користиће излазни скуп карактера наведен у командној линији. Ако није био задат, користиће се скуп карактера улазног PO, а ако улазни PO има подразумевану вредност „CHARSET”, вратиће скуп карактера улазног документа, тако да се не обавља кодирање..

=back

=head1 СМЕРНИЦЕ ЗА БУДУЋНОСТ

Једна од лоших страна текуће TransTractor класе је да не може обрађивати преведене документе који садрже све језике, као што су debconf шаблони, или .desktop фајлови.

Како би се решио проблем, неопходне су само следеће измене интерфејса:

=over 2

=item -

po_in_name треба да узима хеш (листу за сваки појединачни језик)

=item -

додати аргумент функцији translate који наводи циљни језик

=item -

креирати функцију pushline_all, која би одрадила pushline свог садржаја за све језике, користећи синтаксу сличну са map:

    $self->pushline_all({ "Description[".$langcode."]=".
                          $self->translate($line,$ref,$langcode)
                        });

=back

Видећемо да ли је ово довољно ;)

=head1 АУТОРИ

 Дени Барбије <barbier@linuxfr.org>
 Мартин Квинсон (mquinson#debian.org)
 Жорди Вилалта <jvprat@gmail.com>

