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
nsgmls. 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 nsgmls 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 nsgmls (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:
- •
- Wyjście błędów programu nsgmls jest
przekierowane do /dev/null, co z pewnością jest złym
pomysłem. Nie wiem, jak temu zapobiec.
Problemem jest to, że musiałem "ochronić" warunkowe
włączenia (rzeczy takie jak "<! [ %foo [" i
"]]>") w nsgmls. W przeciwnym razie nsgmls 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}".
Problem z tym jest taki, że "{PO4A-end}" i podobne,
które dodam, są poprawne w dokumencie (ale nie w elemencie
<p> lub podobnym).
Wszystko działa dobrze, z takim przekierowaniem wyjścia nsgmls.
Niestety uniemożliwia nam to wykrycie, że dokument jest źle
sformatowany.
- •
- 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 nsgmls 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 nsgmls 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
parserów SGMLS i NSGMLS), który był:
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; można go redystrybuować i/lub
modyfikować zgodnie z warunkami licencji GPL (patrz plik COPYING).
