.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Sgml 3"
.TH Locale::Po4a::Sgml 3 "2012-05-17" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAZWA"
.IX Header "NAZWA"
Locale::Po4a::Sgml \- konwersja dokumentów \s-1SGML\s0 z/do plików \s-1PO\s0
.SH "OPIS"
.IX Header "OPIS"
Celem projektu po4a (\*(L"\s-1PO\s0 for anything\*(R") 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.
.PP
Locale::Po4a::Sgml jest modułem ułatwiającym tłumaczenie dokumentacji w
formacie \s-1SGML\s0 do innych języków [używanych przez ludzi].
.PP
Moduł ten do przetworzenia plików \s-1SGML\s0 używa programu \fBnsgmls\fR. Proszę się
upewnić, że program ten wraz z definicjami \s-1DTD\s0 plików SGMLjest zainstalowany
w systemie.
.SH "OPCJE AKCEPTOWANE PRZEZ MODUŁ"
.IX Header "OPCJE AKCEPTOWANE PRZEZ MODUŁ"
.IP "\fBdebug\fR" 4
.IX Item "debug"
Rozdzielona spacjami lista słów kluczowych, określająca, którą część chcesz
debugować. Możliwe wartości: tag, generic, entities i refs.
.IP "\fBverbose\fR" 4
.IX Item "verbose"
Daje więcej informacji na temat tego, co się dzieje.
.IP "\fBtranslate\fR" 4
.IX Item "translate"
Rozdzielona spacjami lista dodatkowych elementów (oprócz tych zdefiniowanych
w \s-1DTD\s0), których zawartość powinna utworzyć dodatkowy msgid.
.IP "\fBsection\fR" 4
.IX Item "section"
Rozdzielona spacjami lista dodatkowych elementów (oprócz tych zdefiniowanych
w \s-1DTD\s0), zawierających inne elementy, wśród których istnieją elementy
należące do kategorii \fBtranslate\fR.
.IP "\fBindent\fR" 4
.IX Item "indent"
Rozdzielona spacjami lista elementów, które zwiększają poziom wcięcia.
.IP "\fBverbatim\fR" 4
.IX Item "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.
.IP "\fBempty\fR" 4
.IX Item "empty"
Elementy nie muszą być zamknięte.
.IP "\fBignore\fR" 4
.IX Item "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.
.IP "\fBattributes\fR" 4
.IX Item "attributes"
Rozdzielona spacjami lista atrybutów, które muszą być przetłumaczone. Można
określić atrybuty przez ich nazwę (na przykład \*(L"lang\*(R"), 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>.
.IP "\fBqualify\fR" 4
.IX Item "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 \*(L"attributes\*(R".
.IP "\fBforce\fR" 4
.IX Item "force"
Kontynuowanie działania, nawet gdy \s-1DTD\s0 nie jest znany lub gdy nsgmls wykryje
błędy w pliku wejściowym.
.IP "\fBinclude-all\fR" 4
.IX Item "include-all"
Domyślnie, msgid zawierające tylko jedną encję (jak \*(L"&version;\*(R") 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 \*(L"<title>&Aacute;</title>\*(R", choć prawdę mówiąc,
wątpię, by takie coś się mogło kiedykolwiek zdarzyć...
.IP "\fBignore-inclusion\fR" 4
.IX Item "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.
.SH "STATUS MODUŁU"
.IX Header "STATUS MODUŁU"
Wynik jest doskonały. Tj. wygenerowane dokumenty są dokładnie takie
same. Jednak wciąż jest parę problemów:
.IP "\(bu" 2
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.
.Sp
Problemem jest to, że musiałem \*(L"ochronić\*(R" warunkowe włączenia (rzeczy takie
jak \f(CW\*(C`<! [ %foo [\*(C'\fR i \f(CW\*(C`]]>\*(C'\fR) 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 \f(CW\*(C`{PO4A\-end}\*(C'\fR.
.Sp
Problem z tym jest taki, że \f(CW\*(C`{PO4A\-end}\*(C'\fR i podobne, które dodam, są
poprawne w dokumencie (ale nie w elemencie <p> lub podobnym).
.Sp
Wszystko działa dobrze, z takim przekierowaniem wyjścia nsgmls. Niestety
uniemożliwia nam to wykrycie, że dokument jest źle sformatowany.
.IP "\(bu" 2
Działa to tylko z \s-1DTD\s0 DebianDoc i DocBook. Dodanie obsługi nowego \s-1DTD\s0
powinno być bardzo proste. Mechanizm jest taki sam dla każdego \s-1DTD\s0, po
prostu należy podać listę istniejących elementów i ich charakterystykę.
.Sp
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ą.
.IP "\(bu" 2
Ostrzeżenie: obsługa \s-1DTD\s0 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.
.Sp
Testowałem DocBook tylko na dokumencie \s-1SAG\s0 (System Administrator Guide),
jednak jest on całkiem spory, więc powinien używać większości rzeczy
specyficznych dla tego formatu.
.Sp
Dla DebianDoc, przetestowałem kilka podręczników z \s-1DDP\s0, ale jeszcze nie
wszystkie.
.IP "\(bu" 2
W razie dołączania plików odnośniki do komunikatów wiadomości w plikach \s-1PO\s0
(tj. linie jak \f(CW\*(C`#: en/titletoc.sgml:9460\*(C'\fR) będą niepoprawne.
.Sp
Dzieje się tak dlatego, że wstępnie przetwarzam ten plik, aby ochronić
warunkowe włączenia (rzeczy takie jak \f(CW\*(C`<! [ %foo [\*(C'\fR i \f(CW\*(C`]]>\*(C'\fR) 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.
.Sp
Ż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ć.
.SH "AUTORZY"
.IX Header "AUTORZY"
Moduł jest zaadaptowaną wersją sgmlspl (postprocesora \s-1SGML\s0 parserów \s-1SGMLS\s0 i
\&\s-1NSGMLS\s0), który był:
.PP
.Vb 1
\& Copyright (c) 1995 by David Megginson <dmeggins@aix1.uottawa.ca>
.Ve
.PP
Adaptacji do po4a dokonali:
.PP
.Vb 2
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH "PRAWA AUTORSKIE I LICENCJA"
.IX Header "PRAWA AUTORSKIE I LICENCJA"
.Vb 2
\& Copyright (c) 1995 by David Megginson <dmeggins@aix1.uottawa.ca>
\& Copyright 2002, 2003, 2004, 2005 by SPI, inc.
.Ve
.PP
Program jest wolnym oprogramowaniem; można go redystrybuować i/lub
modyfikować zgodnie z warunkami licencji \s-1GPL\s0 (patrz plik \s-1COPYING\s0).
