Provided by: po4a_0.41-1_all bug

NAZWA
       Locale::Po4a::Sgml - konwersja dokumentow SGML z/do plikow PO


OPIS
       Celem projektu po4a ("PO for anything") jest ulatwienie tlumacze (oraz,
       co ciekawsze, zarzdzania tlumaczeniami) przy uyciu narzdzi gettext w
       tych obszarach, gdzie nie byly uywane, jak na przyklad w obszarze
       dokumentacji.

       Locale::Po4a::Sgml jest modulem ulatwiajcym tlumaczenie dokumentacji w
       formacie SGML do innych jzykow [uywanych przez ludzi].

       Modul ten do przetworzenia plikow SGML uywa programu nsgmls. Prosz si
       upewni, e program ten wraz z definicjami DTD plikow SGMLjest
       zainstalowany w systemie.


OPCJE AKCEPTOWANE PRZEZ MODU/L
       debug
           Rozdzielona spacjami lista slow kluczowych, okrelajca, ktor cz
           chcesz debugowa. Moliwe wartoci: tag, generic, entities i refs.

       verbose
           Daje wicej informacji na temat tego, co si dzieje.

       translate
           Rozdzielona spacjami lista dodatkowych elementow (oprocz tych
           zdefiniowanych w DTD), ktorych zawarto powinna utworzy dodatkowy
           msgid.

       section
           Rozdzielona spacjami lista dodatkowych elementow (oprocz tych
           zdefiniowanych w DTD), zawierajcych inne elementy, wrod ktorych
           istniej elementy nalece do kategorii translate.

       indent
           Rozdzielona spacjami lista elementow, ktore zwikszaj poziom wcicia.

       verbatim
           Struktura takich elementow nie powinna by zmieniana. Tekst akapitu
           nie bdzie zawijany i nie zostan dodane adne kosmetyczne dodatkowe
           spacje czy znaki nowej linii.

       empty
           Elementy nie musz by zamknite.

       ignore
           Elementy ignorowane i uznawane przez po4a za zwykle dane znakowe.
           Mog by one czci msgid. Na przyklad <b> jest dobrym kandydatem do
           tej kategorii, poniewa dodanie go w sekcji translate stworzyloby
           msgid, nie bdce calymi zdaniami, co niewtpliwie jest zle.

       attributes
           Rozdzielona spacjami lista atrybutow, ktore musz by przetlumaczone.
           Mona okreli atrybuty przez ich nazw (na przyklad "lang"), ale mona
           take uy hierarchii elementow jako przedrostkow, tak aby okreli, e
           ten atrybut bdzie przetlumaczony tylko wtedy, gdy naley do podanego
           elementu. Na przyklad: <bbb><aaa>lang okrela, e atrybut lang bdzie
           przetlumaczony tylko wtedy, gdy wystpuje w elemencie <aaa>, ktory z
           kolei jest zawarty w elemencie <bbb>. Nazwy elementow s tak naprawd
           wyraeniami regularnymi, tak wic mona przykladowo uy <aaa|bbbb>lang
           do przetlumaczenia tylko tych atrybutow lang, ktore s zawarte w
           elementach <aaa> lub <bbb>.

       qualify
           Rozdzielona spacjami lista atrybutow, ktorych tlumaczenia musz by
           lczone z nazw atrybutu. Prosz zauway, e ta opcja automatycznie doda
           podany atrybut do listy "attributes".

       force
           Kontynuowanie dzialania, nawet gdy DTD nie jest znany lub gdy
           nsgmls wykryje bldy w pliku wejciowym.

       include-all
           Domylnie, msgid zawierajce tylko jedn encj (jak "&version;") s
           pomijane, zapewniajc komfort tlumaczowi. Aktywowanie tej opcji
           uniemoliwia t optymalizacj. Moe by jednak uyteczne, gdy dokument
           zawiera konstrukcje takie, jak "<title>&Aacute;</title>", cho prawd
           mowic, wtpi, by takie co si moglo kiedykolwiek zdarzy...

       ignore-inclusion
           Rozdzielona spacjami lista encji, ktore nie bd wlczane. Tej opcji
           naley uywa ostronie: moe spowodowa, e nsgmls (uywany wewntrznie
           przez ten modul) doda elementy i wygeneruje niepoprawny dokument
           wyjciowy.


STATUS MODU/LU
       Wynik jest doskonaly. Tj. wygenerowane dokumenty s dokladnie takie
       same. Jednak wci jest par problemow:

       o Wyjcie bldow programu nsgmls jest przekierowane do /dev/null, co z
         pewnoci jest zlym pomyslem. Nie wiem, jak temu zapobiec.

         Problemem jest to, e musialem "ochroni" warunkowe wlczenia (rzeczy
         takie jak "<! [ %foo [" i "]]>") w nsgmls. W przeciwnym razie nsgmls
         je zjada, a nie mam pojcia jak je przywroci w kocowym dokumencie. Aby
         temu zapobiec, przepisalem je jako {PO4A-beg-co}> i "{PO4A-end}".

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

         Wszystko dziala dobrze, z takim przekierowaniem wyjcia nsgmls.
         Niestety uniemoliwia nam to wykrycie, e dokument jest le
         sformatowany.

       o Dziala to tylko z DTD DebianDoc i DocBook. Dodanie obslugi nowego DTD
         powinno by bardzo proste. Mechanizm jest taki sam dla kadego DTD, po
         prostu naley poda list istniejcych elementow i ich charakterystyk.

         Zgadzam si, to wymaga dokladniejszej dokumentacji, jednak jest to wci
         wersja beta, a ja nienawidz dokumentowania rzeczy, ktore si mog
         zmieni i zmieni.

       o Ostrzeenie: obsluga DTD jest calkiem eksperymentalna. Nie
         przeczytalem adnego podrcznika, eby znale definicje kadego elementu.
         Dodalem definicje elementow, ktore dzialaj dla kilku dokumentow
         znalezionych w sieci. Jeli Twoj dokument uywa wicej elementow ni moj,
         nie bdzie dzialal. Jak napisalem wyej, poprawienie tego powinno by
         proste.

         Testowalem DocBook tylko na dokumencie SAG (System Administrator
         Guide), jednak jest on calkiem spory, wic powinien uywa wikszoci
         rzeczy specyficznych dla tego formatu.

         Dla DebianDoc, przetestowalem kilka podrcznikow z DDP, ale jeszcze
         nie wszystkie.

       o W razie dolczania plikow odnoniki do komunikatow wiadomoci w plikach
         PO (tj. linie jak "#: en/titletoc.sgml:9460") bd niepoprawne.

         Dzieje si tak dlatego, e wstpnie przetwarzam ten plik, aby ochroni
         warunkowe wlczenia (rzeczy takie jak "<! [ %foo [" i "]]>") oraz
         niektore encja (jak &version) przed nsgmls poniewa chc je otrzyma bez
         zmian w wygenerowanym dokumencie. Dlatego, tworz tymczasow kopi pliku
         wejciowego i na niej robi wszystkie zmiany przed przekazaniem go
         programowi nsgmls do przetwarzania.

         eby to dzialalo, zamieniam encje proszce o wlczenie pliku zawartoci
         podanego pliku (dlatego mog ochroni to, co trzeba, take w plikach
         wlczanych). Ale do tej pory nic nie jest robione, aby poprawi poniej
         odnoniki (tj. nazw pliku i numer linii). Nie jestem pewien, jak mona
         by to najlepiej zrobi.


AUTORZY
       Modul jest zaadaptowan wersj sgmlspl (postprocesora SGML parserow SGMLS
       i NSGMLS), ktory byl:

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

       Adaptacji do po4a dokonali:

        Denis Barbier <barbier@linuxfr.org>
        Martin Quinson (mquinson#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; mona go redystrybuowa i/lub
       modyfikowa zgodnie z warunkami licencji GPL (patrz plik COPYING).