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 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:

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

       • 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ą.

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

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