NAZWA¶

Locale::Po4a::TeX - konwersja dokumentów TeX z/do plików PO

OPIS¶

Celem projektu po4a ("PO for anything") jest ułatwienie tłumaczeń (oraz, co ciekawsze, zarządzania tłumaczeniami) przy użyciu narzędzi gettext w tych obszarach, gdzie nie były używane, jak na przykład w obszarze dokumentacji. Locale::Po4a::TeX jest modułem ułatwiającym tłumaczenie dokumentacji w formacie TeX do innych języków [używanych przez ludzi]. Użytkownicy najprawdopodobniej powinni używać modułu LaTeX, który dziedziczy z modułu TeX i zawiera definicję częstych poleceń LaTeX.

TŁUMACZENIE Z POMOCĄ PO4A::TEX¶

Tego modułu można bezpośrednio użyć do obsługi ogólnych dokumentów w formacie TeX. Podzieli on dokument na mniejsze bloki (akapity, bloki dosłowych tekstów, a nawet jeszcze mniejsze jak tytuły czy indeksy). Istnieje kilka opcji (opisanych w następnej sekcji), które mogą dostosować zachowanie do Twoich wymagań. Jeśli nie pasuje ono do formatu Twojego dokumentu, zachęcamy do napisania własnego modułu dziedziczącego z tego, opisującego szczegóły formatu. Szczegóły można znaleźć w sekcji PRACA ZMODUŁAMI POCHODNYMI poniżej. Zachowanie modułu może być także zmieniane w pliku TeX za pomocą linii zaczynających się od "% po4a:". Takie zmiany są opisane w sekcji DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM.

OPCJE AKCEPTOWANE PRZEZ MODUŁ¶

Opcje tego modułu:

debug

Uaktywnia debugowanie kilku wewnętrznych mechanizmów modułu. Informacje o tym, które części mogą być debugowane, można znaleźć w źródłach.

no_wrap

Rozdzielona przecinkami lista środowisk, które nie powinny być powtórnie zawijane.

 

Proszę zauważyć, że środowiska verbatim i no_wrap się różnią. W blokach verbatim nie są analizowane polecenia ani komentarze.

 

Jeżeli środowisko nie było wcześniej zarejestrowane, to po4a założy, że to środowisko nie potrzebuje żadnych parametrów.

exclude_include

Rozdzielona dwukropkami lista plików, które nie powinny być włączane przez \input i \include.

definitions

Nazwa pliku zawierającego definicje dla po4a, jak to zdefiniowano w sekcji DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM. Można użyć tej opcji, jeśli nie jest możliwe umieszczenie definicja w tłumaczonym dokumencie.

verbatim

Rozdzielona przecinkami lista środowisk, które powinny być przetwarzane tak, jak zostały podane.

 

Jeżeli środowisko nie było wcześniej zarejestrowane, to po4a założy, że to środowisko nie potrzebuje żadnych parametrów.

Użycie tych opcji pozwala zmienić zachowanie poleceń zdefiniowanych w domyślnych listach.

DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM¶

Działanie modułu TeX może być zmieniane za pomocą linii zaczynających się od % po4a:, które są interpretowane jako polecenia parsera. Rozpoznawane są następujące polecenia:

% po4a: command polecenie1 alias polecenie2

Mówi, że argumenty polecenia polecenie1 powinny być traktowane jako argumenty polecenia polecenie2.

% po4a: polecenie polecenie1 parametry

Pozwala szczegółowo opisać parametry polecenia polecenie1. Ta informacja zostanie użyta do sprawdzenia liczby i typów parametrów.

 

Polecenie polecenie1 może być poprzedzone przez następujące znaki:

% po4a: environment środowisko parametery

Pozwala to zdefiniować parametry akceptowane przez środowisko środowisko. Ta informacja później zostanie użyta do sprawdzenia liczby parametrów polecenia \begin oraz pozwala określić, które z nich mają być przetłumaczone. Składnia argumentu parametry jest taka sama, jak dla poleceń. Pierwszy parametr polecenia \begin jest nazwą środowiska. Lista parametrów nie może go zawierać. Kilka przykładów:
% po4a: environment multicols {}
% po4a: environment equation

 

Tak jak dla poleceń środowisko może być poprzedzone plusem (+), aby wskazać, że polecenie \begin musi być przetłumaczone wraz ze wszystkimi jego argumentami.

% po4a: separator środowisko " wyrażenie_regularne"

Wskazuje, że środowisko powinno być podzielone zgodnie z podanym wyrażeniem regularnym.

 

Wyrażenie regularne jest ograniczone cudzysłowami. Nie powinno tworzyć żadnej wstecznych referencji. Jeśli potrzeba pogrupować, to należy użyć (?:). Może także wymagać kilku znaków cytowania.

 

Na przykład moduł LaTeX używa wyrażenia regularnego "(?:&|\\\\)" , aby osobno przetłumaczyć każdą komórkę tabeli (linie są rozdzielone przez '\\' a komórki przez '&').

 

Środowisko jest rozszerzane do typu wyświetlanego pliku PO. Można tego użyć, aby pierwszy wymagany argument polecenia title podzielić na "\\\\". W tym przypadku środowiskiem jest title{#1}.

% po4a: verbatim environment środowisko

Określa, że środowisko jest środowiskiem dosłownym,tj. takim, w którym wszelkie komentarze i polecenia są ignorowane.

 

Jeżeli środowisko nie było wcześniej zarejestrowane, to po4a założy, że to środowisko nie potrzebuje żadnych parametrów.

PRACA Z MODUŁAMI POCHODNYMI¶

pre_trans

post_trans

translate

Funkcje opakowujące translate TransTractora filtrami uruchamianymi przed przetwarzaniem i po nim.

 

Komentarze akapitu są wstawiane jako komentarz PO dla pierwszego tłumaczonego komunikatu dla tego akapitu.

get_leading_command($buffer)

Funkcja zwraca:

get_trailing_command($buffer)

To samo co, get_leading_command, ale dla poleceń z końca bufora.

translate_buffer

Rekurencyjnie tłumaczy bufor, wydzielając z niego początkowe i końcowe polecenia (które powinny być tłumaczone oddzielnie).

 

Jeżeli w bieżącym środowisku zmienna %translate_buffer_env zawiera definicję funkcji, to ta funkcja zostanie użyta zamiast translate_buffer() do przetłumaczenia zawartości bufora.

read

Przeładowanie funkcji read TransTractora

read_file

Rekurencyjnie czyta plik, dodając te pliki włączane, które nie są wymienione w tablicy @exclude_include. Plik włączane są wyszukiwane poleceniem kpsewhich z biblioteki Kpathsea.

 

Poza częścią włączania plików, jest to przekopiowane z funkcji read TransTractora.

parse_definition_file

Procedura parsowania pliku zawierającego dyrektywę po4a (definicje nowych poleceń).

parse_definition_line

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

 

Dalsze informacje można znaleźć w sekcji DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM.

is_closed

docheader

FUNKCJE WEWNĘTRZNE, używane do pisania parserów¶

Funkcje poleceń i środowiska pobierają następujące argumenty (oraz dodatkowo obiekt $self):

Nazwę polecenia

Wariant

Tablica krotek (typ, argument)

Bieżące środowisko

Pierwsze 3 argumenty są wyodrębniane przez get_leading_command lub get_trailing_command. Funkcje poleceń i środowiska zwracają tłumaczenia poleceń z jego argumentami i nowe środowisko. Funkcje środowiska są wywoływane, jeśli znaleziono polecenie \begin. Są one wywoływane z poleceniem \begin i jego argumentami. Moduł TeX proponuje tylko jedną funkcję poleceń i jedną funkcję środowiska: generic_command i generic_environment. generic_command używa informacji podanych przez register_generic_command albo przez dodanie definicji w pliku TeX:
% po4a: command polecenie1 parametry generic_environment używa informacji podanych przez register_generic_environment albo przez dodanie definicji w pliku TeX:
% po4a: environment środowisko parametery Obie funkcje tylko przetłumaczą parametry, które były określone jako możliwe do tłumaczenie (z ""). generic_environment doda nazwę środowiska do stosu środowiska, a generic_command doda nazwę polecenia, po której nastąpi identyfikator parametru (jak {#7} lub [#2]).

STATUS MODUŁU¶

Moduł powinien być bardziej przetestowany. Było testowany na książce z dokumentacją Pythona.

LISTA RZECZY DO ZROBIENIA¶

Automatyczne wykrywanie nowych poleceń

Moduł TeX mógłby sparsować argumenty nowego polecenia i spróbować odgadnąć liczbę i typy argumentów oraz czy powinny być tłumaczone, czy też nie.

Tłumaczenie separatora środowiska

Kiedy jako separatora środowiska użyje się \item, to jego argument jest dołączany do następującego łańcucha znaków.

Niektóre polecenia powinny być dodane do stosu środowiska.

Te polecenia powinny być podawane w parach. Umożliwiłoby podawanie poleceń zaczynających lub kończących dosłowne środowisko.

Inne

Różne inne punkty są oznaczone w źródłach jako "TODO", czyli do zrobienia.

ZNANE BŁĘDY¶

Różne punkty są oznaczone w źródłach jako "FIXME", czyli do poprawienia.

ZOBACZ TAKŻE¶

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

AUTORZY¶

 Nicolas François <nicolas.francois@centraliens.net>

PRAWA AUTORSKIE I LICENCJA¶

Copyright 2004, 2005 by Nicolas FRANÇOIS <nicolas.francois@centraliens.net>. Program jest wolnym oprogramowaniem; można go redystrybuować i/lub modyfikować zgodnie z warunkami licencji GPL (patrz plik COPYING).