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 <dmeggins@aix1.uottawa.ca>
Adaptacji do po4a dokonali:
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Robert Luberda <robert@debian.org>
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).