Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::TeX.3pm

NAZWA

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

OPIS

Celem projektu po4a (``po for anything'') jest uXatwienie tXumaczeX (oraz, co ciekawsze, zarzXdzania tXumaczeniami) przy uXyciu narzXdzi 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 jXzykow [uXywanych przez ludzi].

UXytkownicy najprawdopodobniej powinni uXywaX moduXu LaTeX, ktory dziedziczy z moduXu TeX i zawiera definicjX czXstych poleceX LaTeX.

TXUMACZENIE Z POMOCX PO4A::TEX

Tego moduXu moXna bezpoXrednio uXyX 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 nastXpnej sekcji), ktore mogX dostosowaX zachowanie do Twoich wymagaX. JeXli nie pasuje ono do formatu Twojego dokumentu, zachXcamy do napisania wXasnego moduXu dziedziczXcego z tego, opisujXcego szczegoXy formatu. SzczegoXy moXna znaleXX w sekcji ``Pisanie moduXow pochodnych'' poniXej.

Zachowanie moduXu moXe byX takXe zmieniane w pliku TeX za pomocX linii zaczynajXcych siX 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 wewnXtrznych mechanizmow moduXu. Informacje o tym, ktore czXXci mogX byX debugowane, moXna znaleXX w XrodXach.

no_wrap

Rozdzielona przecinkami lista Xrodowisk, ktore nie powinny byX powtornie zawijane.

ProszX zauwaXyX, Xe Xrodowiska verbatim i no_wrap siX roXniX. W blokach verbatim nie sX analizowane polecenia ani komentarze.

JeXeli Xrodowisko nie byXo wczeXniej zarejestrowane, to po4a zaXoXy, Xe to Xrodowisko nie potrzebuje Xadnych parametrow.

exclude_include

Rozdzielona dwukropkami lista plikow, ktore nie powinny byX 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 uXyX tej opcji, jeXli nie jest moXliwe umieszczenie definicja w tXumaczonym dokumencie.

verbatim

Rozdzielona przecinkami lista Xrodowisk, ktore powinny byX przetwarzane tak, jak zostaXy podane.

JeXeli Xrodowisko nie byXo wczeXniej zarejestrowane, to po4a zaXoXy, Xe to Xrodowisko nie potrzebuje Xadnych parametrow.

UXycie tych opcji pozwala zmieniX zachowanie poleceX zdefiniowanych w domyXlnych listach.

DOSTOSOWYWANIE ZA POMOCX OPCJI W PLIKU XRODXOWYM

DziaXanie moduXu TeX moXe byX zmieniane za pomocX linii zaczynajXcych siX od ``% po4a:'', ktore sX interpretowane jako polecenia parsera. Rozpoznawane sX nastXpujXce polecenia:

% po4a: command polecenie1 alias polecenie2

Mowi, Xe argumenty polecenia polecenie1 powinny byX traktowane jako argumenty polecenia polecenie2.

% po4a: polecenie polecenie1 parametry

Pozwala szczegoXowo opisaX parametry polecenia polecenie1. Ta informacja zostanie uXyta do sprawdzenia liczby i typow parametrow.

Polecenie polecenie1 moXe byX poprzedzone przez nastXpujXce znaki:

gwiazdka (*)

po4a wyciXgnie to polecenie z akapitow (jeXli jest umieszczone na poczXtku lub na koXcu akapitu). TXumacze bXdX musieli wtedy przetXumaczyX te parametry, ktore sX oznaczone jako odpowiednie do tXumaczenia.

plus (+)

Tak jak w przypadku gwiazdki, to polecenie bXdzie wyodrXbnione, jeXeli pojawi siX na koXcu bloku, ale jego parametry nie zostanX oddzielnie przetXumaczone. TXumacz bXdzie musiaX przetXumaczyX polecenie poXXczone ze wszystkimi jego parametrami. Pozwala to zachowaX wiXcej kontekstu i jest uXyteczne dla wszystkich poleceX, przyjmujXcych jako parametr krotkie sXowo, ktore moXe mieX wiele znaczeX (i tXumaczeX).

Uwaga: w tym przypadku nie trzeba okreXlaX, ktore parametry naleXy tXumaczyX, ale po4a musi znaX typ i liczbX parametrow.

minus (-)

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

Argument parameters jest zbiorem nawiasow [] (okreXlajXcych argumenty opcjonalne) lub {} (okreXlajXcych argumenty wymagane). Aby wskazaX, Xe parametr ma zostaX przetXumaczony, moXna pomiXdzy tymi nawiasami umieXciX znak podkreXlenia (_). Na przykXad:
 % po4a: command *chapter [_]{_}
To wskazuje, Xe polecenie chapter ma dwa parametry: opcjonalny (krotki tytuX) i obowiXzkowy, oba muszX byX przetXumaczone. Aby okreXliX, Xe polecenie href ma dwa wymagane parametry, oraz Xe pierwszy z nich (URL) ma nie byX przetXumaczony, oraz Xe polecenie to ma nie byX oddzielone od otaczajXcego go akapitu (co pozwala tXumaczowi zmieniX pozycjX linku w zdaniu), moXna uXyX:
 % po4a: command -href {}{_}
W tym wypadku informacja wskazujXca, ktore argumenty muszX byX przetXumaczone jest uXywana tylko wtedy, gdy akapit jest utworzony tylko z tej komendy href.

% po4a: environment Xrodowisko parametery

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

Tak jak dla poleceX Xrodowisko moXe byX poprzedzone plusem (+), aby wskazaX, Xe polecenie \begin musi byX przetXumaczone wraz ze wszystkimi jego argumentami.

% po4a: separator Xrodowisko "wyraXenie_regularne"

Wskazuje, Xe Xrodowisko powinno byX podzielone zgodnie z podanym wyraXeniem regularnym.

WyraXenie regularne jest ograniczone cudzysXowami. Nie powinno tworzyX Xadnej wstecznych referencji. JeXli potrzeba pogrupowaX, to naleXy uXyX (?:). MoXe takXe wymagaX kilku znakow cytowania.

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

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

% po4a: verbatim environment Xrodowisko

OkreXla, Xe Xrodowisko jest Xrodowiskiem dosXownym,tj. takim, w ktorym wszelkie komentarze i polecenia sX ignorowane.

JeXeli Xrodowisko nie byXo wczeXniej zarejestrowane, to po4a zaXoXy, Xe to Xrodowisko nie potrzebuje Xadnych parametrow.

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:

NazwX polecenia

JeXeli na poczXtku podanego bufora nie znaleziono Xadnego polecenia, tekst bXdzie pusty. SX brane pod uwagX tylko te polecenia, ktore moXna rozdzieliX. Hash %separated_command zawiera ich listX.

Wariant

OkreXla uXyty wariant. Na przykXad gwiazdka (*) moXe byX dodana na koXcu sekcji poleceX, aby okreXliX Xe nie powinny byX numerowane. W tym przypadku pole to bXdzie zawieraX ``*''. JeXli wariant nie istnieje, pole bXdzie pustym XaXcuchem znakow.

TablicX par (typ argumentu, argument)

Typem argumentu moXe byX albo ``{'' (dla argumentow wymaganych), albo ``['' (dla argumentow opcjonalnych).

PozostaXy bufor

Reszta bufora po usuniXciu 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 poleceX z koXca bufora.

translate_buffer

Rekurencyjnie tXumaczy bufor, wydzielajXc z niego poczXtkowe i koXcowe polecenia (ktore powinny byX tXumaczone oddzielnie).

JeXeli w bieXXcym Xrodowisku zmienna %translate_buffer_env zawiera definicjX funkcji, to ta funkcja zostanie uXyta zamiast translate_buffer() do przetXumaczenia zawartoXci bufora.

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 czXXciX wXXczania plikow, jest to przekopiowane z funkcji read TransTractora.

parse_definition_file

Procedura parsowania pliku zawierajXcego dyrektywX po4a (definicje nowych poleceX).

parse_definition_line

Przetwarza liniX definicji w formacie ``% po4a: ''.

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

is_closed

docheader

FUNKCJE WEWNXTRZNE, uXywane do pisania parserow

Funkcje poleceX i Xrodowiska pobierajX nastXpujXce argumenty (oraz dodatkowo obiekt $self):

NazwX polecenia

Wariant

Tablica krotek (typ, argument)

BieXXce Xrodowisko

Pierwsze 3 argumenty sX wyodrXbniane przez get_leading_command lub get_trailing_command.

Funkcje poleceX i Xrodowiska zwracajX tXumaczenia poleceX 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 funkcjX poleceX i jednX funkcjX 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 nazwX Xrodowiska do stosu Xrodowiska, a generic_command doda nazwX polecenia, po ktorej nastXpi identyfikator parametru (jak {#7} lub [#2]).

STATUS MODUXU

ModuX powinien byX bardziej przetestowany.

ByXo testowany na ksiXXce z dokumentacjX Pythona.

LISTA RZECZY DO ZROBIENIA

Automatyczne wykrywanie nowych poleceX

ModuX TeX mogXby sparsowaX argumenty nowego polecenia i sprobowaX odgadnXX liczbX i typy argumentow oraz czy powinny byX tXumaczone, czy teX nie.

TXumaczenie separatora Xrodowiska

Kiedy jako separatora Xrodowiska uXyje siX \item, to jego argument jest doXXczany do nastXpujXcego XaXcucha znakow.

Niektore polecenia powinny byX dodane do stosu Xrodowiska.

Te polecenia powinny byX podawane w parach. UmoXliwiXoby podawanie poleceX zaczynajXcych lub koXczXcych dosXowne Xrodowisko.

Inne

RoXne inne punkty sX oznaczone w XrodXach jako ``TODO'', czyli do zrobienia.

ZNANE BXXDY

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 redystrybuowaX i/lub modyfikowaX zgodnie z warunkami licencji GPL (patrz plik COPYING).