Provided by: po4a_0.33.3-1_all bug

NAZWA

       Locale::Po4a::Sgml - Konwersja dokumentów sgml 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::Sgml jest modułem ułatwiającym tłumaczenie dokumentacji w
       formacie SGML do innych języków [używanych przez ludzi].

       Moduł ten do przetworzenia plików SGML używa programu nsgmls. Proszę
       się upewnić, że program ten wraz z definicjami DTD plików SGMLjest
       zainstalowany w systemie.

OPCJE AKCEPTOWANE PRZEZ TEN MODUŁ

       debug
           Rozdzielona spacjami lista słów kluczowych, określająca, którą
           część chcesz debugować. Możliwe wartości: tag, generic, entities i
           refs.

       verbose
           Daje więcej informacji na temat tego, co się dzieje.

       translate
           Rozdzielona spacjami lista dodatkowych elementów (oprócz tych
           zdefiniowanych w DTD), których zawartość powinna utworzyć dodatkowy
           msgid.

       section
           Rozdzielona spacjami lista dodatkowych elementów (oprócz tych
           zdefiniowanych w DTD), zawierających inne elementy, wśród których
           istnieją elementy należące do kategorii "translate".

       indent
           Rozdzielona spacjami lista elementów, które zwiększają poziom
           wcięcia.

       verbatim
           Struktura takich elementów nie powinna być zmieniana. Tekst akapitu
           nie będzie zawijany i nie zostaną dodane żadne kosmetyczne
           dodatkowe spacje czy znaki nowej linii.

       empty
           Elementy nie muszą być zamknięte.

       ignore
           Elementy ignorowane i uznawane przez po4a za zwykłe dane znakowe.
           Mogą być one częścią msgid. Na przykład <b> jest dobrym kandydatem
           do tej kategorii, ponieważ dodanie go w sekcji translate
           stworzyłoby msgid, nie będące całymi zdaniami, co niewątpliwie jest
           złe.

       attributes
           Rozdzielona spacjami lista atrybutów, które muszą być
           przetłumaczone. Można określić atrybuty przez ich nazwę (na
           przykład "lang"), ale można także użyć hierarchii elementów jako
           przedrostków, tak aby określić, że ten atrybut będzie
           przetłumaczony tylko wtedy, gdy należy do podanego elementu. Na
           przykład: <bbb><aaa>lang określa, że atrybut lang będzie
           przetłumaczony tylko wtedy, gdy występuje w elemencie <aaa>, który
           z kolei jest zawarty w elemencie <bbb>. Nazwy elementów są tak
           naprawdę wyrażeniami regularnymi, tak więc można przykładowo użyć
           <aaa|bbbb>lang do przetłumaczenia tylko tych atrybutów lang, które
           są zawarte w elementach <aaa> lub <bbb>.

       qualify
           Rozdzielona spacjami lista atrybutów, których tłumaczenia muszą być
           łączone z nazwą atrybutu. Proszę zauważyć, że ta opcja
           automatycznie doda podany atrybut do listy "attributes".

       force
           Kontynuowanie działania, nawet gdy DTD nie jest znany lub gdy
           nsgmls wykryje błędy w pliku wejściowym.

       include-all
           Domyślnie, msgid zawierające tylko jedną encję (jak "&version;") są
           pomijane, zapewniając komfort tłumaczowi. Aktywowanie tej opcji
           uniemożliwia tę optymalizację. Może być jednak użyteczne, gdy
           dokument zawiera konstrukcje takie, jak "<title>&Aacute;</title>",
           choć prawdę mówiąc, wątpię, by takie coś się mogło kiedykolwiek
           zdarzyć...

       ignore-inclusion
           Rozdzielona spacjami lista encji, które nie będą włączane. Tej
           opcji należy używać ostrożnie: może spowodować, że nsgmls (używany
           wewnętrznie przez ten moduł) doda elementy i wygeneruje niepoprawny
           dokument wyjściowy.

STATUS MODUŁU

       Wynik jest doskonały. Tj. wygenerowane dokumenty są dokładnie takie
       same. Jednak wciąż jest parę problemów:

       o wyjście błędów programu nsgmls jest przekierowane do /dev/null, co z
         pewnością jest złym pomysłem. Nie wiem, jak temu zapobiec.

         Problemem jest to, że musiałem "ochronić" warunkowe włączenia (rzeczy
         takie jak "<! [ %foo [" i "]]>") w nsgmls. W przeciwnym razie nsgmls
         je zjada, a nie mam pojęcia jak je przywrócić w końcowym dokumencie.
         Aby temu zapobiec, przepisałem je jako {PO4A-beg-coś}> i
         "{PO4A-end}".

         Problem z tym jest taki, że "{PO4A-end}" i podobne, które dodam, są
         poprawne w dokumencie (ale nie w elemencie <p> lub podobnym).

         Wszystko działa dobrze, z takim przekierowaniem wyjścia nsgmls.
         Niestety uniemożliwia nam to wykrycie, że dokument jest źle
         sformatowany.

       o Działa to tylko z dtd debiandoc i docbook. Dodanie obsługi nowego dtd
         powinno być bardzo proste. Mechanizm jest taki sam dla każdego dtd,
         po prostu należy podać listę istniejących elementów i ich
         charakterystykę.

         Zgadzam się, to wymaga dokładniejszej dokumentacji, jednak jest to
         wciąż wersja beta, a ja nienawidzę dokumentowania rzeczy, które się
         mogą zmienić i zmienią.

       o Ostrzeżenie: obsługa dtd jest całkiem eksperymentalna. Nie
         przeczytałem żadnego podręcznika, żeby znaleźć definicje każdego
         elementu. Dodałem definicje elementów, które działają dla kilku
         dokumentów znalezionych w sieci. Jeśli Twój dokument używa więcej
         elementów niż mój, nie będzie działał. Jak napisałem wyżej,
         poprawienie tego powinno być proste.

         Testowałem docbook tylko na dokumencie SAG (System Administrator
         Guide), jednak jest on całkiem spory, więc powinien używać większości
         rzeczy specyficznych dla tego formatu.

         Dla debiandoc, przetestowałem kilka podręczników z DDP, ale jeszcze
         nie wszystkie.

       o W razie dołączania plików odnośniki do komunikatów wiadomości w
         plikach po (tj. linie jak "#: en/titletoc.sgml:9460") będą
         niepoprawne.

         Dzieje się tak dlatego, że wstępnie przetwarzam ten plik, aby
         ochronić warunkowe włączenia (rzeczy takie jak "<! [ %foo [" i "]]>")
         oraz niektóre encja (jak &version) przed nsgmls ponieważ chcę je
         otrzymać bez zmian w wygenerowanym dokumencie. Dlatego, tworzę
         tymczasową kopię pliku wejściowego i na niej robię wszystkie zmiany
         przed przekazaniem go programowi nsgmls do przetwarzania.

         Żeby to działało, zamieniam encje proszące o włączenie pliku
         zawartością podanego pliku (dlatego mogę ochronić to, co trzeba,
         także w plikach włączanych). Ale do tej pory nic nie jest robione,
         aby poprawić później odnośniki (tj. nazwę pliku i numer linii). Nie
         jestem pewien, jak można by to najlepiej zrobić.

AUTORZY

       Moduł jest zaadaptowaną wersją sgmlspl (postprocesora SGML parserów
       SGMLS i NSGMLS), który był:

        Copyright (c) 1995 by David Megginson <dmeggins@aix1.uottawa.ca>

       Adaptacji do po4a dokonali:

        Denis Barbier <barbier@linuxfr.org>
        Martin Quinson (mquinson#debian.org)

TŁUMACZENIE

        Robert Luberda <robert@debian.org>

PRAWA AUTORSKIE I LICENCJA

        Copyright (c) 1995 by David Megginson <dmeggins@aix1.uottawa.ca>
        Copyright 2002, 2003, 2004, 2005 by SPI, inc.

       Program jest wolnym oprogramowaniem; można go redystrybuować i/lub
       modyfikować zgodnie z warunkami licencji GPL (patrz plik COPYING).