Provided by: po4a_0.52-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 PRACA ZMODUŁAMI POCHODNYMI 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 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.

       definitions
           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
           This permits to define the parameters accepted by the env environment.  This
           information is latter used to check the number of arguments of the \begin command, and
           permit to specify which one must be translated.  The syntax of the parameters argument
           is the same as described for the ??? 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ń środowisko może być poprzedzone plusem (+), aby wskazać, że
           polecenie \begin musi być przetłumaczone wraz ze wszystkimi jego argumentami.

       % po4a: separator środowisko "wyrażenie_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 poleceniem kpsewhich z biblioteki
           Kpathsea.

           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

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

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