Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::Xml.3pm

NAZWA

Locale::Po4a::Xml - Konwersja dokumentA~Xw XML i pochodnych z/do plikA~Xw PO

OPIS

Celem projektu po4a (``po for anything'') jest uA°Xatwienie tA°XumaczeA°X (oraz, co ciekawsze, zarzA.Xdzania tA°Xumaczeniami) przy uA°Xyciu narzA.Xdzi gettext w tych obszarach, gdzie nie byA°Xy uA°Xywane, jak na przykA°Xad w obszarze dokumentacji.

Locale::Po4a::XML jest moduA°Xem uA°XatwiajA.Xcym tA°Xumaczenie dokumentA~Xw XML do innych jA.XzykA~Xw [uA°Xywanych przez ludzi].

TA°XUMACZENIE Z POMOCA.X PO4A::XML

Tego moduA°Xu moA°Xna uA°XyA.X bezpoA°Xrednio do obsA°Xugi ogA~Xlnych dokumentA~Xw w formacie XML. WyciA.Xgnie on zawartoA°XA.X wszystkich elementA~Xw, bez A°Xadnych atrybutA~Xw, poniewaA°X to wA°XaA°Xnie w elementach jest zapisywany tekst w wiA.XkszoA°Xci dokumentA~Xw opartych na XML-u.

Istnieje kilka opcji (opisanych w nastA.Xpnej sekcji), ktA~Xre mogA.X dostosowaA.X zachowanie do Twoich wymagaA°X. JeA°Xli nie pasuje ono do formatu Twojego dokumentu, zachA.Xcamy do napisania wA°Xasnego moduA°Xu dziedziczA.Xcego z tego, opisujA.Xcego szczegA~XA°Xy formatu. SzczegA~XA°Xy moA°Xna znaleA°XA.X w sekcji ``Pisanie moduA°XA~Xw pochodnych'' poniA°Xej.

OPCJE AKCEPTOWANE PRZEZ TEN MODUA°X

Globalna opcja debug powoduje, A°Xe ten moduA°X pokaA°Xe wyA°XA.Xczone komunikaty, aby mA~Xc sprawdziA.X, czy przypadkiem nie pomija czegoA°X istotnego.

Opcje tego moduA°Xu:

nostrip

UniemoA°Xliwia usuwanie spacji otaczajA.Xcych wyodrA.Xbnione komunikaty.

wrap

Kanonizuje komunikaty do przetA°Xumaczenia, przyjmujA.Xc, A°Xe spacje nie sA.X waA°Xnie i tylko sA°XuA°XA.X do zawijania przetA°Xumaczonego dokumentu. TA.X opcjA.X moA°Xna nadpisaA.X opcjami dotyczA.Xcymi wA°Xasnych elementA~Xw. Patrz opis opcji ``tags'' poniA°Xej.

caseinsensitive

Powoduje, A°Xe elementy i atrybuty sA.X wyszukiwane z pominiA.Xciem rozpoznawania wielkoA°Xci liter. JeA°Xli jest to zdefiniowane, to <BooK>laNG i <BOOK>Lang zostanA.X potraktowane tak samo jak <book>lang.

includeexternal

JeA°Xeli zdefiniowano, zewnA.Xtrzne encje sA.X doA°XA.Xczane do wygenerowanego (przetA°Xumaczonego) dokumentu oraz do wyodrA.Xbnionych A°XaA°XcuchA~Xw znakA~Xw. JeA°Xeli nie zdefiniowano, bA.Xdzie trzeba przetA°XumaczyA.X zewnA.Xtrzne encje jako niezaleA°Xne dokumenty.

ontagerror

Ta opcja okreA°Xla zachowanie moduA°Xu, kiedy wykryje bA°XA.Xd skA°Xadni XML (element zamykany, ktA~Xry nie odpowiada elementowi ostatnio otwieranemu lub brak jest wartoA°Xci atrybutu elementu). MoA°Xe przyjmowaA.X nastA.XpujA.Xce wartoA°Xci:

fail

Jest to domyA°Xlna wartoA°XA.X. DziaA°Xanie moduA°Xu zakoA°Xczy siA.X bA°XA.Xdem.

warn

ModuA°X wyA°Xwietli ostrzeA°Xenie i bA.Xdzie kontynuowaA°X dziaA°Xanie,

silent

ModuA°X bA.Xdzie kontynuowaA°X bez wypisywania A°Xadnych ostrzeA°XeA°X.

ProszA.X zachowaA.X ostroA°XnoA°XA.X, uA°XywajA.Xc tej opcji. Rekomendowanym zachowaniem jest poprawienie pliku wejA°Xciowego.

tagsonly

WyodrA.Xbnia tylko elementy podane w opcji ``tags''. W przeciwnym wypadku wyodrA.Xbni wszystkie elementy poza podanymi w tej opcji.

Uwaga: Opcja ta jest przestarzaA°Xa.

doctype

A°XaA°Xcuch znakA~Xw, ktA~Xry bA.Xdziemy prA~Xbowali dopasowaA.X do pierwszej linii typu dokumentu (doctype; jeA°Xli zdefiniowany). JeA°Xli nie pasuje, to dokument bA.Xdzie uwaA°Xany za majA.Xcy niepoprawny typ.

tags

Rozdzielona spacjami lista elementA~Xw, ktA~Xre majA.X byA.X przetA°Xumaczone lub opuszczone. DomyA°Xlnie podane elementy bA.XdA.X opuszczone, ale uA°Xycie opcji ``tagsonly'' oznacza, A°Xe podane elementy zostanA.X wA°XA.Xczone. Elementy muszA.X mieA.X postaA.X <aaa>, jednak moA°Xna poA°XA.XczyA.X kilka z nich (<bbb><aaa>), aby okreA°XliA.X, A°Xe zawartoA°XA.X elementu <aaa> bA.Xdzie przetA°Xumaczona tylko wtedy, gdy sam element jest zawarty w elemencie <bbb>.

MoA°Xna podaA.X takA°Xe kilka opcji elementA~Xw dodajA.Xc pewne znaki na poczA.Xtku hierarchii elementA~Xw. Na przykA°Xad moA°Xna dodaA.X ``w'' (zawijaj tekst) lub ``W'' (nie zawijaj), aby nadpisaA.X domyA°Xlne zachowanie okreA°Xlone przez globalnA.X opcjA.X ``wrap''.

PrzykA°Xad: W<chapter><title>

Uwaga: Opcja ta jest przestarzaA°Xa. Prosimy zamiast niej uA°XywaA.X opcji translated i untranslate.

attributes

Rozdzielona spacjami lista atrybutA~Xw elementA~Xw, ktA~Xre naleA°Xy tA°XumaczyA.X. MoA°Xna podaA.X atrybuty, uA°XywajA.Xc ich nazwy (na przykA°Xad ``lang''), ale takA°Xe moA°Xna poprzedziA.X je hierarchiA.X elementA~Xw, aby powiedzieA.X, A°Xe ten atrybut bA.Xdzie tA°Xumaczony tylko wtedy. gdy jest zawarty w okreA°Xlonym elemencie. Na przykA°Xad <bbb><aaa>lang mA~Xwi, A°Xe atrybut lang zostanie przetA°Xumaczony, tylko jeA°Xeli jest zawarty w elemencie <aaa>, ktA~Xry jest w elemencie <bbb>.

inline

Rozdzielona spacjami lista elementA~Xw, ktA~Xre powinny zostaA.X potraktowane jako inline. DomyA°Xlnie wszystkie elementy przerywajA.X sekwencjA.X. SkA°Xadnia jest taka sama jak opcji tags.

nodefault

Rozdzielona spacjami lista elementA~Xw, ktA~Xrych moduA°X nie powinien prA~XbowaA.X domyA°Xlnie umieszczaA.X w kategoriach ``tags'' lub ``inline''.

cpp

Wspiera dyrektywy preprocesora C. JeA°Xli opcja zostanie wA°XA.Xczona, po4a bA.Xdzie przetwarzaA°X dyrektywy preprocesora jako separatory akapitA~Xw. Jest to waA°Xne, jeA°Xli plik XML jest przetwarzanyprzez preprocesor, poniewaA°X jeA°Xli nie uA°Xyje siA.X tej opcji, a dyrektywy preprocesora trafiA.X w A°Xrodek linii, to po4a przyjmie, A°Xa naleA°XA.X do bieA°XA.Xcego paragramu, co spowoduje, A°Xe preprocesor ich juA°X nie rozpozna. Uwaga: dyrektywy preprocesora muszA.X byA.X umieszczone miA.Xdzy elementami (nie mogA.X rozdzielaA.X elementu).

translated

unstranslated

Rozdzielona spacjami lista elementA~Xw, ktA~Xre majA.X byA.X przetA°Xumaczone lub opuszczone. Elementy muszA.X mieA.X postaA.X <aaa>, jednak moA°Xna poA°XA.XczyA.X kilka z nich (<bbb><aaaE>), aby okreA°XliA.X, A°Xe zawartoA°XA.X elementu <aaa> bA.Xdzie przetA°Xumaczona tylko wtedy, gdy sam element jest zawarty w elemencie <bbb>

MoA°Xna podaA.X takA°Xe kilka opcji elementA~Xw dodajA.Xc pewne znaki na poczA.Xtku hierarchii elementA~Xw. Na przykA°Xad moA°Xna dodaA.X ``w'' (zawijaj tekst) lub ``W'' (nie zawijaj), aby nadpisaA.X domyA°Xlne zachowanie okreA°Xlone przez globalnA.X opcjA.X ``wrap''.

PrzykA°Xad: W<chapter><title>

PRACA Z MODUA°XAMI POCHODNYMI

DEFINIOWANIE ELEMENTA~XW I ATRYBUTA~XW DO PRZETA°XUMACZENIA

NajprostszA.X zmianA.X jest zdefiniowanie elementA~Xw i atrybutA~Xw, ktA~Xre parser ma przetA°XumaczyA.X. Powinno byA.X to zrobione w funkcji initialize. Najpierw trzeba wywoA°XaA.X gA°XA~XwnA.X funkcjA.X initialize, aby otrzymaA.X opcje linii poleceA°X, a nastA.Xpnie dodaA.X wA°Xasne definicje do hasha opcji. Aby obsA°XuA°XyA.X nowe opcje w linii poleceA°X, trzeba je zdefiniowaA.X przed wywoA°Xaniem gA°XA~Xwnej 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'', ktA~Xra otrzymuje od parsera wyciA.XgniA.Xte komunikaty, aby je przetA°XumaczyA.X. Tutaj moA°Xna kontrolowaA.X, ktA~Xre komunikaty tA°XumaczyA.X, oraz przeprowadziA.X transformacje na nich przed tA°Xumaczeniem i po nim.

Otrzymuje wyodrA.Xbniony tekst, odnoA°Xnik do miejsca jego znalezienia i hash zawierajA.Xce dodatkowe informacje kontrolujA.Xce, ktA~Xre komunikaty sA.X do przetA°Xumaczenia, jak je przetA°XumaczyA.X i jak wygenerowaA.X komentarz.

ZawartoA°XA.X tych opcji zaleA°Xy od rodzaju A°XaA°Xcucha znakA~Xw (podanego we rekordzie tego hasha):

type="tag"

Znaleziony A°XaA°Xcuch znakA~Xw jest zawartoA°XciA.X elementu, ktA~Xry moA°Xna przetA°XumaczyA.X. Wpis ``tag_options'' zawiera znaki opcji wyciA.XgniA.Xte z poczA.Xtku hierarchii elementA~Xw z opcji ``tags'' moduA°Xu.

type="attribute"

Oznacza, A°Xe znaleziony tekst jest wartoA°XciA.X atrybutu moA°Xliwego do tA°Xumaczenia. Wpis ``attribute'' zawiera nazwA.X atrybutu.

Musi zwrA~XciA.X tekst zastA.XpujA.Xcy w tA°Xumaczonym dokumencie tekst oryginalny. Podstawowy przykA°Xad 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 przykA°Xad moA°Xna znaleA°XA.X w nowym module Dia, ktA~Xry tylko filtruje niektA~Xre A°XaA°Xcuchy znakA~Xw.

MODYFIKOWANIE TYPA~XW ELEMENTA~XW (DO ZROBIENIA)

Jest to jeden z bardziej zA°XoA°Xonych, ale pozwala na (prawie) caA°Xkowite dostosowanie do wA°Xasnych potrzeb. Jest oparty na liA°Xcie hashA~Xw, z ktA~Xrych kaA°Xdy okreA°Xla sposA~Xb zachowania siA.X typu elementu. Lista powinna byA.X posortowana, tak A°Xe elementy bardziej ogA~Xlne wystA.XpujA.X po bardziej szczegA~XA°Xowych (posortowanych najpierw po kluczach poczA.Xtkowych, a potem koA°Xcowych). Aby zdefiniowaA.X typ elementu, trzeba utworzyA.X hash zawierajA.Xcy nastA.XpujA.Xce klucze:

beginning

OkreA°Xla poczA.Xtek elementu, po ``<''.

end

OkreA°Xla koniec elementu, przed ``>''.

breaking

MA~Xwi, A°Xe jest to klasa elementA~Xw rozdzielajA.Xcych. Element nierozdzielajA.Xcy (inline) jest to taki element, ktA~Xre moA°Xe byA.X pobrany jako zawartoA°XA.X innego elementu. MoA°Xe to przyjmowaA.X wartoA°Xci false (0), true (1) lub undefinded. JeA°Xli zostanie jako undefined, to trzeba bA.Xdzie zdefiniowaA.X funkcje f_breaking, mA~XwiA.XcA.X, czy podany element tej klasy jest elementem rozdzielajA.Xcym, czy teA°X nie.

f_breaking

Jest to funkcja, ktA~Xra powie, czy nastA.Xpny element jest elementem zamykajA.Xcym, czy teA°X nie. Powinna byA.X zdefiniowana, jeA°Xli nie zdefiniowano opcji ``breaking''.

f_extract

JeA°Xli wartoA°XciA.X tego klucza pozostanie undefined, to ogA~Xlne funkcje wyodrA.XbniajA.Xce bA.XdA.X musiaA°Xy wyodrA.XbniA.X ten element samodzielnie. Jest to uA°Xyteczne dla elementA~Xw, ktA~Xre mogA.X zawieraA.X w sobie inne elementy lub specjalne struktury, tak A°Xeby gA°XA~Xwny parser nie oszalaA°X. Funkcja otrzymuje flagA.X logicznA.X mA~XwiA.XcA.X, czy element powinien zostaA.X usuniA.Xty z wejA°Xciowego strumienia, czy teA°X nie.

f_translate

Funkcja otrzymuje element (w formacie get_string_until() ) i zwraca przetA°Xumaczony element (przetA°Xumaczone atrybuty lub wszystkie potrzebne transformacje) jako pojedynczy A°XaA°Xcuch znakA~Xw.

FUNKCJE WEWNA.XTRZNE, uA°Xywane do pisania parserA~Xw

PRACA Z ELEMENTAMI

get_path()

Funkcja zwraca A°XcieA°XkA.X bieA°XA.Xcego elementu od korzenia dokumentu w formacie <html><body><p>.

tag_type()

Funkcja zwraca indeks z listy tag_types, ktA~Xry odpowiada nastA.Xpnemu elementowi ze strumienia wejA°Xciowego, lub -1 gdy dotarA°Xa do koA°Xca pliku wejA°Xciowego.

extract_tag($$)

Funkcja zwraca nastA.Xpny element ze strumienia wejA°Xciowego bez poczA.Xtku i koA°Xca, w postaci tablicy i zarzA.Xdza odnoA°Xnikami do pliku wejA°Xciowego. Przyjmuje dwa parametry: typ elementu (zwrA~Xcone przez tag_type) i wartoA°XA.X logicznA.X, okreA°XlajA.XcA.X, czy element powinien zostaA.X usuniA.Xty ze strumienia wejA°Xciowego.

get_tag_name(@)

Funkcja zwraca nazwA.X nastA.Xpnego elementu przekazanego jako argument w formie tablicy zwracanej przez extract_tag.

breaking_tag()

Funkcja zwraca wartoA°XA.X logicznA.X, ktA~Xra mA~Xwi, czy nastA.Xpny element jest elementem rozdzielajA.Xcym, czy nie (element inline). Nie zmienia strumienia wejA°Xciowego.

treat_tag()

Funkcja tA°Xumaczy nastA.Xpny element z A°XrA~XdA°Xowego strumienia, UA°Xywa do tA°Xumaczenia wA°Xasnych funkcji kaA°Xdego typu elementu.

tag_in_list($@)

Funkcja zwraca wartoA°XA.X bA.XdA.XcA.X A°XaA°Xcuchem znakA~Xw, mA~XwiA.XcA.X, czy jej pierwszy argument (hierarchia elementA~Xw) pasuje do ktA~Xregokolwiek elementu jej drugiego argumentu (lista elementA~Xw lub hierarchii elementA~Xw). Zwraca 0, jeA°Xli nie pasuje. W przeciwnym razie zwraca opcje dopasowanego elementy (znaki z poczA.Xtku elementu) lub 1 (jeA°Xli element nie miaA°X opcji).

PRACA Z ATRYBUTAMI

treat_attributes(@)

Funkcja obsA°Xuguje tA°Xumaczenia atrybutA~Xw elementA~Xw. Pobiera element bez znacznikA~Xw poczA.Xtku/koA°Xca, a nastA.Xpnie szuka atrybutA~Xw, tA°Xumaczy te spoA°XrA~Xd nich, ktA~Xre sA.X przeznaczone do tA°Xumaczenia (podane w opcji ``attributes'' moduA°Xu). Zwraca prosty tekst z przetA°Xumaczonym elementem.

PRACA Z OPCJAMI MODUA°XU

treat_options()

Funkcja wypeA°Xnia wewnA.Xtrzne struktury zawierajA.Xce elementy, atrybuty i wA°XA.Xczane dane opcjami moduA°Xu (podanymi w linii poleceA°X lub w funkcji initialize).

POBIERANIE TEKSTU Z PLIKU WEJA°XCIOWEGO

get_string_until($%)

Funkcja zwraca tablicA.X z liniami (i odnoA°Xnikami) z wejA°Xciowego dokumentu dopA~Xki nie znajdzie pierwszego argumentu. Drugim argumentem jest hash opcji. WartoA°XA.X 0 oznacza wyA°XA.Xczenie (domyA°Xlnie), a 1 - wA°XA.Xczenie.

Poprawne opcje:

include

Powoduje, A°Xe zwracana tablica zawiera szukany tekst.

remove

Usuwa zwrA~Xcony strumieA°X z wejA°Xcia

unquoted

Zapewnia, A°Xe szukany tekst nie jest umieszczony w cudzysA°Xowach.

skip_spaces(\@)

Funkcja otrzymuje jako argument odnoA°Xnik do akapitu (w formacie zwrA~Xconym przez get_string_until), pomija spacje nagA°XA~Xwka i zwraca prosty A°XaA°Xcuch znakA~Xw.

join_lines(@)

Funkcja zwraca prosty A°XaA°Xcuch znakA~Xw zawierajA.Xcy tekst z tablicy argumentu (odrzucajA.Xc odnoA°Xniki).

STATUS MODUA°XU

Ten moduA°X umoA°Xliwia tA°Xumaczenie elementA~Xw i atrybutA~Xw.

Wsparcie dla encji i plikA~Xw wA°XA.Xczanych jest na naszej liA°Xcie rzeczy do zrobienia.

Pisanie moduA°XA~Xw pochodnych jest raczej ograniczone.

LISTA RZECZY DO ZROBIENIA

DOCTYPE (ENCJE)

Istnieje minimalna obsA°Xuga tA°XumaczeA°X encji. SA.X one tA°Xumaczone jako caA°XoA°XA.X, a elementy nie sA.X brane pod uwagA.X. Encje wieloliniowe nie sA.X wspierane, a podczas tA°Xumaczenia tekst encji jest zawsze zawijany.

PLIKI WA°XA.XCZANE

MODYFIKOWANIE TYPA~XW ELEMENTA~XW ODZIEDZICZONYCH MODUA°XA~XW (przenieA°XA.X strukturA.X tag_types do hasha $self?)

element dzielA.Xcy w A°Xrodku elementu niedzielA.Xcego (czy to jest moA°Xliwe?) powoduje brzydkie komentarze.

ZOBACZ TAKA°XE

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

AUTORZY

  Jordi Vilalta <jvprat@gmail.com>
 
 

TA°XUMACZENIE

  Robert Luberda <robert@debian.org>
 
 

PRAWA AUTORSKIE I LICENCJA

Copyright (c) 2004 by Jordi Vilalta <jvprat@gmail.com>

Program jest wolnym oprogramowaniem; moA°Xna go redystrybuowaA.X i/lub modyfikowaA.X zgodnie z warunkami licencji GPL (patrz plik COPYING).