Provided by:
po4a_0.33.3-1_all 
NAZWA
Locale::Po4a::Xml - Konwersja dokumentów XML i pochodnych z/do plików
PO
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::XML jest modułem ułatwiającym tłumaczenie dokumentów XML
do innych języków [używanych przez ludzi].
TŁUMACZENIE Z POMOCĄ PO4A::XML
Tego modułu można użyć bezpośrednio do obsługi ogólnych dokumentów w
formacie XML. Wyciągnie on zawartość wszystkich elementów, bez żadnych
atrybutów, ponieważ to właśnie w elementach jest zapisywany tekst w
większości dokumentów opartych na XML-u.
Istnieje kilka opcji (opisanych w następnej sekcji), które mogą
dostosować zachowanie do Twoich wymagań. Jeśli nie pasuje ono do
formatu Twojego dokumentu, zachęcamy do napisania własnego modułu
dziedziczącego z tego, opisującego szczegóły formatu. Szczegóły można
znaleźć w sekcji "Pisanie modułów pochodnych" poniżej.
OPCJE AKCEPTOWANE PRZEZ TEN MODUŁ
Globalna opcja debug powoduje, że ten moduł pokaże wyłączone
komunikaty, aby móc sprawdzić, czy przypadkiem nie pomija czegoś
istotnego.
Opcje tego modułu:
nostrip
Uniemożliwia usuwanie spacji otaczających wyodrębnione komunikaty.
wrap
Kanonizuje komunikaty do przetłumaczenia, przyjmując, że spacje nie
są ważnie i tylko służą do zawijania przetłumaczonego dokumentu. Tę
opcję można nadpisać opcjami dotyczącymi własnych elementów. Patrz
opis opcji "tags" poniżej.
caseinsensitive
Powoduje, że elementy i atrybuty są wyszukiwane z pominięciem
rozpoznawania wielkości liter. Jeśli jest to zdefiniowane, to
<BooK>laNG i <BOOK>Lang zostaną potraktowane tak samo jak
<book>lang.
includeexternal
Jeżeli zdefiniowano, zewnętrzne encje są dołączane do
wygenerowanego (przetłumaczonego) dokumentu oraz do wyodrębnionych
łańcuchów znaków. Jeżeli nie zdefiniowano, będzie trzeba
przetłumaczyć zewnętrzne encje jako niezależne dokumenty.
ontagerror
Ta opcja określa zachowanie modułu, kiedy wykryje błąd składni XML
(element zamykany, który nie odpowiada elementowi ostatnio
otwieranemu lub brak jest wartości atrybutu elementu). Może
przyjmować następujące wartości:
fail
Jest to domyślna wartość. Działanie modułu zakończy się błędem.
warn
Moduł wyświetli ostrzeżenie i będzie kontynuował działanie,
silent
Moduł będzie kontynuował bez wypisywania żadnych ostrzeżeń.
Proszę zachować ostrożność, używając tej opcji. Rekomendowanym
zachowaniem jest poprawienie pliku wejściowego.
tagsonly
Wyodrębnia tylko elementy podane w opcji "tags". W przeciwnym
wypadku wyodrębni wszystkie elementy poza podanymi w tej opcji.
Uwaga: Opcja ta jest przestarzała.
doctype
Łańcuch znaków, który będziemy próbowali dopasować do pierwszej
linii typu dokumentu (doctype; jeśli zdefiniowany). Jeśli nie
pasuje, to dokument będzie uważany za mający niepoprawny typ.
tags
Rozdzielona spacjami lista elementów, które mają być przetłumaczone
lub opuszczone. Domyślnie podane elementy będę opuszczone, ale
użycie opcji "tagsonly" oznacza, że podane elementy zostaną
włączone. Elementy muszą mieć postać <aaa>, jednak można połączyć
kilka z nich (<bbb><aaa>), aby określić, że zawartość elementu
<aaa> będzie przetłumaczona tylko wtedy, gdy sam element jest
zawarty w elemencie <bbb>.
Można podać także kilka opcji elementów dodając pewne znaki na
początku hierarchii elementów. Na przykład można dodać "w" (zawijaj
tekst) lub "W" (nie zawijaj), aby nadpisać domyślne zachowanie
określone przez globalną opcję "wrap".
Przykład: W<chapter><title>
Uwaga: Opcja ta jest przestarzała. Prosimy zamiast niej używać
opcji translated i untranslate.
attributes
Rozdzielona spacjami lista atrybutów elementów, które należy
tłumaczyć. Można podać atrybuty, używając ich nazwy (na przykład
"lang"), ale także można poprzedzić je hierarchią elementów, aby
powiedzieć, że ten atrybut będzie tłumaczony tylko wtedy. gdy jest
zawarty w określonym elemencie. Na przykład <bbb><aaa>lang mówi, że
atrybut lang zostanie przetłumaczony, tylko jeżeli jest zawarty w
elemencie <aaa>, który jest w elemencie <bbb>.
inline
Rozdzielona spacjami lista elementów, które powinny zostać
potraktowane jako inline. Domyślnie wszystkie elementy przerywają
sekwencję. Składnia jest taka sama jak opcji tags.
nodefault
Rozdzielona spacjami lista elementów, których moduł nie powinien
próbować domyślnie umieszczać w kategoriach "tags" lub "inline".
cpp Wspiera dyrektywy preprocesora C. Jeśli opcja zostanie włączona,
po4a będzie przetwarzał dyrektywy preprocesora jako separatory
akapitów. Jest to ważne, jeśli plik XML jest przetwarzanyprzez
preprocesor, ponieważ jeśli nie użyje się tej opcji, a dyrektywy
preprocesora trafią w środek linii, to po4a przyjmie, ża należą do
bieżącego paragramu, co spowoduje, że preprocesor ich już nie
rozpozna. Uwaga: dyrektywy preprocesora muszą być umieszczone
między elementami (nie mogą rozdzielać elementu).
tłumaczenie=wpis nieprzetłumaczony
Rozdzielona spacjami lista elementów, które mają być przetłumaczone
lub opuszczone. Elementy muszą mieć postać <aaa>, jednak można
połączyć kilka z nich (<bbb><aaaE>), aby określić, że zawartość
elementu <aaa> będzie przetłumaczona tylko wtedy, gdy sam element
jest zawarty w elemencie <bbb>
Można podać także kilka opcji elementów dodając pewne znaki na
początku hierarchii elementów. Na przykład można dodać "w" (zawijaj
tekst) lub "W" (nie zawijaj), aby nadpisać domyślne zachowanie
określone przez globalną opcję "wrap".
Przykład: W<chapter><title>
PRACA Z MODUŁAMI POCHODNYMI
DEFINIOWANIE ELEMENTÓW I ATRYBUTÓW DO PRZETŁUMACZENIA
Najprostszą zmianą jest zdefiniowanie elementów i atrybutów, które
parser ma przetłumaczyć. Powinno być to zrobione w funkcji initialize.
Najpierw trzeba wywołać główną funkcję initialize, aby otrzymać opcje
linii poleceń, a następnie dodać własne definicje do hasha opcji. Aby
obsłużyć nowe opcje w linii poleceń, trzeba je zdefiniować przed
wywołaniem głównej 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", która
otrzymuje od parsera wyciągnięte komunikaty, aby je przetłumaczyć.
Tutaj można kontrolować, które komunikaty tłumaczyć, oraz przeprowadzić
transformacje na nich przed tłumaczeniem i po nim.
Otrzymuje wyodrębniony tekst, odnośnik do miejsca jego znalezienia i
hash zawierające dodatkowe informacje kontrolujące, które komunikaty są
do przetłumaczenia, jak je przetłumaczyć i jak wygenerować komentarz.
Zawartość tych opcji zależy od rodzaju łańcucha znaków (podanego we
rekordzie tego hasha):
type="tag"
Znaleziony łańcuch znaków jest zawartością elementu, który można
przetłumaczyć. Wpis "tag_options" zawiera znaki opcji wyciągnięte z
początku hierarchii elementów z opcji "tags" modułu.
type="attribute"
Oznacza, że znaleziony tekst jest wartością atrybutu możliwego do
tłumaczenia. Wpis "attribute" zawiera nazwę atrybutu.
Musi zwrócić tekst zastępujący w tłumaczonym dokumencie tekst
oryginalny. Podstawowy przykład 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 przykład można znaleźć w nowym module Dia, który tylko
filtruje niektóre łańcuchy znaków.
MODYFIKOWANIE TYPÓW ELEMENTÓW (DO ZROBIENIA)
Jest to jeden z bardziej złożonych, ale pozwala na (prawie) całkowite
dostosowanie do własnych potrzeb. Jest oparty na liście hashów, z
których każdy określa sposób zachowania się typu elementu. Lista
powinna być posortowana, tak że elementy bardziej ogólne występują po
bardziej szczegółowych (posortowanych najpierw po kluczach
początkowych, a potem końcowych). Aby zdefiniować typ elementu, trzeba
utworzyć hash zawierający następujące klucze:
beginning
Określa początek elementu, po "<".
end Określa koniec elementu, przed ">".
breaking
Mówi, że jest to klasa elementów rozdzielających. Element
nierozdzielający (inline) jest to taki element, które może być
pobrany jako zawartość innego elementu. Może to przyjmować wartości
false (0), true (1) lub undefinded. Jeśli zostanie jako undefined,
to trzeba będzie zdefiniować funkcje f_breaking, mówiącą, czy
podany element tej klasy jest elementem rozdzielającym, czy też
nie.
f_breaking
Jest to funkcja, która powie, czy następny element jest elementem
zamykającym, czy też nie. Powinna być zdefiniowana, jeśli nie
zdefiniowano opcji "breaking".
f_extract
Jeśli wartością tego klucza pozostanie undefined, to ogólne funkcje
wyodrębniające będą musiały wyodrębnić ten element samodzielnie.
Jest to użyteczne dla elementów, które mogą zawierać w sobie inne
elementy lub specjalne struktury, tak żeby główny parser nie
oszalał. Funkcja otrzymuje flagę logiczną mówiącą, czy element
powinien zostać usunięty z wejściowego strumienia, czy też nie.
f_translate
Funkcja otrzymuje element (w formacie get_string_until() ) i zwraca
przetłumaczony element (przetłumaczone atrybuty lub wszystkie
potrzebne transformacje) jako pojedynczy łańcuch znaków.
FUNKCJE WEWNĘTRZNE, używane do pisania parserów
PRACA Z ELEMENTAMI
get_path()
Funkcja zwraca ścieżkę bieżącego elementu od korzenia dokumentu w
formacie <html><body><p>.
tag_type()
Funkcja zwraca indeks z listy tag_types, który odpowiada następnemu
elementowi ze strumienia wejściowego, lub -1 gdy dotarła do końca
pliku wejściowego.
extract_tag($$)
Funkcja zwraca następny element ze strumienia wejściowego bez
początku i końca, w postaci tablicy i zarządza odnośnikami do pliku
wejściowego. Przyjmuje dwa parametry: typ elementu (zwrócone przez
tag_type) i wartość logiczną, określającą, czy element powinien
zostać usunięty ze strumienia wejściowego.
get_tag_name(@)
Funkcja zwraca nazwę następnego elementu przekazanego jako argument
w formie tablicy zwracanej przez extract_tag.
breaking_tag()
Funkcja zwraca wartość logiczną, która mówi, czy następny element
jest elementem rozdzielającym, czy nie (element inline). Nie
zmienia strumienia wejściowego.
treat_tag()
Funkcja tłumaczy następny element z źródłowego strumienia, Używa do
tłumaczenia własnych funkcji każdego typu elementu.
tag_in_list($@)
Funkcja zwraca wartość będącą łańcuchem znaków, mówiącą, czy jej
pierwszy argument (hierarchia elementów) pasuje do któregokolwiek
elementu jej drugiego argumentu (lista elementów lub hierarchii
elementów). Zwraca 0, jeśli nie pasuje. W przeciwnym razie zwraca
opcje dopasowanego elementy (znaki z początku elementu) lub 1
(jeśli element nie miał opcji).
PRACA Z ATRYBUTAMI
treat_attributes(@)
Funkcja obsługuje tłumaczenia atrybutów elementów. Pobiera element
bez znaczników początku/końca, a następnie szuka atrybutów,
tłumaczy te spośród nich, które są przeznaczone do tłumaczenia
(podane w opcji "attributes" modułu). Zwraca prosty tekst z
przetłumaczonym elementem.
PRACA Z OPCJAMI MODUŁU
treat_options()
Funkcja wypełnia wewnętrzne struktury zawierające elementy,
atrybuty i włączane dane opcjami modułu (podanymi w linii poleceń
lub w funkcji initialize).
POBIERANIE TEKSTU Z PLIKU WEJŚCIOWEGO
get_string_until($%)
Funkcja zwraca tablicę z liniami (i odnośnikami) z wejściowego
dokumentu dopóki nie znajdzie pierwszego argumentu. Drugim
argumentem jest hash opcji. Wartość 0 oznacza wyłączenie
(domyślnie), a 1 - włączenie.
Poprawne opcje:
include
Powoduje, że zwracana tablica zawiera szukany tekst.
remove
Usuwa zwrócony strumień z wejścia
unquoted
Zapewnia, że szukany tekst nie jest umieszczony w cudzysłowach.
skip_spaces(\@)
Funkcja otrzymuje jako argument odnośnik do akapitu (w formacie
zwróconym przez get_string_until), pomija spacje nagłówka i zwraca
prosty łańcuch znaków.
join_lines(@)
Funkcja zwraca prosty łańcuch znaków zawierający tekst z tablicy
argumentu (odrzucając odnośniki).
STATUS MODUŁU
Ten moduł umożliwia tłumaczenie elementów i atrybutów.
Wsparcie dla encji i plików włączanych jest na naszej liście rzeczy do
zrobienia.
Pisanie modułów pochodnych jest raczej ograniczone.
LISTA RZECZY DO ZROBIENIA
DOCTYPE (ENCJE)
Istnieje minimalna obsługa tłumaczeń encji. Są one tłumaczone jako
całość, a elementy nie są brane pod uwagę. Encje wieloliniowe nie są
wspierane, a podczas tłumaczenia tekst encji jest zawsze zawijany.
PLIKI WŁĄCZANE
MODYFIKOWANIE TYPÓW ELEMENTÓW ODZIEDZICZONYCH MODUŁÓW (przenieść
strukturę tag_types do hasha $self?)
element dzielący w środku elementu niedzielącego (czy to jest możliwe?)
powoduje brzydkie komentarze.
ZOBACZ TAKŻE
po4a(7), Locale::Po4a::TransTractor(3pm).
AUTORZY
Jordi Vilalta <jvprat@gmail.com>
TŁUMACZENIE
Robert Luberda <robert@debian.org>
PRAWA AUTORSKIE I LICENCJA
Copyright (c) 2004 by Jordi Vilalta <jvprat@gmail.com>
Program jest wolnym oprogramowaniem; można go redystrybuować i/lub
modyfikować zgodnie z warunkami licencji GPL (patrz plik COPYING).