.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::TransTractor 3"
.TH Locale::Po4a::TransTractor 3 "2012-05-17" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAZWA"
.IX Header "NAZWA"
Locale::Po4a::TransTractor \- ogólny moduł wyodrębniania tłumaczeń.
.SH "OPIS"
.IX Header "OPIS"
Celem projektu po4a (\*(L"\s-1PO\s0 for anything\*(R") jest ułatwienie tłumaczeń (oraz, co
ciekawsze, zarządzania tłumaczeniami) przy użyciu narzędzi gettext w tych
obszarach, gdzie nie były używane, jak na przykład w obszarze dokumentacji.
.PP
Ta klasa jest przodkiem wszystkich parserów po4a używanych do przetwarzania
dokumentu w poszukiwaniu komunikatów do przetłumaczenia, wyodrębniania ich
do pliku \s-1PO\s0 oraz zastępowania ich tłumaczeniami w wyjściowym dokumencie.
.PP
Bardziej formalnie mówiąc, przyjmuje następujące argumenty jako wejście:
.IP "\-" 2
dokument do przetłumaczenia;
.IP "\-" 2
plik \s-1PO\s0 zawierający tłumaczenia do użycia.
.PP
Jako wynik dostajemy:
.IP "\-" 2
inny plik \s-1PO\s0, czego wynikiem jest wyciągnięcie komunikatów możliwych do
przetłumaczenia z dokumentu wejściowego;
.IP "\-" 2
przetłumaczony dokument o takiej samej strukturze, co dokument wejściowy,
ale ze wszystkimi komunikatami możliwymi do przetłumaczenia zamienionymi na
tłumaczenia znalezione w wejściowym pliku \s-1PO\s0.
.PP
Graficzna reprezentacja tego procesu:
.PP
.Vb 6
\&   Dokument wejściowy \-\-\e                          /\-\-> Dokument wyjściowy
\&                         \e                        /     (przetłumaczony)
\&                          +\-> funkcja parse() \-\-\-+
\&                         /                        \e
\&   Wejściowy PO \-\-\-\-\-\-\-\-/                          \e\-\-> Wyjściowy PO
\&                                                        (wyodrębniony)
.Ve
.SH "FUNKCJE, KTÓRE TWÓJ PARSER POWINIEN NADPISAĆ"
.IX Header "FUNKCJE, KTÓRE TWÓJ PARSER POWINIEN NADPISAĆ"
.IP "\fIparse()\fR" 4
.IX Item "parse()"
Jest to miejsce, gdzie odbywa się cała praca: parsowanie dokumentów
wejściowych, generowanie wyjścia, wyodrębnianie komunikatów do
przetłumaczenia. Jest to bardzo proste, jeśli użyje się funkcji opisanych
poniżej, w sekcji \fB\s-1FUNKCJE\s0 WEWNĘTRZNE\fR. Patrz także sekcja \fBSKŁADNIA\fR,
zawierająca przykład.
.Sp
Ta funkcja jest wywoływana przez poniższą funkcję \fIproces()\fR, ale jeżeli
wybierze się użycie funkcji \fInew()\fR i ręczenie się doda zawartość do
dokumentu, trzeba będzie wywołać tę funkcję samemu.
.IP "\fIdocheader()\fR" 4
.IX Item "docheader()"
Funkcja zwraca nagłówek, który powinien zostać dodany do wygenerowanego
dokumentu, odpowiednio przygotowany, tak żeby mógł być komentarzem w języku
docelowym. Aby dowiedzieć się, do czego to służy, proszę przeczytać sekcję
\&\fBPrzekazywanie deweloperom wiedzy o tłumaczeniu\fR w \fIpo4a\fR\|(7).
.SH "SKŁADNIA"
.IX Header "SKŁADNIA"
Następujący przykład przetwarza listę akapitów rozpoczynających się od
\&\*(L"<p>\*(R". Dla uproszczenia, zakładamy, że dokument jest dobrze sformatowany,
tj. występują tylko elementy \*(L"<p>\*(R" i są one umieszczone na samym początku
każdego akapitu.
.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/<p>/ && !$first\-\-; ) {
\&               # Nie po raz pierwszy widzimy <p>. 
\&               # Włóż z powrotem bieżącą linię do wejścia,
\&               #  i dodaj zbudowany akapit do wyjścia
\&               $self\->unshiftline($line,$lref);
\&              
\&               # Teraz, gdy dokument jest sformatowany, przetłumaczmy go:
\&               #   \- Usunięcie początkowych tagów
\&               $paragraph =~ s/^<p>//s;
\&
\&               #   \- dodanie do wyjścia początkowego elementu (nieprzetłumaczonego)
\&               #     i reszty akapitu (przetłumaczonej)
\&               $self\->pushline(  "<p>"
\&                               . $document\->translate($paragraph,$pararef)
\&                               );
\&
\&               next PARAGRAPH;
\&           } else {
\&               # Dodanie do akapitu
\&               $paragraph .= $line;
\&               $pararef = $lref unless(length($pararef));
\&           }
\&
\&           # Ponowna inicjacja pętli
\&           ($line,$lref)=$self\->shiftline();
\&       }
\&       # Nie dostaliśmy zdefiniowanej linii? Koniec pliku wejściowego.
\&       return;
\&   }
\& }
.Ve
.PP
Po zaimplementowaniu funkcji parsującej, można użyć własnych klas dokumentu,
używając publicznego interfejsu zaprezentowanego w następnym rozdziale.
.SH "INTERFEJS PUBLICZNY dla skryptów używających Twojego parsera"
.IX Header "INTERFEJS PUBLICZNY dla skryptów używających Twojego parsera"
.SS "Konstruktor"
.IX Subsection "Konstruktor"
.IP "process(%)" 4
.IX Item "process(%)"
Funkcja zrobi  w jednym uruchomieniu wszystko, co tylko trzeba zrobić z
dokumentem po4a. Jej argumenty muszą być umieszczone w hashu. \s-1AKCJE:\s0
.RS 4
.IP "a." 3
.IX Item "a."
Czyta wszystkie pliki określone w po_in_name
.IP "b." 3
.IX Item "b."
Czyta wszystkie oryginalne dokumenty określone w file_in_name
.IP "c." 3
.IX Item "c."
Przetwarza (parsuje) dokument
.IP "d." 3
.IX Item "d."
Dodaje i stosuje wszystkie podane załączniki
.IP "e." 3
.IX Item "e."
Zapisuje przetłumaczony dokument do file_out_name (jeśli podano)
.IP "f." 3
.IX Item "f."
Zapisuje wygenerowany plik \s-1PO\s0 do po_out_name (jeśli podano)
.RE
.RS 4
.Sp
\&\s-1ARGUMENTY\s0, poza tymi akceptowanymi przez \fInew()\fR (z oczekiwanym typem):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Lista nazw plików, z których powinniśmy odczytać plik wejściowy.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Kodowanie znaków dokumentu wejściowego (jeśli nie podano, nastąpi próba
określenia kodowania z dokumentu wejściowego).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nazwa pliku, do którego należy zapisać wynikowy dokument.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Kodowanie znaków wyjściowego dokumentu (jeśli nie podano, będzie użyte
kodowanie znaków pliku \s-1PO\s0).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Lista nazw plików, z których powinniśmy odczytać wejściowe pliki \s-1PO\s0
zawierające tłumaczenia, które będą użyte podczas tłumaczenia dokumentu.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nazwa pliku, do którego powinien być zapisany wynikowy plik \s-1PO\s0, zawierający
komunikaty wyciągnięte z dokumentu wejściowego.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Lista nazw plików, z których powinniśmy odczytać pliki załączników.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Kodowanie znaków załączników.
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Tworzy nowy dokument po4a. Akceptowane opcje (będące w hashu):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Ustawia gadatliwość.
.IP "debug ($)" 4
.IX Item "debug ($)"
Ustawia debugowanie.
.RE
.RS 4
.RE
.SS "Manipulowanie plikami z dokumentacją"
.IX Subsection "Manipulowanie plikami z dokumentacją"
.IP "read($)" 4
.IX Item "read($)"
Dodaje kolejny dokument wejściowy na koniec istniejącego
dokumentu. Argumentem jest nazwa pliku do odczytania.
.Sp
Proszę zauważyć, że to niczego nie przetwarza. Należy użyć funkcji \fIparse()\fR
po zakończeniu pakowania plików wejściowych do dokumentu.
.IP "write($)" 4
.IX Item "write($)"
Zapisuje przetłumaczony dokument do pliku o podanej nazwie.
.SS "Manipulowanie plikami \s-1PO\s0"
.IX Subsection "Manipulowanie plikami PO"
.IP "readpo($)" 4
.IX Item "readpo($)"
Dodaje zawartość pliku (którego nazwa jest podawana w argumencie) do
istniejącego pliku wejściowego \s-1PO\s0. Stara zawartość nie jest tracona.
.IP "writepo($)" 4
.IX Item "writepo($)"
Zapisuje wygenerowany plik \s-1PO\s0 do pliku o podanej nazwie.
.IP "\fIstats()\fR" 4
.IX Item "stats()"
Zwraca statystyki dotyczące tłumaczeń. Proszę zauważyć, że nie są to te same
statystyki, które wypisuje msgfmt \-\-statistic. Tutaj są to statystyki o
obecnym wykorzystaniu pliku \s-1PO\s0, podczas gdy msgfmt wyświetla status tego
pliku. Funkcja jest opakowaniem funkcji Locale::Po4a::Po::stats_get
zastosowanej do wejściowego pliku \s-1PO\s0. Przykład użycia:
.Sp
.Vb 1
\&    [zwykłe użycie dokumentu po4a ...]
\&
\&    ($percent,$hit,$queries) = $document\->stats();
\&    print "Znaleźliśmy tłumaczenia $percent\e% ($hit z $queries) komunikatów.\en";
.Ve
.SS "Manipulowanie załącznikami"
.IX Subsection "Manipulowanie załącznikami"
.IP "addendum($)" 4
.IX Item "addendum($)"
Więcej informacji o tym, czym są załączniki, i jak tłumacze powinni je
pisać, można znaleźć w \fIpo4a\fR\|(7). Aby dodać załącznik do
przetłumaczonego dokumentu, wystarczy po prostu tej funkcji przekazać nazwę
pliku, w którym się znajduje, i gotowe ;)
.Sp
Funkcja zwraca liczbę nie będącą nullem lub błąd.
.SH "FUNKCJE WEWNĘTRZNE, używane do pisania parserów"
.IX Header "FUNKCJE WEWNĘTRZNE, używane do pisania parserów"
.SS "Pobieranie wejścia, dostarczanie wyjścia"
.IX Subsection "Pobieranie wejścia, dostarczanie wyjścia"
Dostarczone są cztery funkcje pobierania wejścia i zwracania wyjścia. Są one
bardzo podobne do shift/unshift i push/pop. Pierwsza para dotyczy wejścia, a
druga \- wyjścia. Mnemonik: w wejściu interesuje Cię pierwsza linia, co daje
shift, a w wyjściu chcesz dostać wynik na końcu, tak jak do robi push.
.IP "\fIshiftline()\fR" 4
.IX Item "shiftline()"
Funkcja zwraca kolejną linię z doc_in do przetworzenia oraz jej odnośnik
(spakowany jako tablica).
.IP "unshiftline($$)" 4
.IX Item "unshiftline($$)"
Zwraca z powrotem linię dokumentu wejściowego i jej odnośnik.
.IP "pushline($)" 4
.IX Item "pushline($)"
Dodaje nową linię na koniec doc_out.
.IP "\fIpopline()\fR" 4
.IX Item "popline()"
Pobiera ostatnio wstawioną linię z doc_out.
.SS "Zaznaczanie łańcuchów znaków jako możliwych do przetłumaczenia"
.IX Subsection "Zaznaczanie łańcuchów znaków jako możliwych do przetłumaczenia"
Dostarczona jest jedna funkcja obsługująca tekst, który powinien być
przetłumaczony.
.IP "translate($$$)" 4
.IX Item "translate($$$)"
Argumenty obowiązkowe:
.RS 4
.IP "\-" 2
Łańcuch znaków do przetłumaczenia
.IP "\-" 2
Odnośnik tego komunikatu (tj. pozycja w pliku wejściowym)
.IP "\-" 2
Typ tego komunikatu (tj. tekstowy opis jego roli w strukturze; używany w
\&\fILocale::Po4a::Po::gettextization()\fR; patrz także \fIpo4a\fR\|(7), sekcja
\&\fBProces przekształcania do formatu gettext: jak to działa?\fR)
.RE
.RS 4
.Sp
Funkcja przyjmuje także kilka dodatkowych argumentów. Muszą być
zorganizowane jako hash. Na przykład:
.Sp
.Vb 2
\&  $self\->translate("string","ref","type",
\&                   \*(Aqwrap\*(Aq => 1);
.Ve
.IP "\fBwrap\fR" 4
.IX Item "wrap"
flaga logiczna określająca, czy traktujemy białe znaki w komunikacie jako
nieistotne. Jeśli tak, to funkcja przed wyszukaniem lub wyciągnięciem
tłumaczenia kanonizuje komunikat, a następnie zawija tekst tłumaczenia.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
kolumna, w której tekst powinien być zawijany (domyślnie: 76).
.IP "\fBcomment\fR" 4
.IX Item "comment"
dodatkowy komentarz do dodania do wpisu.
.RE
.RS 4
.Sp
Akcje:
.IP "\-" 2
Dodaje nowy komunikat, odnośnik i typ do po_out.
.IP "\-" 2
Zwraca tłumaczenie tekstu (znalezione w po_in), tak że parser może zbudować
doc_out.
.IP "\-" 2
Obsługuje kodowania znaków, aby zmienić kodowanie komunikatów przed
wysłaniem do po_out i przed zwróceniem tłumaczeń.
.RE
.RS 4
.RE
.SS "Różne funkcje"
.IX Subsection "Różne funkcje"
.IP "\fIverbose()\fR" 4
.IX Item "verbose()"
Zwraca informację, czy podczas uruchomienia TransTractora, podano opcję
verbose.
.IP "\fIdebug()\fR" 4
.IX Item "debug()"
Zwraca informację, czy podczas uruchomienia TransTractora podano opcję
debug.
.IP "detected_charset($)" 4
.IX Item "detected_charset($)"
Mówi TransTractorowi, że w dokumencie źródłowym wykryto nowe kodowanie
znaków (podane jako pierwszy argument wywołania). Zwykle kodowanie może być
odczytane z nagłówka dokumentu. Pozostawione będzie tylko pierwsze kodowanie
znaków, pochodzące albo z argumentów funkcji \fIprocess()\fR, albo z dokumentu.
.IP "\fIget_out_charset()\fR" 4
.IX Item "get_out_charset()"
Funkcja zwraca kodowanie znaków, które powinno być użyte w dokumencie
wyjściowym (zazwyczaj użyteczne do zamienienia wykrytego kodowania znaków
dokumentu wejściowego, tam gdzie został znaleziony).
.Sp
Użyje wyjściowego kodowania znaków podanego w linii poleceń. Jeśli go nie
podano, użyje kodowania znaków wejściowego pliku \s-1PO\s0, a jeżeli jako to
kodowanie w pliku był ustawiony domyślny tekst \*(L"\s-1CHARSET\s0\*(R", to zwróci
kodowanie znaków wejściowego dokumentu, tak że nie zostanie przeprowadzona
żadna konwersja kodowań.
.IP "recode_skipped_text($)" 4
.IX Item "recode_skipped_text($)"
Funkcja zwraca tekst przekazany jako argument przekodowany z kodowania
znaków dokumentu wejściowego na kodowanie znaków dokumentu wyjściowego. Nie
jest to potrzebne podczas tłumaczenia komunikatu (\fItranslate()\fR wszystko
przekodowuje samodzielnie), ale wtedy, gdy pominięto komunikat z dokumentu
wejściowego, a dokument wyjściowy powinien mieć spójne kodowanie znaków.
.SH "DALSZE WSKAZÓWKI"
.IX Header "DALSZE WSKAZÓWKI"
Mankamentem obecnego TransTractora jest brak obsługi dokumentów
zawierających wszystkie języki naraz, jak na przykład szablony debconf lub
pliki .desktop.
.PP
Aby rozwiązać ten problem, jedynymi potrzebnymi zmianami w interfejsie są:
.IP "\-" 2
pobieranie hasha jak po_in_name (lista dla języka)
.IP "\-" 2
dodawanie argumentu do przetłumaczenia, wskazując język docelowy
.IP "\-" 2
stworzenie funkcję pushline_all, która robiłaby pushline jej zawartości dla
wszystkich języków, używając składni podobnej do składni map:
.Sp
.Vb 3
\&    $self\->pushline_all({ "Description[".$langcode."]=".
\&                          $self\->translate($line,$ref,$langcode) 
\&                        });
.Ve
.PP
Zobaczymy, czy to wystarczy ;)
.SH "AUTORZY"
.IX Header "AUTORZY"
.Vb 3
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
\& Jordi Vilalta <jvprat@gmail.com>
.Ve
