blib::man::Sgml(3pm)

NAZWA
Locale::Po4a::Sgml - Konwersja dokumentow sgml z/do plikow PO

OPIS
Celem projektu po4a ("po for anything") jest uXatwienie tXumaczen~ (oraz, co ciekawsze, zarzXdzania tXumaczeniami) przy uXyciu narzedzi gettext w tych obszarach, gdzie nie byXy uXywane, jak na przykXad w obszarze dokumentacji.

Locale::Po4a::Sgml jest moduXem uXatwiajXcym tXumaczenie dokumentacji w formacie SGML do innych jezykow [uXywanych przez ludzi].

OPCJE AKCEPTOWANE PRZEZ TEN MODUX

debug
    Rozdzielona spacjami lista sXow kluczowych, okreXlajXca, ktorX czeXae chcesz debugowaae. MoXliwe wartoXci: tag, generic, entities i refs.

verbose
    Daje wiecej informacji na temat tego, co sie dzieje.

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

section
    Rozdzielona spacjami lista dodatkowych elementow (oprocz tych zdefiniowanych w DTD), zawierajXcych inne elementy, wXrod ktorych istniejX elementy naleXXce do kategorii 'translate'.

indent
    Rozdzielona spacjami lista elementow, ktore zwiekszajX poziom wciecia.

verbatim
    Struktura takich elementow nie powinna byae zmieniana. Tekst akapitu nie bedzie zawijany i nie zostanX dodane Xadne kosmetyczne dodatkowe spacje czy znaki nowej linii.

empty
    Elementy nie muszX byae zamkniete.

ignore
    Elementy ignorowane i uznawane przez po4a za zwykXe dane znakowe. MogX byae one czeXciX msgid. Na przykXad <b> jest dobrym kandydatem do tej kategorii, poniewaX dodanie go w sekcji translate stworzyXoby msgid, nie bedXce caXymi zdaniami, co niewXtpliwie jest zXe.

attributes
    Rozdzielona spacjami lista atrybutow, ktore muszX byae przetXumaczone. MoXna okreXliae atrybuty przez ich nazwe (na przykXad "lang"), ale moXna takXe uXyae hierarchii elementow jako przedrostkow, tak aby okreXliae, Xe ten atrybut bedzie przetXumaczony tylko wtedy, gdy naleXy do podanego elementu. Na przykXad: <bbb><aaa>lang okreXla, Xe atrybut lang bedzie przetXumaczony tylko wtedy, gdy wystepuje w elemencie <aaa>, ktory z kolei jest zawarty w elemencie <bbb>. Nazwy elementow sX tak naprawde wyraXeniami regularnymi, tak wiec moXna przykXadowo uXyae <aaa|bbbb>lang do przetXumaczenia tylko tych atrybutow lang, ktore sX zawarte w elementach <aaa> lub <bbb>.

qualify
    Rozdzielona spacjami lista atrybutow, ktorych tXumaczenia muszX byae XXczone z nazwX atrybutu. Prosze zauwaXyae, Xe ta opcja automatycznie doda podany atrybut do listy "attributes".

force
    Kontynuowanie dziaXania, nawet gdy DTD nie jest znany.

include-all
    DomyXlnie, msgid zawierajXce tylko jednX encje (jak "&version;") sX pomijane, zapewniajXc komfort tXumaczowi. Aktywowanie tej opcji uniemoXliwia te optymalizacje. MoXe byae jednak uXyteczne, gdy dokument zawiera konstrukcje takie, jak "<title>&Aacute;</title>", choae prawde mowiXc, wXtpie, by takie coX sie mogXo kiedykolwiek zdarzyae...

ignore-inclusion
    Rozdzielona spacjami lista encji, ktore nie bedX wXXczane. Tej opcji naleXy uXywaae ostroXnie: moXe spowodowaae, Xe nsgmls (uXywany wewnetrznie przez ten moduX) doda elementy i wygeneruje niepoprawny dokument wyjXciowy.

STATUS MODUXU
Wynik jest doskonaXy. Tj. wygenerowane dokumenty sX dokXadnie takie same. Jednak wciXX jest pare problemow:

•   wyjXcie bXedow programu nsgmls jest przekierowane do /dev/null, co z pewnoXciX jest zXym pomysXem. Nie wiem, jak temu zapobiec.

    Problemem jest to, Xe musiaXem "ochroniae" warunkowe wXXczenia (rzeczy takie jak "<! [ %foo [" i "]]>") w nsgmls. W przeciwnym razie nsgmls je zjada, a nie mam pojecia jak je przywrociae w kon~cowym dokumencie. Aby temu zapobiec, przepisaXem je jako {PO4A-beg-coX}> i "{PO4A-end}".

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

    Wszystko dziaXa dobrze, z takim przekierowaniem wyjXcia nsgmls. Niestety uniemoXliwia nam to wykrycie, Xe dokument jest Xle sformatowany.

•   DziaXa to tylko z dtd debiandoc i docbook. Dodanie obsXugi nowego dtd powinno byae bardzo proste. Mechanizm jest taki sam dla kaXdego dtd, po prostu naleXy podaae liste istniejXcych elementow i ich charakterystyke.

    Zgadzam sie, to wymaga dokXadniejszej dokumentacji, jednak jest to wciXX wersja beta, a ja nienawidze dokumentowania rzeczy, ktore sie mogX zmieniae i zmieniX.

•   OstrzeXenie: obsXuga dtd jest caXkiem eksperymentalna. Nie przeczytaXem Xadnego podrecznika, Xeby znaleXae definicje kaXdego elementu. DodaXem definicje elementow, ktore dziaXajX dla kilku dokumentow znalezionych w sieci. JeXli Twoj dokument uXywa wiecej elementow niX moj, nie bedzie dziaXaX. Jak napisaXem wyXej, poprawienie tego powinno byae proste.

    TestowaXem docbook tylko na dokumencie SAG (System Administrator Guide), jednak jest on caXkiem spory, wiec powinien uXywaae wiekszoXci rzeczy specyficznych dla tego formatu.

    Dla debiandoc, przetestowaXem kilka podrecznikow z DDP, ale jeszcze nie wszystkie.

•   W razie doXXczania plikow odnoXniki do komunikatow wiadomoXci w plikach po (tj. linie jak "#: en/titletoc.sgml:9460") bedX niepoprawne.

    Dzieje sie tak dlatego, Xe wstepnie przetwarzam ten plik, aby ochroniae warunkowe wXXczenia (rzeczy takie jak "<! [ %foo [" i "]]>") oraz niektore encja (jak &version) przed nsgmls poniewaX chce je otrzymaae bez zmian w wygenerowanym dokumencie. Dlatego, tworze tymczasowX kopie pliku wejXciowego i na niej robie wszystkie zmiany przed przekazaniem go programowi nsgmls do przetwarzania.

    Xeby to dziaXaXo, zamieniam encje proszXce o wXXczenie pliku zawartoXciX podanego pliku (dlatego moge ochroniae to, co trzeba, takXe w plikach wXXczanych). Ale do tej pory nic nie jest robione, aby poprawiae poXniej odnoXniki (tj. nazwe pliku i numer linii). Nie jestem pewien, jak moXna by to najlepiej zrobiae.

AUTORZY
ModuX jest zaadaptowanX wersjX sgmlspl (postprocesora SGML parserow SGMLS i NSGMLS), ktory byX:

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

Adaptacji do po4a dokonali:

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

TXUMACZENIE
 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; moXna go redystrybuowaae i/lub modyfikowaae zgodnie z warunkami licencji GPL (patrz plik COPYING).