LOCALE::PO4A::TEX.3PM(1) User Contributed Perl Documentation NAZWA Locale::Po4a::TeX - convert TeX documents and derivatives from/to PO files OPIS Celem projektu po4a ("PO for anything") jest ulatwienie tlumaczen (oraz, co ciekawsze, zarzadzania tlumaczeniami) przy uzyciu narzedzi gettext w tych obszarach, gdzie nie byly uzywane, jak na przyklad w obszarze dokumentacji. Locale::Po4a::TeX jest modulem ulatwiajacym tlumaczenie dokumentacji w formacie TeX do innych jezykow [uzywanych przez ludzi]. Uzytkownicy najprawdopodobniej powinni uzywac modulu LaTeX, ktory dziedziczy z modulu TeX i zawiera definicje czestych polecen LaTeX. TLUMACZENIE Z POMOCA PO4A::TEX Tego modulu mozna bezposrednio uzyc 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). 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 MODUL Opcje tego modulu: debug Uaktywnia debugowanie kilku wewnetrznych mechanizmow modulu. Informacje o tym, ktore czesci moga byc debugowane, mozna znalezc w zrodlach. no_wrap Rozdzielona przecinkami lista srodowisk, ktore nie powinny byc powtornie zawijane. Prosze zauwazyc, ze srodowiska verbatim i no_wrap sie roznia. W blokach verbatim nie sa analizowane polecenia ani komentarze. Jezeli srodowisko nie bylo wczesniej zarejestrowane, to po4a zalozy, ze to srodowisko nie potrzebuje zadnych parametrow. exclude_include Rozdzielona dwukropkami lista plikow, ktore nie powinny byc wlaczane przez \input i \include. definitions Nazwa pliku zawierajacego definicje dla po4a, jak to zdefiniowano w sekcji DOSTOSOWYWANIE ZA POMOCA OPCJI W PLIKU ZRODLOWYM. Mozna uzyc tej opcji, jesli nie jest mozliwe umieszczenie definicja w tlumaczonym dokumencie. verbatim Rozdzielona przecinkami lista srodowisk, ktore powinny byc przetwarzane tak, jak zostaly podane. Jezeli srodowisko nie bylo wczesniej zarejestrowane, to po4a zalozy, ze to srodowisko nie potrzebuje zadnych parametrow. Use these options to override the default behavior of the defined commands. DOSTOSOWYWANIE ZA POMOCA OPCJI W PLIKU ZRODLOWYM Dzialanie modulu TeX moze byc zmieniane za pomoca linii zaczynajacych sie od % po4a:, ktore sa interpretowane jako polecenia parsera. Rozpoznawane sa nastepujace polecenia: % po4a: command polecenie1 alias polecenie2 Mowi, ze argumenty polecenia polecenie1 powinny byc traktowane jako argumenty polecenia polecenie2. % po4a: polecenie polecenie1 parametry This describes in detail the parameters of the command1 command. This information will be used to check the number of arguments and their types. Polecenie polecenie1 moze byc poprzedzone przez nastepujace znaki: gwiazdka (*) po4a wyciagnie to polecenie z akapitow (jesli jest umieszczone na poczatku lub na koncu akapitu). Tlumacze beda musieli wtedy przetlumaczyc te parametry, ktore sa oznaczone jako odpowiednie do tlumaczenia. plus (+) As for an asterisk, the command will be extracted if it appear at an extremity of a block, but the parameters won't be translated separately. The translator will have to translate the command concatenated to all its parameters. This keeps more context, and is useful for commands with small words in parameter, which can have multiple meanings (and translations). Uwaga: w tym przypadku nie trzeba okreslac, ktore parametry nalezy tlumaczyc, ale po4a musi znac typ i liczbe parametrow. minus (-) W takim wypadku, polecenie nie zostanie wydobyte z zadnego bloku. Ale jezeli pojawi sie samodzielnie w bloku, to tlumaczowi zostana pokazane tylko te parametry, ktore zostaly zaznaczone jako mozliwe do przetlumaczenia. Polecenia te zazwyczaj nie powinny byc wydzielane z ich akapitow (aby zachowac kontekst), ale nie ma zadnego powodu, zeby meczyc tlumacza nimi, jesli caly komunikat jest zawarty w takim poleceniu. Argument parameters jest zbiorem nawiasow [] (okreslajacych argumenty opcjonalne) lub {} (okreslajacych argumenty wymagane). Aby wskazac, ze parametr ma zostac przetlumaczony, mozna pomiedzy tymi nawiasami umiescic znak podkreslenia (_). Na przyklad: % po4a: command *chapter [_]{_} To wskazuje, ze polecenie chapter ma dwa parametry: opcjonalny (krotki tytul) i obowiazkowy, oba musza byc przetlumaczone. Aby okreslic, ze polecenie href ma dwa wymagane parametry, oraz ze pierwszy z nich (URL) ma nie byc przetlumaczony, oraz ze polecenie to ma nie byc oddzielone od otaczajacego go akapitu (co pozwala tlumaczowi zmienic pozycje linku w zdaniu), mozna uzyc: % po4a: command -href {}{_} W tym wypadku informacja wskazujaca, ktore argumenty musza byc przetlumaczone jest uzywana tylko wtedy, gdy akapit jest utworzony tylko z tej komendy href. % po4a: environment srodowisko parametery This defines the parameters accepted by the env environment and specifies the ones to be translated. This information is later used to check the number of arguments of the \begin command. 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 polecen srodowisko moze byc poprzedzone plusem (+), aby wskazac, ze polecenie \begin musi byc przetlumaczone wraz ze wszystkimi jego argumentami. % po4a: separator srodowisko "wyrazenie_regularne" Wskazuje, ze srodowisko powinno byc podzielone zgodnie z podanym wyrazeniem regularnym. The regular expression is delimited by quotes. It should not create any back-reference. You should use (?:) if you need a group. It may also need some escapes. Na przyklad modul LaTeX uzywa wyrazenia regularnego "(?:&|\\\\)" , aby osobno przetlumaczyc kazda komorke tabeli (linie sa rozdzielone przez '\\' a komorki 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 srodowisko Okresla, ze srodowisko jest srodowiskiem doslownym,tj. takim, w ktorym wszelkie komentarze i polecenia sa ignorowane. Jezeli srodowisko nie bylo wczesniej zarejestrowane, to po4a zalozy, ze to srodowisko nie potrzebuje zadnych parametrow. PRACA Z MODULAMI 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 opakowujace translate TransTractora filtrami uruchamianymi przed przetwarzaniem i po nim. Komentarze akapitu sa wstawiane jako komentarz PO dla pierwszego tlumaczonego komunikatu dla tego akapitu. get_leading_command($buffer) Funkcja zwraca: Nazwe polecenia Jezeli na poczatku podanego bufora nie znaleziono zadnego polecenia, tekst bedzie pusty. Sa brane pod uwage tylko te polecenia, ktore mozna rozdzielic. Hash %separated_command zawiera ich liste. Wariant Okresla uzyty wariant. Na przyklad gwiazdka (*) moze byc dodana na koncu sekcji polecen, aby okreslic ze nie powinny byc numerowane. W tym przypadku pole to bedzie zawierac "*". Jesli wariant nie istnieje, pole bedzie pustym lancuchem znakow. Tablice par (typ argumentu, argument) Typem argumentu moze byc albo "{" (dla argumentow wymaganych), albo "[" (dla argumentow opcjonalnych). Pozostaly bufor Reszta bufora po usunieciu poczatkowego polecenia i jego argumentow. Jesli 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 konca bufora. translate_buffer Rekurencyjnie tlumaczy bufor, wydzielajac z niego poczatkowe i koncowe polecenia (ktore powinny byc tlumaczone oddzielnie). Jezeli w biezacym srodowisku zmienna %translate_buffer_env zawiera definicje funkcji, to ta funkcja zostanie uzyta zamiast translate_buffer() do przetlumaczenia zawartosci bufora. read Przeladowanie funkcji read() TransTractora. read_file Rekurencyjnie czyta plik, dodajac te pliki wlaczane, ktore nie sa wymienione w tablicy @exclude_include. Plik wlaczane sa wyszukiwane poleceniem kpsewhich z biblioteki Kpathsea. Poza czescia wlaczania plikow, jest to przekopiowane z funkcji read TransTractora. parse_definition_file Procedura parsowania pliku zawierajacego dyrektywe po4a (definicje nowych polecen). parse_definition_line Przetwarza linie definicji w formacie "% po4a: ". Dalsze informacje mozna znalezc w sekcji DOSTOSOWYWANIE ZA POMOCA OPCJI W PLIKU ZRODLOWYM. is_closed parse docheader FUNKCJE WEWNETRZNE, uzywane do pisania parserow Funkcje polecen i srodowiska pobieraja nastepujace argumenty (oraz dodatkowo obiekt $self): Nazwe polecenia Wariant Tablica krotek (typ, argument) Biezace srodowisko Pierwsze 3 argumenty sa wyodrebniane przez get_leading_command lub get_trailing_command. Funkcje polecen i srodowiska zwracaja tlumaczenia polecen z jego argumentami i nowe srodowisko. Funkcje srodowiska sa wywolywane, jesli znaleziono polecenie \begin. Sa one wywolywane z poleceniem \begin i jego argumentami. Modul TeX proponuje tylko jedna funkcje polecen i jedna funkcje srodowiska: generic_command i generic_environment. generic_command uzywa informacji podanych przez register_generic_command albo przez dodanie definicji w pliku TeX: % po4a: command polecenie1 parametry generic_environment uzywa informacji podanych przez register_generic_environment albo przez dodanie definicji w pliku TeX: % po4a: environment srodowisko parametery Obie funkcje tylko przetlumacza parametry, ktore byly okreslone jako mozliwe do tlumaczenie (z ""). generic_environment doda nazwe srodowiska do stosu srodowiska, a generic_command doda nazwe polecenia, po ktorej nastapi identyfikator parametru (jak {#7} lub [#2]). STATUS MODULU Modul powinien byc bardziej przetestowany. Bylo testowany na ksiazce z dokumentacja Pythona. LISTA RZECZY DO ZROBIENIA Automatyczne wykrywanie nowych polecen Modul TeX moglby sparsowac argumenty nowego polecenia i sprobowac odgadnac liczbe i typy argumentow oraz czy powinny byc tlumaczone, czy tez nie. Tlumaczenie separatora srodowiska Kiedy jako separatora srodowiska uzyje sie \item, to jego argument jest dolaczany do nastepujacego lancucha znakow. Niektore polecenia powinny byc dodane do stosu srodowiska. These commands should be specified by couples. This can be used to specify commands beginning or ending a verbatim environment. Inne Rozne inne punkty sa oznaczone w zrodlach jako "TODO", czyli do zrobienia. ZNANE BLEDY Rozne punkty sa oznaczone w zrodlach jako "FIXME", czyli do poprawienia. ZOBACZ TAKZE Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7) AUTORZY Nicolas Francois TLUMACZENIE Robert Luberda PRAWA AUTORSKIE I LICENCJA Copyright (C) 2004, 2005 Nicolas FRANCOIS . This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file). perl v5.38.2 2024-06-26 LOCALE::PO4A::TEX.3PM(1)