
        *****************************************************
        *           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 NAZWA

Locale::Po4a::TeX - convert TeX documents and derivatives from/to PO files

=head1 OPIS

Celem projektu po4a ("PO for anything") 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.

Locale::Po4a::TeX jest modułem ułatwiającym tłumaczenie dokumentacji w formacie TeX do innych języków [używanych przez ludzi].

Użytkownicy najprawdopodobniej powinni używać modułu LaTeX, który dziedziczy z modułu TeX i zawiera definicję częstych poleceń LaTeX.

=head1 TŁUMACZENIE Z POMOCĄ PO4A::TEX

Tego modułu można bezpośrednio użyć do obsługi ogólnych dokumentów w formacie TeX. Podzieli on dokument na mniejsze bloki (akapity, bloki dosłowych tekstów, a nawet jeszcze mniejsze jak tytuły czy indeksy).

There are some options (described in the next section) that can customize this behavior.  If this doesn't fit to your document format you're encouraged to write your own derivative module from this, to describe your format's details.  See the section B<WRITING DERIVATIVE MODULES> below, for the process description.

This module can also be customized by lines starting with "% po4a:" in the TeX file. This process is described in the B<INLINE CUSTOMIZATION> section.

=head1 OPCJE AKCEPTOWANE PRZEZ MODUŁ

Opcje tego modułu:

=over 4

=item B<debug>

Uaktywnia debugowanie kilku wewnętrznych mechanizmów modułu. Informacje o tym, które części mogą być debugowane, można znaleźć w źródłach.

=item B<no_wrap>

Rozdzielona przecinkami lista środowisk, które nie powinny być powtórnie zawijane.

Proszę zauważyć, że środowiska verbatim i no_wrap się różnią. W blokach verbatim nie są analizowane polecenia ani komentarze.

Jeżeli środowisko nie było wcześniej zarejestrowane, to po4a założy, że to środowisko nie potrzebuje żadnych parametrów.

=item B<exclude_include>

Rozdzielona dwukropkami lista plików, które nie powinny być włączane przez \input i \include.

=item B<definitions>

Nazwa pliku zawierającego definicje dla po4a, jak to zdefiniowano w sekcji B<DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM>. Można użyć tej opcji, jeśli nie jest możliwe umieszczenie definicja w tłumaczonym dokumencie.

=item B<verbatim>

Rozdzielona przecinkami lista środowisk, które powinny być przetwarzane tak, jak zostały podane.

Jeżeli środowisko nie było wcześniej zarejestrowane, to po4a założy, że to środowisko nie potrzebuje żadnych parametrów.

=back

Użycie tych opcji pozwala zmienić zachowanie poleceń zdefiniowanych w domyślnych listach.

=head1 DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM

Działanie modułu TeX może być zmieniane za pomocą linii zaczynających się od B<% po4a:>, które są interpretowane jako polecenia parsera. Rozpoznawane są następujące polecenia:

=over 4

=item B<% po4a: command> I<polecenie1> B<alias> I<polecenie2>

Mówi, że argumenty polecenia I<polecenie1> powinny być traktowane jako argumenty polecenia I<polecenie2>.

=item B<% po4a: polecenie> I<polecenie1> I<parametry>

Pozwala szczegółowo opisać parametry polecenia I<polecenie1>. Ta informacja zostanie użyta do sprawdzenia liczby i typów parametrów.

Polecenie I<polecenie1> może być poprzedzone przez następujące znaki: 

=over 4

=item gwiazdka (B<*>)

po4a wyciągnie to polecenie z akapitów (jeśli jest umieszczone na początku lub na końcu akapitu). Tłumacze będą musieli wtedy przetłumaczyć te parametry, które są oznaczone jako odpowiednie do tłumaczenia.

=item plus (B<+>)

Tak jak w przypadku gwiazdki, to polecenie będzie wyodrębnione, jeżeli pojawi się na końcu bloku, ale jego parametry nie zostaną oddzielnie przetłumaczone. Tłumacz będzie musiał przetłumaczyć polecenie połączone ze wszystkimi jego parametrami. Pozwala to zachować więcej kontekstu i jest użyteczne dla wszystkich poleceń, przyjmujących jako parametr krótkie słowo, które może mieć wiele znaczeń (i tłumaczeń).

Uwaga: w tym przypadku nie trzeba określać, które parametry należy tłumaczyć, ale po4a musi znać typ i liczbę parametrów.

=item minus (B<->)

W takim wypadku, polecenie nie zostanie wydobyte z żadnego bloku. Ale jeżeli pojawi się samodzielnie w bloku, to tłumaczowi zostaną pokazane tylko te parametry, które zostały zaznaczone jako możliwe do przetłumaczenia. Polecenia te zazwyczaj nie powinny być wydzielane z ich akapitów (aby zachować kontekst), ale nie ma żadnego powodu, żeby męczyć tłumacza nimi, jeśli cały komunikat jest zawarty w takim poleceniu.

=back

Argument I<parameters> jest zbiorem nawiasów [] (określających argumenty
opcjonalne) lub {} (określających argumenty wymagane).
Aby wskazać, że parametr ma zostać przetłumaczony, można pomiędzy
tymi nawiasami umieścić znak podkreślenia (_). Na przykład:
 % po4a: command *chapter [_]{_}

To wskazuje, że polecenie chapter ma dwa parametry: opcjonalny
(krótki tytuł) i obowiązkowy, oba muszą być przetłumaczone.
Aby określić, że polecenie href ma dwa wymagane parametry,
oraz że pierwszy z nich (URL) ma nie być przetłumaczony, oraz
że polecenie to ma nie być oddzielone od otaczającego go akapitu
(co pozwala tłumaczowi zmienić pozycję linku w zdaniu), można użyć:
 % po4a: command -href {}{_}

W tym wypadku informacja wskazująca, które argumenty muszą być przetłumaczone jest używana tylko wtedy, gdy akapit jest utworzony tylko z tej komendy href.

=item B<% po4a: environment> I<środowisko> I<parametery>

This permits to define the parameters accepted by the I<env> environment.
This information is later used to check the number of arguments of the
\begin command, and permit to specify which one must be translated.
The syntax of the I<parameters> argument is the same as described for the
others commands.
The first parameter of the \begin command is the name of the environment.
This parameter must not be specified in the list of parameters. Here are
some examples:
 % po4a: environment multicols {}
 % po4a: environment equation

Tak jak dla poleceń I<środowisko> może być poprzedzone plusem (+), aby wskazać, że polecenie \begin musi być przetłumaczone wraz ze wszystkimi jego argumentami.

=item B<% po4a: separator> I<środowisko> B<">I<wyrażenie_regularne>B<">

Wskazuje, że środowisko powinno być podzielone zgodnie z podanym wyrażeniem regularnym.

Wyrażenie regularne jest ograniczone cudzysłowami. Nie powinno tworzyć żadnej wstecznych referencji. Jeśli potrzeba pogrupować, to należy użyć (?:). Może także wymagać kilku znaków cytowania.

Na przykład moduł LaTeX używa wyrażenia regularnego "(?:&|\\\\)" , aby osobno przetłumaczyć każdą komórkę tabeli (linie są rozdzielone przez '\\' a komórki przez '&').

The notion of environment is expanded to the type displayed in the PO file. This can be used to split on "\\\\" in the first mandatory argument of the title command.  In this case, the environment is title{#1}.

=item B<% po4a: verbatim environment> I<środowisko>

Określa, że I<środowisko> jest środowiskiem dosłownym,tj. takim, w którym wszelkie komentarze i polecenia są ignorowane.

Jeżeli środowisko nie było wcześniej zarejestrowane, to po4a założy, że to środowisko nie potrzebuje żadnych parametrów.

=back

=head1 PRACA Z MODUŁAMI POCHODNYMI

=over 4

=item B<pre_trans>

=item B<post_trans>

=item B<add_comment>

Add a string as a comment to be added around the next translated element. This is mostly useful to the texinfo module, as comments are automatically handled in TeX.

=item B<translate>

Funkcje opakowujące translate TransTractora  filtrami uruchamianymi przed przetwarzaniem i po nim.

Komentarze akapitu są wstawiane jako komentarz PO dla pierwszego tłumaczonego komunikatu dla tego akapitu.

=item B<get_leading_command>($buffer)

Funkcja zwraca:

=over 4

=item Nazwę polecenia

Jeżeli na początku podanego bufora nie znaleziono żadnego polecenia, tekst będzie pusty. Są brane pod uwagę tylko te polecenia, które można rozdzielić. Hash %separated_command zawiera ich listę.

=item Wariant

Określa użyty wariant. Na przykład gwiazdka (*) może być dodana na końcu sekcji poleceń, aby określić że nie powinny być numerowane. W tym przypadku pole to będzie zawierać "*". Jeśli wariant nie istnieje, pole będzie pustym łańcuchem znaków.

=item Tablicę par  (typ argumentu, argument)

Typem argumentu może być albo "{" (dla argumentów wymaganych), albo "[" (dla argumentów opcjonalnych).

=item Pozostały bufor

Reszta bufora po usunięciu początkowego polecenia i jego argumentów. Jeśli nie znaleziono polecenia, oryginalny bufor jest zwracany niezmieniony w tym polu.

=back

=item B<get_trailing_command>($buffer)

To samo co, B<get_leading_command>, ale dla poleceń z końca bufora.

=item B<translate_buffer>

Rekurencyjnie tłumaczy bufor, wydzielając z niego początkowe i końcowe polecenia (które powinny być tłumaczone oddzielnie).

Jeżeli w bieżącym środowisku zmienna %translate_buffer_env zawiera definicję funkcji, to ta funkcja zostanie użyta zamiast translate_buffer() do przetłumaczenia zawartości bufora.

=item B<read>

Przeładowanie funkcji read() TransTractora.

=item B<read_file>

Rekurencyjnie czyta plik, dodając te pliki włączane, które nie są wymienione w tablicy @exclude_include. Plik włączane są wyszukiwane poleceniem B<kpsewhich> z biblioteki Kpathsea.

Poza częścią włączania plików, jest to przekopiowane z funkcji read TransTractora.

=back



=over 4

=item B<parse_definition_file>

Procedura parsowania pliku zawierającego dyrektywę po4a (definicje nowych poleceń).

=item B<parse_definition_line>

Przetwarza linię definicji w formacie "% po4a: ".

Dalsze informacje można znaleźć w sekcji B<DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM>.

=item B<is_closed>

=item B<parse>

=item B<docheader>

=back

=head1 FUNKCJE WEWNĘTRZNE, używane do pisania parserów

Funkcje poleceń i środowiska pobierają następujące argumenty (oraz dodatkowo obiekt $self):

=over 

=item Nazwę polecenia

=item Wariant

=item Tablica krotek (typ, argument) 

=item Bieżące środowisko

=back

Pierwsze 3 argumenty są wyodrębniane przez get_leading_command lub get_trailing_command.

Funkcje poleceń i środowiska zwracają tłumaczenia poleceń z jego argumentami i nowe środowisko.

Funkcje środowiska są wywoływane, jeśli znaleziono polecenie \begin. Są one wywoływane z poleceniem \begin i jego argumentami.

Moduł TeX proponuje tylko jedną funkcję poleceń i jedną funkcję środowiska: generic_command i generic_environment.

generic_command używa informacji podanych przez 
register_generic_command albo przez dodanie definicji w pliku TeX:
 % po4a: command I<polecenie1> I<parametry>

generic_environment używa informacji podanych przez 
register_generic_environment albo przez dodanie definicji w pliku TeX:
 % po4a: environment I<środowisko> I<parametery>

Obie funkcje tylko przetłumaczą parametry, które były określone jako możliwe do tłumaczenie (z ""). generic_environment doda nazwę środowiska do stosu środowiska, a generic_command doda nazwę polecenia, po której nastąpi identyfikator parametru (jak {#7} lub [#2]).

=head1 STATUS MODUŁU

Moduł powinien być bardziej przetestowany.

Było testowany na książce z dokumentacją Pythona.

=head1 LISTA RZECZY DO ZROBIENIA

=over 4

=item Automatyczne wykrywanie nowych poleceń

Moduł TeX mógłby sparsować argumenty nowego polecenia i spróbować odgadnąć liczbę i typy argumentów oraz czy powinny być tłumaczone, czy też nie.

=item Tłumaczenie separatora środowiska

Kiedy jako separatora środowiska użyje się \item, to jego argument jest dołączany do następującego łańcucha znaków.

=item Niektóre polecenia powinny być dodane do stosu środowiska.

Te polecenia powinny być podawane w parach. Umożliwiłoby podawanie poleceń zaczynających lub kończących dosłowne środowisko.

=item Inne

Różne inne punkty są oznaczone w źródłach jako "TODO", czyli do zrobienia.

=back

=head1 ZNANE BŁĘDY

Różne punkty są oznaczone w źródłach jako "FIXME", czyli do poprawienia.

=head1 ZOBACZ TAKŻE

L<Locale::Po4a::LaTeX(3pm)|Locale::Po4a::LaTeX>, L<Locale::Po4a::TransTractor(3pm)|Locale::Po4a::TransTractor>, L<po4a(7)|po4a.7>

=head1 AUTORZY

 Nicolas François <nicolas.francois@centraliens.net>


=head1 TŁUMACZENIE

 Robert Luberda <robert@debian.org>

=head1 PRAWA AUTORSKIE I LICENCJA

Copyright © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

Program jest wolnym oprogramowaniem; można go redystrybuować i/lub modyfikować zgodnie z warunkami licencji GPL (patrz plik COPYING).

