jammy (3) Locale::Po4a::Sgml.3pm.gz

Provided by: po4a_0.66-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 onsgmls(1). 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 onsgmls 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 onsgmls (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:

       • The error output of onsgmls is redirected to /dev/null by default, which is clearly bad. I don't know
         how to avoid that.

         Problemem jest to, że musiałem "ochronić" warunkowe włączenia (rzeczy takie jak "<! [ %foo [" i "]]>")
         w onsgmls. W przeciwnym razie onsgmls 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}".

         The problem with this is that the "{PO4A-end}" and such I add are invalid in the document (not in a <p>
         tag or so).

         If you want to view the onsgmls output, just add the following to your command line (or po4a
         configuration line):

           -o debug=onsgmls

       • 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 onsgmls 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 onsgmls 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 parsera ONSGMLS), który był:

        Copyright © 1995 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 © 1995 David Megginson <dmeggins@aix1.uottawa.ca>.
        Copyright © 2002-2005 SPI, Inc.

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