blib::man::TeX(3pm)

NAZWA
Locale::Po4a::TeX - Konwersja dokumentow TeX z/do plikow PO

OPIS
Celem projektu po4a ("po for anything") jest uXatwienie tXumaczen~ (oraz, co ciekawsze, zarzXdzania tXumaczeniami) przy uXyciu narzedzi gettext w tych obszarach, gdzie nie byXy uXywane, jak na przykXad w obszarze dokumentacji.

Locale::Po4a::TeX jest moduXem uXatwiajXcym tXumaczenie dokumentacji w formacie TeX do innych jezykow [uXywanych przez ludzi].

UXytkownicy najprawdopodobniej powinni uXywaae moduXu LaTeX, ktory dziedziczy z moduXu TeX i zawiera definicje czestych polecen~ LaTeX.

TXUMACZENIE Z POMOCX PO4A::TEX
Tego moduXu moXna bezpoXrednio uXyae do obsXugi ogolnych dokumentow w formacie TeX. Podzieli on dokument na mniejsze bloki (akapity, bloki dosXowych tekstow, a nawet jeszcze mniejsze jak tytuXy czy indeksy).

Istnieje kilka opcji (opisanych w nastepnej sekcji), ktore mogX dostosowaae zachowanie do Twoich wymagan~. JeXli nie pasuje ono do formatu Twojego dokumentu, zachecamy do napisania wXasnego moduXu dziedziczXcego z tego, opisujXcego szczegoXy formatu. SzczegoXy moXna znaleXae w sekcji "Pisanie moduXow pochodnych" poniXej.

Zachowanie moduXu moXe byae takXe zmieniane w pliku TeX za pomocX linii zaczynajXcych sie od "% po4a:". Takie zmiany sX opisane w sekcji DOSTOSOWYWANIE ZA POMOCX OPCJI W PLIKU XRODXOWYM.

OPCJE AKCEPTOWANE PRZEZ TEN MODUX
Opcje tego moduXu:

debug
    Uaktywnia debugowanie kilku wewnetrznych mechanizmow moduXu. Informacje o tym, ktore czeXci mogX byae debugowane, moXna znaleXae w XrodXach.

no_wrap
    Rozdzielona przecinaki lista Xrodowiska, ktore nie powinno byae powtornie zawijane.

    Prosze zauwaXyae, Xe Xrodowiska verbatim i no_wrap sie roXniX. W blokach verbatim nie sX analizowane polecenia ani komentarze.

exclude_include
    Rozdzielona dwukropkami lista plikow, ktore nie powinny byae wXXczane przez \input i \include.

definicje
    Nazwa pliku zawierajXcego definicje dla po4a, jak to zdefiniowano w sekcji DOSTOSOWYWANIE ZA POMOCX OPCJI W PLIKU XRODXOWYM. MoXna uXyae tej opcji, jeXli nie jest moXliwe umieszczenie definicja w tXumaczonym dokumencie.

UXycie tych opcji pozwala zmieniae zachowanie polecen~ zdefiniowanych w domyXlnych listach.

DOSTOSOWYWANIE ZA POMOCX OPCJI W PLIKU XRODXOWYM
DziaXanie moduXu TeX moXe byae zmieniane za pomocX linii zaczynajXcych sie od "% po4a:", ktore sX interpretowane jako polecenia parsera. Rozpoznawane sX nastepujXce polecenia:

% po4a: command polecenie1 alias polecenie2
    Mowi, Xe argumenty polecenia polecenie1 powinny byae traktowane jako argumenty polecenia polecenie2.

% po4a: polecenie polecenie1 parametry
    Pozwala szczegoXowo opisaae parametry polecenia polecenie1. Ta informacja zostanie uXyta do sprawdzenia liczby i typow parametrow.

    Polecenie polecenie1 moXe byae poprzedzone przez nastepujXce znaki:

    gwiazdka (*)
        po4a wyciXgnie to polecenie z akapitow (jeXli jest umieszczone na poczXtku lub na kon~cu akapitu). TXumacze bedX musieli wtedy przetXumaczyae te parametry, ktore sX oznaczone jako odpowiednie do tXumaczenia.

    plus (+)
        Tak jak w przypadku gwiazdki, to polecenie bedzie wyodrebnione, jeXeli pojawi sie na kon~cu bloku, ale jego parametry nie zostanX oddzielnie przetXumaczone. TXumacz bedzie musiaX przetXumaczyae polecenie poXXczone ze wszystkimi jego parametrami. Pozwala to zachowaae wiecej kontekstu i jest uXyteczne dla wszystkich polecen~, przyjmujXcych jako parametr krotkie sXowo, ktore moXe mieae wiele znaczen~ (i tXumaczen~).

        Uwaga: w tym przypadku nie trzeba okreXlaae, ktore parametry naleXy tXumaczyae, ale po4a musi znaae typ i liczbe parametrow.

    minus (-)
        W takim wypadku, polecenie nie zostanie wydobyte z Xadnego bloku. Ale jeXeli pojawi sie samodzielnie w bloku, to tXumaczowi zostanX pokazane tylko te parametry, ktore zostaXy zaznaczone jako moXliwe do przetXumaczenia. Polecenia te zazwyczaj nie powinny byae wydzielane z ich akapitow (aby zachowaae kontekst), ale nie ma Xadnego powodu, Xeby meczyae tXumacza nimi, jeXli caXy komunikat jest zawarty w takim poleceniu.

    Argument parameters jest zbiorem nawiasow [] (okreXlajXcych argumenty opcjonalne) lub {} (okreXlajXcych argumenty wymagane). Aby wskazaae, Xe parametr ma zostaae przetXumaczony, moXna pomiedzy tymi nawiasami umieXciae znak podkreXlenia (_). Na przykXad:
     % po4a: command *chapter [_]{_}

    To wskazuje, Xe polecenie chapter ma dwa parametry: opcjonalny (krotki tytuX) i obowiXzkowy, oba muszX byae przetXumaczone. Aby okreXliae, Xe polecenie href ma dwa wymagane parametry, oraz Xe pierwszy z nich (URL) ma nie byae przetXumaczony, oraz Xe polecenie to ma nie byae oddzielone od otaczajXcego go akapitu (co pozwala tXumaczowi zmieniae pozycje linku w zdaniu), moXna uXyae:
     % po4a: command -href {}{_}

    W tym wypadku informacja wskazujXca, ktore argumenty muszX byae przetXumaczone jest uXywana tylko wtedy, gdy akapit jest utworzony tylko z tej komendy href.

% po4a: environment Xrodowisko parametery
    Pozwala to zdefiniowaae parametry akceptowane przez Xrodowisko Xrodowisko. Ta informacja poXniej zostanie uXyta do sprawdzenia liczby parametrow polecenia \begin oraz pozwala okreXliae, ktore z nich majX byae przetXumaczone. SkXadnia argumentu parametry jest taka sama jak dla polecen~. Pierwszy parametr polecenia \begin jest nazwX Xrodowiska. Lista parametrow nie moXe go zawieraae. Kilka przykXadow:
     % po4a: environment multicols {}
     % po4a: environment equation

    Tak jak dla polecen~ Xrodowisko moXe byae poprzedzone plusem (+), aby wskazaae, Xe polecenie \begin musi byae przetXumaczone wraz ze wszystkimi jego argumentami.

% po4a: separator Xrodowisko "wyraXenie_regularne"
    Wskazuje, Xe Xrodowisko powinno byae podzielone zgodnie z podanym wyraXeniem regularnym.

    WyraXenie regularne jest ograniczone cudzysXowami. Nie powinno tworzyae Xadnej wstecznych referencji. JeXli potrzeba pogrupowaae, to naleXy uXyae (?:). MoXe takXe wymagaae kilku znakow cytowania.

    Na przykXad moduX LaTeX uXywa wyraXenia regularnego "(?:&|\\\\)" , aby osobno przetXumaczyae kaXdX komorke tabeli (linie sX rozdzielone przez '\\' a komorki przez '&').

    Xrodowisko jest rozszerzane do typu wyXwietlanego pliku PO. MoXna tego uXyae, aby pierwszy wymagany argument polecenia title podzieliae na "\\\\". W tym przypadku Xrodowiskiem jest title{#1}.

PRACA Z MODUXAMI POCHODNYMI

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

    Komentarze akapitu sX wstawiane jako komentarz PO dla pierwszego tXumaczonego komunikatu dla tego akapitu.

get_leading_command($buffer)
    Funkcja zwraca:

    Nazwe polecenia
        JeXeli na poczXtku podanego bufora nie znaleziono Xadnego polecenia, tekst bedzie pusty. SX brane pod uwage tylko te polecenia, ktore moXna rozdzieliae. Hash %separated_command zawiera ich liste.

    Wariant
        OkreXla uXyty wariant. Na przykXad gwiazdka (*) moXe byae dodana na kon~cu sekcji polecen~, aby okreXliae Xe nie powinny byae numerowane. W tym przypadku pole to bedzie zawieraae "*". JeXli wariant nie istnieje, pole bedzie pustym Xan~cuchem znakow.

    Tablice par  (typ argumentu, argument)
        Typem argumentu moXe byae albo "{" (dla argumentow wymaganych), albo "[" (dla argumentow opcjonalnych).

    PozostaXy bufor
        Reszta bufora po usunieciu poczXtkowego polecenia i jego argumentow. JeXli nie znaleziono polecenia, oryginalny bufor jest zwracany niezmieniony w tym polu.

get_trailing_command($buffer)
    To samo co, get_leading_command, ale dla polecen~ z kon~ca bufora.

translate_buffer
    Rekurencyjnie tXumaczy bufor, wydzielajXc z niego poczXtkowe i kon~cowe polecenia (ktore powinny byae tXumaczone oddzielnie).

read
    PrzeXadowanie funkcji read TransTractora

read_file
    Rekurencyjnie czyta plik, dodajXc te pliki wXXczane, ktore nie sX wymienione w tablicy @exclude_include. Plik wXXczane sX wyszukiwane w katalogu dokumentu XrodXowego lub w katalogu okreXlonym przez zmiennX XrodowiskowX TEXINPUTS.

    Poza czeXciX wXXczania plikow, jest to przekopiowane z funkcji read TransTractora.

parse_definition_file
    Procedura parsowania pliku zawierajXcego dyrektywe po4a (definicje nowych polecen~).

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

    Dalsze informacje moXna znaleXae w sekcji DOSTOSOWYWANIE ZA POMOCX OPCJI W PLIKU XRODXOWYM.

is_closed
docheader

FUNKCJE WEWNETRZNE, uXywane do pisania parserow
Funkcje polecen~ i Xrodowiska pobierajX nastepujXce argumenty (oraz dodatkowo obiekt $self):

Nazwe polecenia
Wariant
Tablica krotek (typ, argument)
BieXXce Xrodowisko

Pierwsze 3 argumenty sX wyodrebniane przez get_leading_command lub get_trailing_command.

Funkcje polecen~ i Xrodowiska zwracajX tXumaczenia polecen~ z jego argumentami i nowe Xrodowisko.

Funkcje Xrodowiska sX wywoXywane, jeXli znaleziono polecenie \begin. SX one wywoXywane z poleceniem \begin i jego argumentami.

ModuX TeX proponuje tylko jednX funkcje polecen~ i jednX funkcje Xrodowiska: generic_command i generic_environment.

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

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

Obie funkcje tylko przetXumaczX parametry, ktore byXy okreXlone jako moXliwe do tXumaczenie (z ""). generic_environment doda nazwe Xrodowiska do stosu Xrodowiska, a generic_command doda nazwe polecenia, po ktorej nastXpi identyfikator parametru (jak {#7} lub [#2]).

STATUS MODUXU
ModuX powinien byae bardziej przetestowany.

ByXo testowany na ksiXXce z dokumentacjX Pythona.

LISTA RZECZY DO ZROBIENIA

inne kategorie
    DosXowna (verbatim) kategoria moXe byae potrzebna, aby po4a nie probowaX zawijaae linii oraz do okreXlenia, Xe znaki procenta nie zaczynajX komentarza, a nawiasy mogX nie byae zamykane.

Automatyczne wykrywanie nowych polecen~
    ModuX TeX mogXby sparsowaae argumenty nowego polecenia i sprobowaae odgadnXae liczbe i typy argumentow oraz czy powinny byae tXumaczone, czy teX nie.

TXumaczenie separatora Xrodowiska
    Kiedy jako separatora Xrodowiska uXyje sie \item, to jego argument jest doXXczany do nastepujXcego Xan~cucha znakow.

Inne
    RoXne inne punkty sX oznaczone w XrodXach jako "TODO", czyli do zrobienia.

ZNANE BXEDY
RoXne punkty sX oznaczone w XrodXach jako "FIXME", czyli do poprawienia.

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

AUTORZY
 Nicolas Francois <nicolas.francois@centraliens.net>

TXUMACZENIE
 Robert Luberda <robert@debian.org>

PRAWA AUTORSKIE I LICENCJA
Copyright 2004, 2005 by Nicolas FRANCOIS <nicolas.francois@centraliens.net>.

Program jest wolnym oprogramowaniem; moXna go redystrybuowaae i/lub modyfikowaae zgodnie z warunkami licencji GPL (patrz plik COPYING).