bionic (3) Locale::Po4a::Sgml.3pm.gz
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].
This module uses onsgmls(1) to parse the SGML files. Make sure it is installed. Also make sure that the
DTD of the SGML files are installed in the system.
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
Proceed even if the DTD is unknown or if onsgmls finds errors in the input file.
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
Space separated list of entities that won't be inlined. Use this option with caution: it may cause
onsgmls (used internally) to add tags and render the output document invalid.
STATUS MODUŁU
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.
The problem is that I have to "protect" the conditional inclusions (i.e. the "<! [ %foo [" and "]]>"
stuff) from onsgmls. Otherwise onsgmls eats them, and I don't know how to restore them in the final
document. To prevent that, I rewrite them to "{PO4A-beg-foo}" and "{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.
This is because I preprocess the file to protect the conditional inclusion (i.e. the "<! [ %foo [" and
"]]>" stuff) and some entities (like &version;) from onsgmls because I want them verbatim to the
generated document. For that, I make a temp copy of the input file and do all the changes I want to
this before passing it to onsgmls for parsing.
Ż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
This module is an adapted version of sgmlspl (SGML postprocessor for the ONSGMLS parser) which was:
Copyright (c) 1995 by David Megginson <dmeggins@aix1.uottawa.ca>
Adaptacji do po4a dokonali:
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
TŁUMACZENIE
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; można go redystrybuować i/lub modyfikować zgodnie z warunkami licencji GPL (patrz plik COPYING).