Provided by:
po4a_0.41-1_all 
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).