Provided by: po4a_0.41-1_all bug

NAZWA

       Locale::Po4a::TransTractor - ogolny modul wyodrbniania tlumacze.

OPIS

       Celem projektu po4a ("PO for anything") jest ulatwienie tlumacze (oraz,
       co ciekawsze, zarzdzania tlumaczeniami) przy uyciu narzdzi gettext w
       tych obszarach, gdzie nie byly uywane, jak na przyklad w obszarze
       dokumentacji.

       Ta klasa jest przodkiem wszystkich parserow po4a uywanych do
       przetwarzania dokumentu w poszukiwaniu komunikatow do przetlumaczenia,
       wyodrbniania ich do pliku PO oraz zastpowania ich tlumaczeniami w
       wyjciowym dokumencie.

       Bardziej formalnie mowic, przyjmuje nastpujce argumenty jako wejcie:

       - dokument do przetlumaczenia;

       - plik PO zawierajcy tlumaczenia do uycia.

       Jako wynik dostajemy:

       - inny plik PO, czego wynikiem jest wycignicie komunikatow moliwych do
         przetlumaczenia z dokumentu wejciowego;

       - przetlumaczony dokument o takiej samej strukturze, co dokument
         wejciowy, ale ze wszystkimi komunikatami moliwymi do przetlumaczenia
         zamienionymi na tlumaczenia znalezione w wejciowym pliku PO.

       Graficzna reprezentacja tego procesu:

          Dokument wejciowy --\                          /--> Dokument wyjciowy
                                \                        /     (przetlumaczony)
                                 +-> funkcja parse() ---+
                                /                        \
          Wejciowy PO --------/                          \--> Wyjciowy PO
                                                               (wyodrbniony)

FUNKCJE, KT'ORE TW'OJ PARSER POWINIEN NADPISA

       parse()
           Jest to miejsce, gdzie odbywa si cala praca: parsowanie dokumentow
           wejciowych, generowanie wyjcia, wyodrbnianie komunikatow do
           przetlumaczenia. Jest to bardzo proste, jeli uyje si funkcji
           opisanych poniej, w sekcji FUNKCJE WEWNTRZNE. Patrz take sekcja
           SK/LADNIA, zawierajca przyklad.

           Ta funkcja jest wywolywana przez ponisz funkcj proces(), ale jeeli
           wybierze si uycie funkcji new() i rczenie si doda zawarto do
           dokumentu, trzeba bdzie wywola t funkcj samemu.

       docheader()
           Funkcja zwraca naglowek, ktory powinien zosta dodany do
           wygenerowanego dokumentu, odpowiednio przygotowany, tak eby mogl by
           komentarzem w jzyku docelowym. Aby dowiedzie si, do czego to sluy,
           prosz przeczyta sekcj Przekazywanie deweloperom wiedzy o
           t/lumaczeniu w po4a(7).

SK/LADNIA

       Nastpujcy przyklad przetwarza list akapitow rozpoczynajcych si od
       "<p>". Dla uproszczenia, zakladamy, e dokument jest dobrze
       sformatowany, tj. wystpuj tylko elementy "<p>" i s one umieszczone na
       samym pocztku kadego akapitu.

        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--; ) {
                      # Nie po raz pierwszy widzimy <p>.
                      # Wlo z powrotem biec lini do wejcia,
                      #  i dodaj zbudowany akapit do wyjcia
                      $self->unshiftline($line,$lref);

                      # Teraz, gdy dokument jest sformatowany, przetlumaczmy go:
                      #   - Usunicie pocztkowych tagow
                      $paragraph =~ s/^<p>//s;

                      #   - dodanie do wyjcia pocztkowego elementu (nieprzetlumaczonego)
                      #     i reszty akapitu (przetlumaczonej)
                      $self->pushline(  "<p>"
                                      . $document->translate($paragraph,$pararef)
                                      );

                      next PARAGRAPH;
                  } else {
                      # Dodanie do akapitu
                      $paragraph .= $line;
                      $pararef = $lref unless(length($pararef));
                  }

                  # Ponowna inicjacja ptli
                  ($line,$lref)=$self->shiftline();
              }
              # Nie dostalimy zdefiniowanej linii? Koniec pliku wejciowego.
              return;
          }
        }

       Po zaimplementowaniu funkcji parsujcej, mona uy wlasnych klas
       dokumentu, uywajc publicznego interfejsu zaprezentowanego w nastpnym
       rozdziale.

INTERFEJS PUBLICZNY dla skrypt'ow uywajcych Twojego parsera

   Konstruktor
       process(%)
           Funkcja zrobi  w jednym uruchomieniu wszystko, co tylko trzeba
           zrobi z dokumentem po4a. Jej argumenty musz by umieszczone w hashu.
           AKCJE:

           a. Czyta wszystkie pliki okrelone w po_in_name

           b. Czyta wszystkie oryginalne dokumenty okrelone w file_in_name

           c. Przetwarza (parsuje) dokument

           d. Dodaje i stosuje wszystkie podane zalczniki

           e. Zapisuje przetlumaczony dokument do file_out_name (jeli podano)

           f. Zapisuje wygenerowany plik PO do po_out_name (jeli podano)

           ARGUMENTY, poza tymi akceptowanymi przez new() (z oczekiwanym
           typem):

           file_in_name (@)
               Lista nazw plikow, z ktorych powinnimy odczyta plik wejciowy.

           file_in_charset ($)
               Kodowanie znakow dokumentu wejciowego (jeli nie podano, nastpi
               proba okrelenia kodowania z dokumentu wejciowego).

           file_out_name ($)
               Nazwa pliku, do ktorego naley zapisa wynikowy dokument.

           file_out_charset ($)
               Kodowanie znakow wyjciowego dokumentu (jeli nie podano, bdzie
               uyte kodowanie znakow pliku PO).

           po_in_name (@)
               Lista nazw plikow, z ktorych powinnimy odczyta wejciowe pliki
               PO zawierajce tlumaczenia, ktore bd uyte podczas tlumaczenia
               dokumentu.

           po_out_name ($)
               Nazwa pliku, do ktorego powinien by zapisany wynikowy plik PO,
               zawierajcy komunikaty wycignite z dokumentu wejciowego.

           addendum (@)
               Lista nazw plikow, z ktorych powinnimy odczyta pliki
               zalcznikow.

           addendum_charset ($)
               Kodowanie znakow zalcznikow.

       new(%)
           Tworzy nowy dokument po4a. Akceptowane opcje (bdce w hashu):

           verbose ($)
               Ustawia gadatliwo.

           debug ($)
               Ustawia debugowanie.

   Manipulowanie plikami z dokumentacj
       read($)
           Dodaje kolejny dokument wejciowy na koniec istniejcego dokumentu.
           Argumentem jest nazwa pliku do odczytania.

           Prosz zauway, e to niczego nie przetwarza. Naley uy funkcji parse()
           po zakoczeniu pakowania plikow wejciowych do dokumentu.

       write($)
           Zapisuje przetlumaczony dokument do pliku o podanej nazwie.

   Manipulowanie plikami PO
       readpo($)
           Dodaje zawarto pliku (ktorego nazwa jest podawana w argumencie) do
           istniejcego pliku wejciowego PO. Stara zawarto nie jest tracona.

       writepo($)
           Zapisuje wygenerowany plik PO do pliku o podanej nazwie.

       stats()
           Zwraca statystyki dotyczce tlumacze. Prosz zauway, e nie s to te
           same statystyki, ktore wypisuje msgfmt --statistic. Tutaj s to
           statystyki o obecnym wykorzystaniu pliku PO, podczas gdy msgfmt
           wywietla status tego pliku. Funkcja jest opakowaniem funkcji
           Locale::Po4a::Po::stats_get zastosowanej do wejciowego pliku PO.
           Przyklad uycia:

               [zwykle uycie dokumentu po4a ...]

               ($percent,$hit,$queries) = $document->stats();
               print "Znalelimy tlumaczenia $percent\% ($hit z $queries) komunikatow.\n";

   Manipulowanie za/lcznikami
       addendum($)
           Wicej informacji o tym, czym s zalczniki, i jak tlumacze powinni je
           pisa, mona znale w po4a(7). Aby doda zalcznik do przetlumaczonego
           dokumentu, wystarczy po prostu tej funkcji przekaza nazw pliku, w
           ktorym si znajduje, i gotowe ;)

           Funkcja zwraca liczb nie bdc nullem lub bld.

FUNKCJE WEWNTRZNE, uywane do pisania parser'ow

   Pobieranie wejcia, dostarczanie wyjcia
       Dostarczone s cztery funkcje pobierania wejcia i zwracania wyjcia. S
       one bardzo podobne do shift/unshift i push/pop. Pierwsza para dotyczy
       wejcia, a druga - wyjcia. Mnemonik: w wejciu interesuje Ci pierwsza
       linia, co daje shift, a w wyjciu chcesz dosta wynik na kocu, tak jak do
       robi push.

       shiftline()
           Funkcja zwraca kolejn lini z doc_in do przetworzenia oraz jej
           odnonik (spakowany jako tablica).

       unshiftline($$)
           Zwraca z powrotem lini dokumentu wejciowego i jej odnonik.

       pushline($)
           Dodaje now lini na koniec doc_out.

       popline()
           Pobiera ostatnio wstawion lini z doc_out.

   Zaznaczanie /lacuch'ow znak'ow jako moliwych do przet/lumaczenia
       Dostarczona jest jedna funkcja obslugujca tekst, ktory powinien by
       przetlumaczony.

       translate($$$)
           Argumenty obowizkowe:

           - Lacuch znakow do przetlumaczenia

           - Odnonik tego komunikatu (tj. pozycja w pliku wejciowym)

           - Typ tego komunikatu (tj. tekstowy opis jego roli w strukturze;
             uywany w Locale::Po4a::Po::gettextization(); patrz take po4a(7),
             sekcja Proces przekszta/lcania do formatu gettext: jak to dzia/la?)

           Funkcja przyjmuje take kilka dodatkowych argumentow. Musz by
           zorganizowane jako hash. Na przyklad:

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

           wrap
               flaga logiczna okrelajca, czy traktujemy biale znaki w
               komunikacie jako nieistotne. Jeli tak, to funkcja przed
               wyszukaniem lub wycigniciem tlumaczenia kanonizuje komunikat, a
               nastpnie zawija tekst tlumaczenia.

           wrapcol
               kolumna, w ktorej tekst powinien by zawijany (domylnie: 76).

           comment
               dodatkowy komentarz do dodania do wpisu.

           Akcje:

           - Dodaje nowy komunikat, odnonik i typ do po_out.

           - Zwraca tlumaczenie tekstu (znalezione w po_in), tak e parser moe
             zbudowa doc_out.

           - Obsluguje kodowania znakow, aby zmieni kodowanie komunikatow
             przed wyslaniem do po_out i przed zwroceniem tlumacze.

   R'one funkcje
       verbose()
           Zwraca informacj, czy podczas uruchomienia TransTractora, podano
           opcj verbose.

       debug()
           Zwraca informacj, czy podczas uruchomienia TransTractora podano
           opcj debug.

       detected_charset($)
           Mowi TransTractorowi, e w dokumencie rodlowym wykryto nowe
           kodowanie znakow (podane jako pierwszy argument wywolania). Zwykle
           kodowanie moe by odczytane z naglowka dokumentu. Pozostawione bdzie
           tylko pierwsze kodowanie znakow, pochodzce albo z argumentow
           funkcji process(), albo z dokumentu.

       get_out_charset()
           Funkcja zwraca kodowanie znakow, ktore powinno by uyte w dokumencie
           wyjciowym (zazwyczaj uyteczne do zamienienia wykrytego kodowania
           znakow dokumentu wejciowego, tam gdzie zostal znaleziony).

           Uyje wyjciowego kodowania znakow podanego w linii polece. Jeli go
           nie podano, uyje kodowania znakow wejciowego pliku PO, a jeeli jako
           to kodowanie w pliku byl ustawiony domylny tekst "CHARSET", to
           zwroci kodowanie znakow wejciowego dokumentu, tak e nie zostanie
           przeprowadzona adna konwersja kodowa.

       recode_skipped_text($)
           Funkcja zwraca tekst przekazany jako argument przekodowany z
           kodowania znakow dokumentu wejciowego na kodowanie znakow dokumentu
           wyjciowego. Nie jest to potrzebne podczas tlumaczenia komunikatu
           (translate() wszystko przekodowuje samodzielnie), ale wtedy, gdy
           pominito komunikat z dokumentu wejciowego, a dokument wyjciowy
           powinien mie spojne kodowanie znakow.

DALSZE WSKAZ'OWKI

       Mankamentem obecnego TransTractora jest brak obslugi dokumentow
       zawierajcych wszystkie jzyki naraz, jak na przyklad szablony debconf
       lub pliki .desktop.

       Aby rozwiza ten problem, jedynymi potrzebnymi zmianami w interfejsie s:

       - pobieranie hasha jak po_in_name (lista dla jzyka)

       - dodawanie argumentu do przetlumaczenia, wskazujc jzyk docelowy

       - stworzenie funkcj pushline_all, ktora robilaby pushline jej zawartoci
         dla wszystkich jzykow, uywajc skladni podobnej do skladni map:

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

       Zobaczymy, czy to wystarczy ;)

AUTORZY

        Denis Barbier <barbier@linuxfr.org>
        Martin Quinson (mquinson#debian.org)
        Jordi Vilalta <jvprat@gmail.com>