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

Narzędzia po4a                                     2023-01-03                            Locale::Po4a::Sgml(3pm)