blib::man::Xml(3pm)

NAZWA
Locale::Po4a::Xml - Konwersja dokumentow XML i pochodnych z/do plikow PO

OPIS
Celem projektu po4a ("po for anything") jest uXatwienie tXumaczen~ (oraz, co ciekawsze, zarzXdzania tXumaczeniami) przy uXyciu narzedzi gettext w tych obszarach, gdzie nie byXy uXywane, jak na przykXad w obszarze dokumentacji.

Locale::Po4a::XML jest moduXem uXatwiajXcym tXumaczenie dokumentow XML do innych jezykow [uXywanych przez ludzi].

Prosze zauwaXyae, Xe ten moduX jest wciXX rozwijany i nie jest dystrybuowany w oficjalnych wydaniach po4a, gdyX nie jest wystarczajXco stabilny. JeXli chcesz sprobowaae, musisz go XciXgnXae z CVS-a.

TXUMACZENIE Z POMOCX PO4A::XML
Tego moduXu moXna uXyae bezpoXrednio do obsXugi ogolnych dokumentow w formacie XML. WyciXgnie on zawartoXae wszystkich elementow, bez Xadnych atrybutow, poniewaX to wXaXnie w elementach jest zapisywany tekst w wiekszoXci dokumentow opartych na XML-u.

Istnieje kilka opcji (opisanych w nastepnej sekcji), ktore mogX dostosowaae zachowanie do Twoich wymagan~. JeXli nie pasuje ono do formatu Twojego dokumentu, zachecamy do napisania wXasnego moduXu dziedziczXcego z tego, opisujXcego szczegoXy formatu. SzczegoXy moXna znaleXae w sekcji "Pisanie moduXow pochodnych" poniXej.

OPCJE AKCEPTOWANE PRZEZ TEN MODUX
Globalna opcja debug powoduje, Xe ten moduX pokaXe wyXXczone komunikaty, aby moc sprawdziae, czy przypadkiem nie pomija czegoX istotnego.

Opcje tego moduXu:

nostrip
    UniemoXliwia usuwanie spacji otaczajXcych wyodrebnione komunikaty.

wrap
    Kanonizuje komunikaty do przetXumaczenia, przyjmujXc, Xe spacje nie sX waXnie i tylko sXuXX do zawijania przetXumaczonego dokumentu. Te opcje moXna nadpisaae opcjami dotyczXcymi wXasnych elementow. Patrz opis opcji "tags" poniXej.

caseinsensitive
    Powoduje, Xe elementy i atrybuty sX wyszukiwane z pominieciem rozpoznawania wielkoXci liter. JeXli jest to zdefiniowane, to <BooK>laNG i <BOOK>Lang zostanX potraktowane tak samo jak <book>lang.

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

doctype
    Xan~cuch znakow, ktory bedziemy probowali dopasowaae do pierwszej linii doctypu dokumentu (jeXli zdefiniowany). JeXli nie pasuje, to dokument bedzie uwaXany za majXcy niepoprawny typ.

tags
    Rozdzielona spacjami lista elementow, ktore majX byae przetXumaczone lub opuszczone. DomyXlnie podane elementy bede opuszczone, ale uXycie opcji "tagsonly" oznacza, Xe podane elementy zostanX wXXczone. Elementy muszX mieae postaae <aaa>, jednak moXna poXXczyae kilka z nich (<bbb><aaa>), aby okreXliae, Xe zawartoXae elementu <aaa> bedzie przetXumaczona tylko wtedy, gdy sam element jest zawarty w elemencie <bbb>.

    MoXna podaae takXe kilka opcji elementow dodajXc pewne znaki na poczXtku hierarchii elementow. Na przykXad moXna dodaae "w" (zawijaj tekst) lub "W" (nie zawijaj), aby nadpisaae domyXlne zachowanie okreXlone przez globalnX opcje "wrap".

    PrzykXad: W<chapter><title>

attributes
    Rozdzielona spacjami lista atrybutow elementow, ktore naleXy tXumaczyae. MoXna podaae atrybuty, uXywajXc ich nazwy (na przykXad "lang"), ale takXe moXna poprzedziae je hierarchiX elementow, aby powiedzieae, Xe ten atrybut bedzie tXumaczony tylko wtedy. gdy jest zawarty w okreXlonym elemencie. Na przykXad <bbb><aaa>lang mowi, Xe atrybut lang zostanie przetXumaczony, tylko jeXeli jest zawarty w elemencie <aaa>, ktory jest w elemencie <bbb>.

inline
    Rozdzielona spacjami lista elementow, ktore powinny zostaae potraktowane jako inline. DomyXlnie wszystkie elementy przerywajX sekwencje. SkXadnia jest taka sama jak opcji tags.

nodefault
    Rozdzielona spacjami lista elementow, ktorych moduX nie powinien probowaae domyXlnie umieszczaae w kategoriach "tags" lub "inline".

PRACA Z MODUXAMI POCHODNYMI

  DEFINIOWANIE ELEMENTOW I ATRYBUTOW DO PRZETXUMACZENIA
NajprostszX zmianX jest zdefiniowanie elementow i atrybutow, ktore parser ma przetXumaczyae. Powinno byae to zrobione w funkcji initialize. Najpierw trzeba wywoXaae gXownX funkcje initialize, aby otrzymaae opcje linii polecen~, a nastepnie dodaae wXasne definicje do hasha opcji. Aby obsXuXyae nowe opcje w linii polecen~, trzeba je zdefiniowaae przed wywoXaniem gXownej funkcje initialize:

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

  NADPISYWANIE FUNKCJI found_string
Innym prostym krokiem jest nadpisanie funkcji "found_string", ktora otrzymuje od parsera wyciXgniete komunikaty, aby je przetXumaczyae. Tutaj moXna kontrolowaae, ktore komunikaty tXumaczyae, oraz przeprowadziae transformacje na nich przed tXumaczeniem i po nim.

Otrzymuje wyodrebniony tekst, odnoXnik do miejsca jego znalezienia i hash zawierajXce dodatkowe informacje kontrolujXce, ktore komunikaty sX do przetXumaczenia, jak je przetXumaczyae i jak wygenerowaae komentarz.

ZawartoXae tych opcji zaleXy od rodzaju Xan~cucha znakow (podanego we rekordzie tego hasha):

type="tag"
    Znaleziony Xan~cuch znakow jest zawartoXciX elementu, ktory moXna przetXumaczyae. Wpis "tag_options" zawiera znaki opcji wyciXgniete z poczXtku hierarchii elementow z opcji "tags" moduXu.

type="attribute"
    Oznacza, Xe znaleziony tekst jest wartoXciX atrybutu moXliwego do tXumaczenia. Wpis "attribute" zawiera nazwe atrybutu.

Musi zwrociae tekst zastepujXcy w tXumaczonym dokumencie tekst oryginalny. Podstawowy przykXad tej 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 przykXad moXna znaleXae w nowym module Dia, ktory tylko filtruje niektore Xan~cuchy znakow.

  MODYFIKOWANIE TYPOW ELEMENTOW (DO ZROBIENIA)
Jest to jeden z bardziej zXoXonych, ale pozwala na (prawie) caXkowite dostosowanie do wXasnych potrzeb. Jest oparty na liXcie hashow, z ktorych kaXdy okreXla sposob zachowania sie typu elementu. Lista powinna byae posortowana, tak Xe elementy bardziej ogolne wystepujX po bardziej szczegoXowych (posortowanych najpierw po kluczach poczXtkowych, a potem kon~cowych). Aby zdefiniowaae typ elementu, trzeba utworzyae hash zawierajXcy nastepujXce klucze:

beginning
    OkreXla poczXtek elementu, po "<".

end OkreXla koniec elementu, przed ">".

breaking
    Mowi, Xe jest to klasa elementow rozdzielajXcych. Element nierozdzielajXcy (inline) jest to taki element, ktore moXe byae pobrany jako zawartoXae innego elementu. MoXe to przyjmowaae wartoXci false (0), true (1) lub undefinded. JeXli zostanie jako undefined, to trzeba bedzie zdefiniowaae funkcje f_breaking, mowiXcX, czy podany element tej klasy jest elementem rozdzielajXcym, czy teX nie.

f_breaking
    Jest to funkcja, ktora powie, czy nastepny element jest elementem zamykajXcym, czy teX nie. Powinna byae zdefiniowana, jeXli nie zdefiniowano opcji "breaking".

f_extract
    JeXli wartoXciX tego klucza pozostanie undefined, to ogolne funkcje wyodrebniajXce bedX musiaXy wyodrebniae ten element samodzielnie. Jest to uXyteczne dla elementow, ktore mogX zawieraae w sobie inne elementy lub specjalne struktury, tak Xeby gXowny parser nie oszalaX. Funkcja otrzymuje flage logicznX mowiXcX, czy element powinien zostaae usuniety z wejXciowego strumienia, czy teX nie.

f_translate
    Funkcja otrzymuje element (w formacie get_string_until() ) i zwraca przetXumaczony element (przetXumaczone atrybuty lub wszystkie potrzebne transformacje) jako pojedynczy Xan~cuch znakow.

FUNKCJE WEWNETRZNE, uXywane do pisania parserow

  PRACA Z ELEMENTAMI

get_path()
    Funkcja zwraca XcieXke bieXXcego elementu od korzenia dokumentu w formacie <html><body><p>.

tag_type()
    Funkcja zwraca indeks z listy tag_types, ktory odpowiada nastepnemu elementowi ze strumienia wejXciowego, lub -1 gdy dotarXa do kon~ca pliku wejXciowego.

extract_tag($$)
    Funkcja zwraca nastepny element ze strumienia wejXciowego bez poczXtku i kon~ca, w postaci tablicy i zarzXdza odnoXnikami do pliku wejXciowego. Przyjmuje dwa parametry: typ elementu (zwrocone przez tag_type) i wartoXae logicznX, okreXlajXcX, czy element powinien zostaae usuniety ze strumienia wejXciowego.

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

breaking_tag()
    Funkcja zwraca wartoXae logicznX, ktora mowi, czy nastepny element jest elementem rozdzielajXcym, czy nie (element inline). Nie zmienia strumienia wejXciowego.

treat_tag()
    Funkcja tXumaczy nastepny element z XrodXowego strumienia, UXywa do tXumaczenia wXasnych funkcji kaXdego typu elementu.

tag_in_list($@)
    Funkcja zwraca wartoXae bedXcX Xan~cuchem znakow, mowiXcX, czy jej pierwszy argument (hierarchia elementow) pasuje do ktoregokolwiek elementu jej drugiego argumentu (lista elementow lub hierarchii elementow). Zwraca 0, jeXli nie pasuje. W przeciwnym razie zwraca opcje dopasowanego elementy (znaki z poczXtku elementu) lub 1 (jeXli element nie miaX opcji).

  PRACA Z ATRYBUTAMI

treat_attributes(@)
    Funkcja obsXuguje tXumaczenia atrybutow elementow. Pobiera element bez znacznikow poczXtku/kon~ca, a nastepnie szuka atrybutow, tXumaczy te spoXrod nich, ktore sX przeznaczone do tXumaczenia (podane w opcji "attributes" moduXu). Zwraca prosty tekst z przetXumaczonym elementem.

  PRACA Z OPCJAMI MODUXU

treat_options()
    Funkcja wypeXnia wewnetrzne struktury zawierajXce elementy, atrybuty i wXXczane dane opcjami moduXu (podanymi w linii polecen~ lub w funkcji initialize).

  POBIERANIE TEKSTU Z PLIKU WEJXCIOWEGO

get_string_until($%)
    Funkcja zwraca tablice z liniami (i odnoXnikami) z wejXciowego dokumentu dopoki nie znajdzie pierwszego argumentu. Drugim argumentem jest hash opcji. WartoXae 0 oznacza wyXXczenie (domyXlnie), a 1 - wXXczenie.

    Poprawne opcje:

    include
        Powoduje, Xe zwracana tablica zawiera szukany tekst.

    remove
        Usuwa zwrocony strumien~ z wejXcia

    unquoted
        Zapewnia, Xe szukany tekst nie jest umieszczony w cudzysXowach.

skip_spaces(\@)
    Funkcja otrzymuje jako argument odnoXnik do akapitu (w formacie zwroconym przez get_string_until), pomija spacje nagXowka i zwraca prosty Xan~cuch znakow.

join_lines(@)
    Funkcja zwraca prosty Xan~cuch znakow zawierajXcy tekst z tablicy argumentu (odrzucajXc odnoXniki).

STATUS MODUXU
Ten moduX umoXliwia tXumaczenie elementow i atrybutow.

Wsparcie dla encji i plikow wXXczanych jest na naszej liXcie rzeczy do zrobienia.

Pisanie moduXow pochodnych jest raczej ograniczone.

LISTA RZECZY DO ZROBIENIA
DOCTYPE (ENCJE)

Istnieje minimalna obsXuga tXumaczen~ encji. SX one tXumaczone jako caXoXae, a elementy nie sX brane pod uwage. Encje wieloliniowe nie sX wspierane, a podczas tXumaczenia tekst encji jest zawsze zawijany.

PLIKI WXXCZANE

MODYFIKOWANIE TYPOW ELEMENTOW ODZIEDZICZONYCH MODUXOW (przenieXae strukture tag_types do hasha $self?)

element dzielXcy w Xrodku elementu niedzielXcego (czy to jest moXliwe?) powoduje brzydkie komentarze.

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

AUTORZY
 Jordi Vilalta <jvprat@gmail.com>

TXUMACZENIE
 Robert Luberda <robert@debian.org>

PRAWA AUTORSKIE I LICENCJA
Copyright (c) 2004 by Jordi Vilalta <jvprat@gmail.com>

Program jest wolnym oprogramowaniem; moXna go redystrybuowaae i/lub modyfikowaae zgodnie z warunkami licencji GPL (patrz plik COPYING).