Ubuntu Manpage: Locale::Po4a::TeX - convert TeX documents and derivatives from/to PO files

NAZWA

       Locale::Po4a::TeX - convert TeX documents and derivatives from/to PO files

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

       There are some options (described in the next section) that can customize this behavior.  If this doesn't
       fit to your document format you're encouraged to write your own derivative module from this, to describe
       your format's details.  See the section WRITING DERIVATIVE MODULES below, for the process description.

       This module can also be customized by lines starting with "% po4a:" in the TeX file. This process is
       described in the INLINE CUSTOMIZATION section.

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:

gwiazdka (*)
po4a wyciągnie to polecenie z akapitów (jeśli jest umieszczone na początku lub na końcu akapitu).
Tłumacze będą musieli wtedy przetłumaczyć te parametry, które są oznaczone jako odpowiednie do
tłumaczenia.

plus (+)
Tak jak w przypadku gwiazdki, to polecenie będzie wyodrębnione, jeżeli pojawi się na końcu bloku,
ale jego parametry nie zostaną oddzielnie przetłumaczone. Tłumacz będzie musiał przetłumaczyć
polecenie połączone ze wszystkimi jego parametrami. Pozwala to zachować więcej kontekstu i jest
użyteczne dla wszystkich poleceń, przyjmujących jako parametr krótkie słowo, które może mieć
wiele znaczeń (i tłumaczeń).

Uwaga: w tym przypadku nie trzeba określać, które parametry należy tłumaczyć, ale po4a musi znać
typ i liczbę parametrów.

minus (-)
W takim wypadku, polecenie nie zostanie wydobyte z żadnego bloku. Ale jeżeli pojawi się
samodzielnie w bloku, to tłumaczowi zostaną pokazane tylko te parametry, które zostały zaznaczone
jako możliwe do przetłumaczenia. Polecenia te zazwyczaj nie powinny być wydzielane z ich akapitów
(aby zachować kontekst), ale nie ma żadnego powodu, żeby męczyć tłumacza nimi, jeśli cały
komunikat jest zawarty w takim poleceniu.

Argument parameters jest zbiorem nawiasów [] (określających argumenty opcjonalne) lub {}
(określających argumenty wymagane). Aby wskazać, że parametr ma zostać przetłumaczony, można
pomiędzy tymi nawiasami umieścić znak podkreślenia (_). Na przykład:
% po4a: command *chapter [_]{_}

To wskazuje, że polecenie chapter ma dwa parametry: opcjonalny (krótki tytuł) i obowiązkowy, oba
muszą być przetłumaczone. Aby określić, że polecenie href ma dwa wymagane parametry, oraz że
pierwszy z nich (URL) ma nie być przetłumaczony, oraz że polecenie to ma nie być oddzielone od
otaczającego go akapitu (co pozwala tłumaczowi zmienić pozycję linku w zdaniu), można użyć:
% po4a: command -href {}{_}

W tym wypadku informacja wskazująca, które argumenty muszą być przetłumaczone jest używana tylko
wtedy, gdy akapit jest utworzony tylko z tej komendy href.

% po4a: environment środowisko parametery
This permits to define the parameters accepted by the env environment. This information is later
used to check the number of arguments of the \begin command, and permit to specify which one must be
translated. The syntax of the parameters argument is the same as described for the others commands.
The first parameter of the \begin command is the name of the environment. This parameter must not be
specified in the list of parameters. Here are some examples:
% 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 '&').

The notion of environment is expanded to the type displayed in the PO file. This can be used to split
on "\\\\" in the first mandatory argument of the title command. In this case, the environment is
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
add_comment
Add a string as a comment to be added around the next translated element. This is mostly useful to
the texinfo module, as comments are automatically handled in TeX.

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:

Nazwę polecenia
Jeżeli na początku podanego bufora nie znaleziono żadnego polecenia, tekst będzie pusty. Są brane
pod uwagę tylko te polecenia, które można rozdzielić. Hash %separated_command zawiera ich listę.

Wariant
Określa użyty wariant. Na przykład gwiazdka (*) może być dodana na końcu sekcji poleceń, aby
określić że nie powinny być numerowane. W tym przypadku pole to będzie zawierać "*". Jeśli
wariant nie istnieje, pole będzie pustym łańcuchem znaków.

Tablicę par (typ argumentu, argument)
Typem argumentu może być albo "{" (dla argumentów wymaganych), albo "[" (dla argumentów
opcjonalnych).

Pozostały bufor
Reszta bufora po usunięciu początkowego polecenia i jego argumentów. Jeśli 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 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
parse
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>

TŁUMACZENIE

        Robert Luberda <robert@debian.org>

PRAWA AUTORSKIE I LICENCJA

       Copyright © 2004, 2005 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).

Narzędzia po4a                                     2022-01-02                             Locale::Po4a::TeX(3pm)