Provided by: po4a_0.33.3-1_all bug

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).