Provided by: po4a_0.33.3-1_all bug

NAZWA

       Locale::Po4a::TeX - Konwersja dokumentów TeX z/do plików PO

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.

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).

       Istnieje kilka opcji (opisanych w następnej sekcji), które mogą
       dostosować zachowanie do Twoich wymagań. Jeśli nie pasuje ono do
       formatu Twojego dokumentu, zachęcamy do napisania własnego modułu
       dziedziczącego z tego, opisującego szczegóły formatu. Szczegóły można
       znaleźć w sekcji "Pisanie modułów pochodnych" poniżej.

       Zachowanie modułu może być także zmieniane w pliku TeX za pomocą linii
       zaczynających się od "% po4a:". Takie zmiany są opisane w sekcji
       DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM.

OPCJE AKCEPTOWANE PRZEZ TEN MODUŁ

       Opcje tego modułu:

       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.

       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.

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

       definicje
           Nazwa pliku zawierającego definicje dla po4a, jak to zdefiniowano w
           sekcji 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.

       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.

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

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 "% po4a:", które są interpretowane jako polecenia parsera.
       Rozpoznawane są następujące polecenia:

       % po4a: command polecenie1 alias polecenie2
           Mówi, że argumenty polecenia polecenie1 powinny być traktowane jako
           argumenty polecenia polecenie2.

       % po4a: polecenie polecenie1 parametry
           Pozwala szczegółowo opisać parametry polecenia polecenie1. Ta
           informacja zostanie użyta do sprawdzenia liczby i typów parametrów.

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

           gwiazdka (*)
               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.

           plus (+)
               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.

           minus (-)
               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.

           Argument 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.

       % po4a: environment rodowisko parametery
           Pozwala to zdefiniować parametry akceptowane przez środowisko
           rodowisko.  Ta informacja później zostanie użyta do sprawdzenia
           liczby parametrów polecenia \begin oraz pozwala określić, które z
           nich mają być przetłumaczone.  Składnia argumentu parametry jest
           taka sama, jak dla poleceń.  Pierwszy parametr polecenia \begin
           jest nazwą środowiska. Lista parametrów nie może go zawierać. Kilka
           przykładów:
            % po4a: environment multicols {}
            % po4a: environment equation

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

       % po4a: separator rodowisko "wyraenie_regularne"
           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 '&').

           Środowisko jest rozszerzane do typu wyświetlanego pliku PO. Można
           tego użyć, aby pierwszy wymagany argument polecenia title podzielić
           na "\\\\". W tym przypadku środowiskiem jest title{#1}.

       % po4a: verbatim environment rodowisko
           Określa, że 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.

PRACA Z MODUŁAMI POCHODNYMI

       pre_trans
       post_trans
       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.

       get_leading_command($buffer)
           Funkcja zwraca:

           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ę.

           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.

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

           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.

       get_trailing_command($buffer)
           To samo co, get_leading_command, ale dla poleceń z końca bufora.

       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.

       read
           Przeładowanie funkcji read TransTractora

       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
           w katalogu dokumentu źródłowego lub w katalogu określonym przez
           zmienną środowiskową TEXINPUTS.

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

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

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

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

       is_closed
       docheader

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

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

       Nazwę polecenia
       Wariant
       Tablica krotek (typ, argument)
       Bieżące środowisko

       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 polecenie1 parametry

       generic_environment używa informacji podanych przez
       register_generic_environment albo przez dodanie definicji w pliku TeX:
        % po4a: environment rodowisko 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]).

STATUS MODUŁU

       Moduł powinien być bardziej przetestowany.

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

LISTA RZECZY DO ZROBIENIA

       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.

       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.

       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.

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

ZNANE BŁĘDY

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

ZOBACZ TAKŻE

       po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::LaTeX(3pm).

AUTORZY

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

TŁUMACZENIE

        Robert Luberda <robert@debian.org>

PRAWA AUTORSKIE I LICENCJA

       Copyright 2004, 2005 by 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).