Provided by: po4a_0.41-1_all bug

NAZWA

       Locale::Po4a::TeX - konwersja dokumentow TeX z/do plikow PO

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.

       Locale::Po4a::TeX jest modulem ulatwiajcym tlumaczenie dokumentacji w
       formacie TeX do innych jzykow [uywanych przez ludzi].

       Uytkownicy najprawdopodobniej powinni uywa modulu LaTeX, ktory
       dziedziczy z modulu TeX i zawiera definicj czstych polece LaTeX.

T/LUMACZENIE Z POMOC PO4A::TEX

       Tego modulu mona bezporednio uy do obslugi ogolnych dokumentow w
       formacie TeX. Podzieli on dokument na mniejsze bloki (akapity, bloki
       doslowych tekstow, a nawet jeszcze mniejsze jak tytuly czy indeksy).

       Istnieje kilka opcji (opisanych w nastpnej sekcji), ktore mog dostosowa
       zachowanie do Twoich wymaga. Jeli nie pasuje ono do formatu Twojego
       dokumentu, zachcamy do napisania wlasnego modulu dziedziczcego z tego,
       opisujcego szczegoly formatu. Szczegoly mona znale w sekcji PRACA
       ZMODU/LAMI POCHODNYMI poniej.

       Zachowanie modulu moe by take zmieniane w pliku TeX za pomoc linii
       zaczynajcych si od "% po4a:". Takie zmiany s opisane w sekcji
       DOSTOSOWYWANIE ZA POMOC OPCJI W PLIKU R'OD/LOWYM.

OPCJE AKCEPTOWANE PRZEZ MODU/L

       Opcje tego modulu:

       debug
           Uaktywnia debugowanie kilku wewntrznych mechanizmow modulu.
           Informacje o tym, ktore czci mog by debugowane, mona znale w
           rodlach.

       no_wrap
           Rozdzielona przecinkami lista rodowisk, ktore nie powinny by
           powtornie zawijane.

           Prosz zauway, e rodowiska verbatim i no_wrap si roni. W blokach
           verbatim nie s analizowane polecenia ani komentarze.

           Jeeli rodowisko nie bylo wczeniej zarejestrowane, to po4a zaloy, e
           to rodowisko nie potrzebuje adnych parametrow.

       exclude_include
           Rozdzielona dwukropkami lista plikow, ktore nie powinny by wlczane
           przez \input i \include.

       definitions
           Nazwa pliku zawierajcego definicje dla po4a, jak to zdefiniowano w
           sekcji DOSTOSOWYWANIE ZA POMOC OPCJI W PLIKU R'OD/LOWYM. Mona uy tej
           opcji, jeli nie jest moliwe umieszczenie definicja w tlumaczonym
           dokumencie.

       verbatim
           Rozdzielona przecinkami lista rodowisk, ktore powinny by
           przetwarzane tak, jak zostaly podane.

           Jeeli rodowisko nie bylo wczeniej zarejestrowane, to po4a zaloy, e
           to rodowisko nie potrzebuje adnych parametrow.

       Uycie tych opcji pozwala zmieni zachowanie polece zdefiniowanych w
       domylnych listach.

DOSTOSOWYWANIE ZA POMOC OPCJI W PLIKU R'OD/LOWYM

       Dzialanie modulu TeX moe by zmieniane za pomoc linii zaczynajcych si od
       % po4a:, ktore s interpretowane jako polecenia parsera. Rozpoznawane s
       nastpujce polecenia:

       % po4a: command polecenie1 alias polecenie2
           Mowi, e argumenty polecenia polecenie1 powinny by traktowane jako
           argumenty polecenia polecenie2.

       % po4a: polecenie polecenie1 parametry
           Pozwala szczegolowo opisa parametry polecenia polecenie1. Ta
           informacja zostanie uyta do sprawdzenia liczby i typow parametrow.

           Polecenie polecenie1 moe by poprzedzone przez nastpujce znaki:

           gwiazdka (*)
               po4a wycignie to polecenie z akapitow (jeli jest umieszczone na
               pocztku lub na kocu akapitu). Tlumacze bd musieli wtedy
               przetlumaczy te parametry, ktore s oznaczone jako odpowiednie
               do tlumaczenia.

           plus (+)
               Tak jak w przypadku gwiazdki, to polecenie bdzie wyodrbnione,
               jeeli pojawi si na kocu bloku, ale jego parametry nie zostan
               oddzielnie przetlumaczone. Tlumacz bdzie musial przetlumaczy
               polecenie polczone ze wszystkimi jego parametrami. Pozwala to
               zachowa wicej kontekstu i jest uyteczne dla wszystkich polece,
               przyjmujcych jako parametr krotkie slowo, ktore moe mie wiele
               znacze (i tlumacze).

               Uwaga: w tym przypadku nie trzeba okrela, ktore parametry naley
               tlumaczy, ale po4a musi zna typ i liczb parametrow.

           minus (-)
               W takim wypadku, polecenie nie zostanie wydobyte z adnego
               bloku. Ale jeeli pojawi si samodzielnie w bloku, to tlumaczowi
               zostan pokazane tylko te parametry, ktore zostaly zaznaczone
               jako moliwe do przetlumaczenia. Polecenia te zazwyczaj nie
               powinny by wydzielane z ich akapitow (aby zachowa kontekst),
               ale nie ma adnego powodu, eby mczy tlumacza nimi, jeli caly
               komunikat jest zawarty w takim poleceniu.

           Argument parameters jest zbiorem nawiasow [] (okrelajcych argumenty
           opcjonalne) lub {} (okrelajcych argumenty wymagane).  Aby wskaza, e
           parametr ma zosta przetlumaczony, mona pomidzy tymi nawiasami
           umieci znak podkrelenia (_). Na przyklad:
            % po4a: command *chapter [_]{_}

           To wskazuje, e polecenie chapter ma dwa parametry: opcjonalny
           (krotki tytul) i obowizkowy, oba musz by przetlumaczone.  Aby
           okreli, e polecenie href ma dwa wymagane parametry, oraz e pierwszy
           z nich (URL) ma nie by przetlumaczony, oraz e polecenie to ma nie
           by oddzielone od otaczajcego go akapitu (co pozwala tlumaczowi
           zmieni pozycj linku w zdaniu), mona uy:
            % po4a: command -href {}{_}

           W tym wypadku informacja wskazujca, ktore argumenty musz by
           przetlumaczone jest uywana 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 poniej zostanie uyta do sprawdzenia
           liczby parametrow polecenia \begin oraz pozwala okreli, ktore z
           nich maj by przetlumaczone.  Skladnia argumentu parametry jest taka
           sama, jak dla polece.  Pierwszy parametr polecenia \begin jest nazw
           rodowiska. Lista parametrow nie moe go zawiera. Kilka przykladow:
            % po4a: environment multicols {}
            % po4a: environment equation

           Tak jak dla polece rodowisko moe by poprzedzone plusem (+), aby
           wskaza, e polecenie \begin musi by przetlumaczone wraz ze
           wszystkimi jego argumentami.

       % po4a: separator rodowisko "wyraenie_regularne"
           Wskazuje, e rodowisko powinno by podzielone zgodnie z podanym
           wyraeniem regularnym.

           Wyraenie regularne jest ograniczone cudzyslowami. Nie powinno
           tworzy adnej wstecznych referencji. Jeli potrzeba pogrupowa, to
           naley uy (?:). Moe take wymaga kilku znakow cytowania.

           Na przyklad modul LaTeX uywa wyraenia regularnego "(?:&|\\\\)" ,
           aby osobno przetlumaczy kad komork tabeli (linie s rozdzielone
           przez '\\' a komorki przez '&').

           rodowisko jest rozszerzane do typu wywietlanego pliku PO. Mona tego
           uy, aby pierwszy wymagany argument polecenia title podzieli na
           "\\\\". W tym przypadku rodowiskiem jest title{#1}.

       % po4a: verbatim environment rodowisko
           Okrela, e rodowisko jest rodowiskiem doslownym,tj. takim, w ktorym
           wszelkie komentarze i polecenia s ignorowane.

           Jeeli rodowisko nie bylo wczeniej zarejestrowane, to po4a zaloy, e
           to rodowisko nie potrzebuje adnych parametrow.

PRACA Z MODU/LAMI POCHODNYMI

       pre_trans
       post_trans
       translate
           Funkcje opakowujce translate TransTractora  filtrami uruchamianymi
           przed przetwarzaniem i po nim.

           Komentarze akapitu s wstawiane jako komentarz PO dla pierwszego
           tlumaczonego komunikatu dla tego akapitu.

       get_leading_command($buffer)
           Funkcja zwraca:

           Nazw polecenia
               Jeeli na pocztku podanego bufora nie znaleziono adnego
               polecenia, tekst bdzie pusty. S brane pod uwag tylko te
               polecenia, ktore mona rozdzieli. Hash %separated_command
               zawiera ich list.

           Wariant
               Okrela uyty wariant. Na przyklad gwiazdka (*) moe by dodana na
               kocu sekcji polece, aby okreli e nie powinny by numerowane. W
               tym przypadku pole to bdzie zawiera "*". Jeli wariant nie
               istnieje, pole bdzie pustym lacuchem znakow.

           Tablic par  (typ argumentu, argument)
               Typem argumentu moe by albo "{" (dla argumentow wymaganych),
               albo "[" (dla argumentow opcjonalnych).

           Pozostaly bufor
               Reszta bufora po usuniciu pocztkowego polecenia i jego
               argumentow. Jeli 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 koca bufora.

       translate_buffer
           Rekurencyjnie tlumaczy bufor, wydzielajc z niego pocztkowe i kocowe
           polecenia (ktore powinny by tlumaczone oddzielnie).

           Jeeli w biecym rodowisku zmienna %translate_buffer_env zawiera
           definicj funkcji, to ta funkcja zostanie uyta zamiast
           translate_buffer() do przetlumaczenia zawartoci bufora.

       read
           Przeladowanie funkcji read TransTractora

       read_file
           Rekurencyjnie czyta plik, dodajc te pliki wlczane, ktore nie s
           wymienione w tablicy @exclude_include. Plik wlczane s wyszukiwane
           poleceniem kpsewhich z biblioteki Kpathsea.

           Poza czci wlczania plikow, jest to przekopiowane z funkcji read
           TransTractora.

       parse_definition_file
           Procedura parsowania pliku zawierajcego dyrektyw po4a (definicje
           nowych polece).

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

           Dalsze informacje mona znale w sekcji DOSTOSOWYWANIE ZA POMOC OPCJI
           W PLIKU R'OD/LOWYM.

       is_closed
       docheader

FUNKCJE WEWNTRZNE, uywane do pisania parser'ow

       Funkcje polece i rodowiska pobieraj nastpujce argumenty (oraz dodatkowo
       obiekt $self):

       Nazw polecenia
       Wariant
       Tablica krotek (typ, argument)
       Biece rodowisko

       Pierwsze 3 argumenty s wyodrbniane przez get_leading_command lub
       get_trailing_command.

       Funkcje polece i rodowiska zwracaj tlumaczenia polece z jego
       argumentami i nowe rodowisko.

       Funkcje rodowiska s wywolywane, jeli znaleziono polecenie \begin. S one
       wywolywane z poleceniem \begin i jego argumentami.

       Modul TeX proponuje tylko jedn funkcj polece i jedn funkcj rodowiska:
       generic_command i generic_environment.

       generic_command uywa informacji podanych przez register_generic_command
       albo przez dodanie definicji w pliku TeX:
        % po4a: command polecenie1 parametry

       generic_environment uywa informacji podanych przez
       register_generic_environment albo przez dodanie definicji w pliku TeX:
        % po4a: environment rodowisko parametery

       Obie funkcje tylko przetlumacz parametry, ktore byly okrelone jako
       moliwe do tlumaczenie (z ""). generic_environment doda nazw rodowiska
       do stosu rodowiska, a generic_command doda nazw polecenia, po ktorej
       nastpi identyfikator parametru (jak {#7} lub [#2]).

STATUS MODU/LU

       Modul powinien by bardziej przetestowany.

       Bylo testowany na ksice z dokumentacj Pythona.

LISTA RZECZY DO ZROBIENIA

       Automatyczne wykrywanie nowych polece
           Modul TeX moglby sparsowa argumenty nowego polecenia i sprobowa
           odgadn liczb i typy argumentow oraz czy powinny by tlumaczone, czy
           te nie.

       Tlumaczenie separatora rodowiska
           Kiedy jako separatora rodowiska uyje si \item, to jego argument
           jest dolczany do nastpujcego lacucha znakow.

       Niektore polecenia powinny by dodane do stosu rodowiska.
           Te polecenia powinny by podawane w parach. Umoliwiloby podawanie
           polece zaczynajcych lub koczcych doslowne rodowisko.

       Inne
           Rone inne punkty s oznaczone w rodlach jako "TODO", czyli do
           zrobienia.

ZNANE B/LDY

       Rone punkty s oznaczone w rodlach jako "FIXME", czyli do poprawienia.

ZOBACZ TAKE

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

AUTORZY

        Nicolas Francois <nicolas.francois@centraliens.net>

PRAWA AUTORSKIE I LICENCJA

       Copyright 2004, 2005 by Nicolas FRANCOIS
       <nicolas.francois@centraliens.net>.

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