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 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 przecinkami lista Xrodowisk, ktore nie powinny byae powtornie zawijane.

Prosze zauwaXyae, Xe Xrodowiska verbatim i no_wrap sie 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 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.

verbatim

Rozdzielona przecinkami lista Xrodowisk, ktore powinny byae 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 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}.

% 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:

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

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.

Niektore polecenia powinny byae dodane do stosu Xrodowiska.

Te polecenia powinny byae podawane w parach. UmoXliwiXoby podawanie polecen~ zaczynajXcych lub kon~czXcych dosXowne Xrodowisko.

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