Locale::Po4a::Sgml - konwersja dokumentów SGML z/do plików PO
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.
- 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>Á</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.
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ć.
Moduł jest zaadaptowaną wersją sgmlspl (postprocesora SGML
parsera ONSGMLS), który był:
Copyright © 1995 David Megginson <[email protected]>
Adaptacji do po4a dokonali:
Denis Barbier <[email protected]>
Martin Quinson (mquinson#debian.org)
Robert Luberda <[email protected]>
Copyright © 1995 David Megginson <[email protected]>.
Copyright © 2002-2005 SPI, Inc.
Program jest wolnym oprogramowaniem; można go redystrybuować i/lub
modyfikować zgodnie z warunkami licencji GPL (patrz plik
COPYING).