Provided by: po4a_0.41-1_all bug

NAZWA

       Locale::Po4a::Xml - konwersja dokumentow XML i pochodnych 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::XML jest modulem ulatwiajcym tlumaczenie dokumentow XML
       do innych jzykow [uywanych przez ludzi].

T/LUMACZENIE Z POMOC PO4A::XML

       Tego modulu mona uy bezporednio do obslugi ogolnych dokumentow w
       formacie XML. Wycignie on zawarto wszystkich elementow, bez adnych
       atrybutow, poniewa to wlanie w elementach jest zapisywany tekst w
       wikszoci dokumentow opartych na XML-u.

       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.

OPCJE AKCEPTOWANE PRZEZ MODU/L

       Globalna opcja debug powoduje, e ten modul pokae wylczone komunikaty,
       aby moc sprawdzi, czy przypadkiem nie pomija czego istotnego.

       Opcje tego modulu:

       nostrip
           Uniemoliwia usuwanie spacji otaczajcych wyodrbnione komunikaty.

       wrap
           Kanonizuje komunikaty do przetlumaczenia, przyjmujc, e spacje nie s
           wanie i tylko slu do zawijania przetlumaczonego dokumentu. T opcj
           mona nadpisa opcjami dotyczcymi wlasnych elementow. Patrz opis
           opcji "tags" poniej.

       caseinsensitive
           Powoduje, e elementy i atrybuty s wyszukiwane z pominiciem
           rozpoznawania wielkoci liter. Jeli jest to zdefiniowane, to
           <BooK>laNG i <BOOK>Lang zostan potraktowane tak samo jak
           <book>lang.

       includeexternal
           Jeeli zdefiniowano, zewntrzne encje s dolczane do wygenerowanego
           (przetlumaczonego) dokumentu oraz do wyodrbnionych lacuchow znakow.
           Jeeli nie zdefiniowano, bdzie trzeba przetlumaczy zewntrzne encje
           jako niezalene dokumenty.

       ontagerror
           Ta opcja okrela zachowanie modulu, kiedy wykryje bld skladni XML
           (element zamykany, ktory nie odpowiada elementowi ostatnio
           otwieranemu lub brak jest wartoci atrybutu elementu). Moe przyjmowa
           nastpujce wartoci:

           fail
               Jest to domylna warto. Dzialanie modulu zakoczy si bldem.

           warn
               Modul wywietli ostrzeenie i bdzie kontynuowal dzialanie,

           silent
               Modul bdzie kontynuowal bez wypisywania adnych ostrzee.

           Prosz zachowa ostrono, uywajc tej opcji. Rekomendowanym zachowaniem
           jest poprawienie pliku wejciowego.

       tagsonly
           Wyodrbnia tylko elementy podane w opcji "tags". W przeciwnym
           wypadku wyodrbni wszystkie elementy poza podanymi w tej opcji.

           Uwaga: Opcja ta jest przestarzala.

       doctype
           Lacuch znakow, ktory bdziemy probowali dopasowa do pierwszej linii
           typu dokumentu (doctype; jeli zdefiniowany). Jeli nie pasuje, to
           zostanie wypisane ostrzeenie, e dokument moe mie niepoprawny typ.

       addlang
           Lacuch znakow oznaczajcy ciek (np. <bbb><aaa>)) znacznika, do
           ktorego powinien zosta dodany atrybut lang="..." . Jzyk jest
           zdefiniowany jako nazwa bazowa pliku PO z usunitym rozszerzeniem
           .po.

       tags
           Rozdzielona spacjami lista elementow, ktore maj by przetlumaczone
           lub opuszczone. Domylnie podane elementy bd opuszczone, ale uycie
           opcji "tagsonly" oznacza, e podane elementy bd jedynymi elementami
           wlczonymi. Elementy musz mie posta <aaa>, jednak mona polczy kilka
           z nich (<bbb><aaa>), aby okreli, e zawarto elementu <aaa> bdzie
           przetlumaczona tylko wtedy, gdy sam element jest zawarty w
           elemencie <bbb>.

           Mona poda take kilka opcji elementow dodajc pewne znaki na pocztku
           hierarchii elementow. Na przyklad mona doda "w" (zawijaj tekst) lub
           "W" (nie zawijaj), aby nadpisa domylne zachowanie okrelone przez
           globaln opcj "wrap".

           Przyklad: W<chapter><title>

           Uwaga: Opcja ta jest przestarzala. Prosimy zamiast niej uywa opcji
           translated i untranslated.

       attributes
           Rozdzielona spacjami lista atrybutow elementow, ktore naley
           tlumaczy. Mona poda atrybuty, uywajc ich nazwy (na przyklad
           "lang"), ale take mona poprzedzi je hierarchi elementow, aby
           powiedzie, e ten atrybut bdzie tlumaczony tylko wtedy. gdy jest
           zawarty w okrelonym elemencie. Na przyklad <bbb><aaa>lang mowi, e
           atrybut lang zostanie przetlumaczony, tylko jeeli jest zawarty w
           elemencie <aaa>, ktory jest w elemencie <bbb>.

       foldattributes
           Nie tlumaczy atrybutow elementow wlczanych. Zamiast tego zastpuje
           wszystkie atrybuty elementu przez po4a-id=<id>.

           Jest to uyteczne w przypadku atrybutow, ktore nie powinny by
           tlumaczone - upraszcza komunikaty do tlumaczenia i zapobiega
           pomylkom tlumaczy.

       customtag
           Rozdzielona spacjami lista elementow, ktore nie powinny by
           traktowane jako elementy.Tagi te s traktowane jako wlczane i nie
           musz by zamykane.

       break
           Rozdzielona spacjami lista elementow, ktore powinny przerwa
           sekwencj. Domylnie wszystkie elementy przerywaj sekwencj.

           Elementu musz by w postaci <aaa>, mona je jednak polczy
           (<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
           tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).

       inline
           Rozdzielona spacjami lista elementow, ktore powinny zosta
           potraktowane jako wlczane. Domylnie wszystkie elementy przerywaj
           sekwencj.

           Elementu musz by w postaci <aaa>, mona je jednak polczy
           (<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
           tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).

       placeholder
           Rozdzielona spacjami lista elementow, ktore powinny zosta
           potraktowane jako wypelniacze miejsca (placeholder). Wypelniacze
           miejsca nie przerywaj sekwencji, jednak ich zawarto jest tlumaczona
           osobno.

           Poloenie wypelniaczy miejsca w bloku bdzie oznaczone lacuchem
           znakow podobnym do:

             <placeholder type=\"footnote\" id=\"0\"/>

           Elementu musz by w postaci <aaa>, mona je jednak polczy
           (<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
           tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).

       nodefault
           Rozdzielona spacjami lista elementow, ktorych modul nie powinien
           probowa domylnie umieszcza jakiejkolwiek kategorii.

       cpp Wspiera dyrektywy preprocesora C. Jeli opcja zostanie wlczona, po4a
           bdzie przetwarzal dyrektywy preprocesora jako separatory akapitow.
           Jest to wane, jeli plik XML jest przetwarzany przez preprocesor,
           poniewa jeli nie uyje si tej opcji, a dyrektywy preprocesora trafi
           w rodek linii, to po4a przyjmie, a nale do biecego paragramu, co
           spowoduje, e preprocesor ich ju nie rozpozna. Uwaga: dyrektywy
           preprocesora musz by umieszczone midzy elementami (nie mog
           rozdziela elementu).

       translated
           Rozdzielona spacjami lista elementow do przetlumaczenia.

           Elementu musz by w postaci <aaa>, mona je jednak polczy
           (<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
           tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).

           Mona poda take kilka opcji elementow dodajc pewne znaki na pocztku
           hierarchii elementow. Na przyklad mona doda "w" (zawijaj tekst) lub
           "W" (nie zawijaj), aby nadpisa domylne zachowanie okrelone przez
           globaln opcj "wrap".

           Przyklad: W<chapter><title>

       untranslated
           Rozdzielona spacjami lista elementow, ktore nie maj by tlumaczone.

           Elementu musz by w postaci <aaa>, mona je jednak polczy
           (<bbb><aaa>), jeeli dany element (<aaa>) powinien by rozpatrywany
           tylko wtedy, gdy znajduje si w innym elemencie (<bbb>).

       defaulttranslateoption
           Domylne kategorie tych elementow ktore nie s tlumaczone
           (translated), nietlumaczone (untranslated), przerywaczami (break),
           wlczane (inline), ani wypelniaczami miejsca (placeholder).

           Jest to zbior liter:

           w   Elementy powinny by przetlumaczone i mona zmieni formatowanie
               zawartoci.

           W   Elementy powinny by tlumaczone, ale nie mona zmienia
               formatowania ich zawartoci.

           i   Elementy powinny tlumaczone jako wlczane.

           p   Elementy powinny by tlumaczone jako wypelniacze miejsca.

PRACA Z MODU/LAMI POCHODNYMI

   DEFINIOWANIE ELEMENT'OW I ATRYBUT'OW DO PRZET/LUMACZENIA
       Najprostsz zmian jest zdefiniowanie elementow i atrybutow, ktore parser
       ma przetlumaczy. Powinno by to zrobione w funkcji initialize. Najpierw
       trzeba wywola glown funkcj initialize, aby otrzyma opcje linii polece,
       a nastpnie doda wlasne definicje do hasha opcji. Aby obsluy nowe opcje
       w linii polece, trzeba je zdefiniowa przed wywolaniem glownej funkcji
       initialize:

         $self->{options}{'new_option'}='';
         $self->SUPER::initialize(%options);
         $self->{options}{'_default_translated'}.=' <p> <head><title>';
         $self->{options}{'attributes'}.=' <p>lang id';
         $self->{options}{'_default_inline'}.=' <br>';
         $self->treat_options;

       W modulach pochodnych naley uywa opcji _default_inline, _default_break,
       _default_placeholder, _default_translated, _default_untranslated oraz
       _default_attributes. Pozwala to uytkownikom zmieni domylne zachowanie
       za pomoc opcji linii polece.

   NADPISYWANIE FUNKCJI found_string
       Innym prostym krokiem jest nadpisanie funkcji "found_string", ktora
       otrzymuje od parsera wycignite komunikaty do przetlumaczenia. Tutaj
       mona kontrolowa, ktore komunikaty tlumaczy, oraz przeprowadzi na nich
       transformacje zarowno przed tlumaczeniem, jak i po nim.

       Otrzymuje wyodrbniony tekst, odnonik do miejsca jego znalezienia i hash
       zawierajce dodatkowe informacje kontrolujce, ktore komunikaty s do
       przetlumaczenia, jak je przetlumaczy i jak wygenerowa komentarz.

       Zawarto tych opcji zaley od rodzaju lacucha znakow (podanego we
       rekordzie tego hasha):

       type="tag"
           Znaleziony lacuch znakow jest zawartoci elementu, ktory mona
           przetlumaczy. Wpis "tag_options" zawiera znaki opcji wycignite z
           pocztku hierarchii elementow z opcji "tags" modulu.

       type="attribute"
           Oznacza, e znaleziony tekst jest wartoci atrybutu moliwego do
           tlumaczenia. Wpis "attribute" zawiera nazw atrybutu.

       Funkcja musi zwroci tekst zastpujcy w tlumaczonym dokumencie tekst
       oryginalny. Podstawowy przyklad takiej funkcji:

         sub found_string {
           my ($self,$text,$ref,$options)=@_;
           $text = $self->translate($text,$ref,"type ".$options->{'type'},
             'wrap'=>$self->{options}{'wrap'});
           return $text;
         }

       Kolejny prosty przyklad mona znale w nowym module Dia, ktory tylko
       filtruje niektore lacuchy znakow.

   MODYFIKOWANIE TYP'OW ELEMENT'OW (DO ZROBIENIA)
       Jest to jeden z bardziej zloonych procesow, ale pozwala na (prawie)
       calkowite dostosowanie do wlasnych potrzeb. Jest oparty na licie
       hashow, z ktorych kady okrela sposob zachowania si typu elementu. Lista
       powinna by posortowana, tak e elementy bardziej ogolne wystpuj po
       bardziej szczegolowych (posortowanych najpierw po kluczach pocztkowych,
       a potem kocowych). Aby zdefiniowa typ elementu, trzeba utworzy hash
       zawierajcy nastpujce klucze:

       beginning
           Okrela pocztek elementu, po "<".

       end Okrela koniec elementu, przed ">".

       breaking
           Mowi, e jest to klasa elementow rozdzielajcych. Element
           nierozdzielajcy (inline) jest to taki element, ktore moe by pobrany
           jako zawarto innego elementu. Moe to przyjmowa wartoci false (0),
           true (1) lub undefinded. Jeli zostanie jako undefined, to trzeba
           bdzie zdefiniowa funkcje f_breaking, mowic, czy podany element tej
           klasy jest elementem rozdzielajcym, czy te nie.

       f_breaking
           Jest to funkcja, ktora powie, czy nastpny element jest elementem
           zamykajcym, czy te nie. Powinna by zdefiniowana, jeli nie
           zdefiniowano opcji breaking.

       f_extract
           Jeli wartoci tego klucza pozostanie undefined, to ogolne funkcje
           wyodrbniajce bd musialy wyodrbni ten element samodzielnie. Jest to
           uyteczne dla elementow, ktore mog zawiera w sobie inne elementy lub
           specjalne struktury, tak eby glowny parser nie oszalal. Funkcja
           otrzymuje flag logiczn mowic, czy element powinien zosta usunity z
           wejciowego strumienia, czy te nie.

       f_translate
           Funkcja otrzymuje element (w formacie get_string_until() ) i zwraca
           przetlumaczony element (przetlumaczone atrybuty lub wszystkie
           potrzebne transformacje) jako pojedynczy lacuch znakow.

FUNKCJE WEWNTRZNE, uywane do pisania parser'ow

   PRACA Z ELEMENTAMI
       get_path()
           Funkcja zwraca ciek biecego elementu od korzenia dokumentu w
           formacie <html><body><p>.

           Jako argument mona przekaza dodatkow tablic elementow (bez
           nawiasow). Elementy te zostan dolczone na kocu biecej cieki.

       tag_type()
           Funkcja zwraca indeks z listy tag_types, ktory odpowiada nastpnemu
           elementowi ze strumienia wejciowego, lub -1 gdy dotarla do koca
           pliku wejciowego.

       extract_tag($$)
           Funkcja zwraca nastpny element ze strumienia wejciowego bez pocztku
           i koca, w postaci tablicy i zarzdza odnonikami do pliku wejciowego.
           Przyjmuje dwa parametry: typ elementu (zwrocone przez tag_type) i
           warto logiczn, okrelajc, czy element powinien zosta usunity ze
           strumienia wejciowego.

       get_tag_name(@)
           Funkcja zwraca nazw nastpnego elementu przekazanego jako argument w
           formie tablicy zwracanej przez extract_tag.

       breaking_tag()
           Funkcja zwraca warto logiczn, ktora mowi, czy nastpny element jest
           elementem rozdzielajcym, czy nie (element inline). Nie zmienia
           strumienia wejciowego.

       treat_tag()
           Funkcja tlumaczy nastpny element z rodlowego strumienia, uywajc do
           tego wlasnych funkcji kadego typu elementu.

       tag_in_list($@)
           Funkcja zwraca warto bdc lacuchem znakow, mowic, czy jej pierwszy
           argument (hierarchia elementow) pasuje do ktoregokolwiek elementu
           jej drugiego argumentu (lista elementow lub hierarchii elementow).
           Zwraca 0, jeli nie pasuje. W przeciwnym razie zwraca opcje
           dopasowanego elementy (znaki z pocztku elementu) lub 1 (jeli
           element nie mial opcji).

   PRACA Z ATRYBUTAMI
       treat_attributes(@)
           Funkcja obsluguje tlumaczenia atrybutow elementow. Pobiera element
           bez znacznikow pocztku/koca, a nastpnie szuka atrybutow, tlumaczy
           te sporod nich, ktore s przeznaczone do tlumaczenia (podane w opcji
           "attributes" modulu). Zwraca prosty tekst z przetlumaczonym
           elementem.

   PRACA Z OPCJAMI MODU/LU
       treat_options()
           Funkcja wypelnia wewntrzne struktury zawierajce elementy, atrybuty
           i dane wlczane wraz z opcjami modulu (podanymi w linii polece lub w
           funkcji initialize).

   POBIERANIE TEKSTU Z PLIKU WEJCIOWEGO
       get_string_until($%)
           Funkcja zwraca tablic z liniami (i odnonikami) z wejciowego
           dokumentu dopoki nie znajdzie pierwszego argumentu. Drugim
           argumentem jest hash opcji. Warto 0 oznacza wylczenie (domylnie), a
           1 - wlczenie.

           Poprawne opcje:

           include
               Powoduje, e zwracana tablica zawiera szukany tekst.

           remove
               Usuwa zwrocony strumie z wejcia

           unquoted
               Zapewnia, e szukany tekst nie jest umieszczony w cudzyslowach.

       skip_spaces(\@)
           Funkcja otrzymuje jako argument odnonik do akapitu (w formacie
           zwroconym przez get_string_until), pomija spacje naglowka i zwraca
           prosty lacuch znakow.

       join_lines(@)
           Funkcja zwraca prosty lacuch znakow zawierajcy tekst z tablicy
           argumentu (odrzucajc odnoniki).

STATUS MODU/LU

       Ten modul umoliwia tlumaczenie elementow i atrybutow.

LISTA RZECZY DO ZROBIENIA

       DOCTYPE (ENCJE)

       Istnieje minimalna obsluga tlumacze encji. S one tlumaczone jako calo,
       a elementy nie s brane pod uwag. Encje wieloliniowe  nie s wspierane, a
       podczas tlumaczenia tekst encji jest zawsze zawijany.

       MODYFIKOWANIE TYPOW ELEMENTOW ODZIEDZICZONYCH MODULOW (przenie struktur
       tag_types do hasha $self?)

ZOBACZ TAKE

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

AUTORZY

        Jordi Vilalta <jvprat@gmail.com>
        Nicolas Francois <nicolas.francois@centraliens.net>

PRAWA AUTORSKIE I LICENCJA

        Copyright (c) 2004 by Jordi Vilalta  <jvprat@gmail.com>
        Copyright (c) 2008-2009 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).