Provided by:
po4a_0.41-1_all 
NAZWA
Locale::Po4a::Man - konwersja stron podrcznika z/do plikow PO
OPIS
Celem projektu po4a ("PO for anything") jest ulatwienie tlumacze (oraz,
co ciekawsze, zarzdzania tlumaczeniami) przy uyciu narzdzi gettext w
tych obszarach, gdzie nie byly uywane, jak na przyklad w obszarze
dokumentacji.
Locale::Po4a::Man jest modulem ulatwiajcym tlumaczenie dokumentacji w
formacie nroff (jzyk stron podrcznika ekranowego) do innych jzykow
[uywanych przez ludzi].
T/LUMACZENIE Z POMOC PO4A::MAN
Modul bardzo si stara, aby ulatwi ycie tlumacza. Dlatego tekst
prezentowany tlumaczowi nie jest doslown kopi oryginalnego tekstu
strony podrcznika. W istocie, ukrywane s surowe czci formatu nroff, tak
eby tlumacze nie zrobili w nich balaganu.
Zawijanie tekstu
Teksty niewcitych akapitow s automatycznie zawijane dla wygody
tlumacza. Moe to prowadzi do niewielkich ronic w wygenerowanym pliku
wyjciowym, poniewa reguly zawijania tekstu uywane przez groffa nie s
jasne - na przyklad czasami groff zachowuje dwie spacje wystpujce po
nawiasie.
Tak czy owak, ronica bdzie dotyczyla tylko rozmieszczenia dodatkowych
spacji w zawinitym tekcie akapitu.
Okrelanie czcionki
Pierwsza zmiana dotyczy specyfikacji zmian czcionek. W nroffie istnieje
kilka sposobow okrelenia, e podane slowo powinno by napisane czcionk
mal, wytluszczon lub kursyw. W tekcie do przetlumaczenia mona to zrobi
tylko na jeden sposob, zapoyczony z formatu POD (formatu dokumentacji
Perla):
I<tekst> -- kursywa
odpowiednik \fItekst\fP lub ".I tekst"
B<tekst> -- tekst wytluszczony
odpowiednik \fBtekst\fP lub ".B tekst"
R<tekst> -- tekst zwykl czcionk
odpowiednik \fRtekst\fP
CW<tekst<gt> -- tekst o stalej szerokoci
odpowiednik \f(CWtekst\fP lub ".CW tekst"
Uwaga: CW nie jest dostpne dla wszystkich urzdze groffa. Uywanie go nie
jest zalecane. Jest dostarczone dla wygody uytkownika.
Automatyczna transliteracja znak'ow
Po4a automatycznie zamienia niektore znaki, aby ulatwi tlumaczenia lub
przegldanie tlumacze. Lista takich transliteracji:
lczniki
Lczniki (-) i znaki minusa (\-) w stronach podrcznika ekranowego s
wszystkie transliterowane do zwyklych mylnikow (-) w pliku PO.
Kiedy tlumaczenia s zapisywane w pliku wynikowym wszystkie mylniki
s zamieniane na znaki minusa (\-).
Tlumacze mog wymusi wstawienie lcznika, uywajc w swoich
tlumaczeniach kodu "\[hy]" groffa.
spacje nierozdzielajce
Tlumacze mog uywa nierozdzielajcych spacji w swoich tlumaczeniach.
Takie spacje nierozdzielajce (0xA0 w latin1) bd przetlumaczone jako
spacje nierozdzielajce roff ("\ ").
transliteracje cudzyslowow
`` i '' s odpowiednio zamieniane na \*(lq i \*(rq.
Aby unikn tych transliteracji, tlumacze mog umieci zerowej
szerokoci znak roffa (np. uywajc odpowiednio `\&` lub '\&').
Wstawianie "<" i ">" w t/lumaczeniach
Poniewa znaki te s uywane do oddzielania czci objtych zmian czcionki,
nie mona ich uywa wprost. Zamiast nich trzeba uy E<lt> i E<gt> (jak w
POD, po raz kolejny).
OPCJE AKCEPTOWANE PRZEZ MODU/L
Opcje tego modulu:
debug
Uaktywnia debugowanie kilku wewntrznych mechanizmow modulu.
Informacje o tym, ktore czci mog by debugowane, mona znale w
rodlach.
verbose
Zwiksza gadatliwo.
groff_code
Ta opcja pozwala na zmian zachowania modulu, kiedy napotka sekcj
.de, .ie lub .if. Moe przyjmowa nastpujce wartoci:
fail
Jest to domylna warto. Dzialanie modulu zakoczy si bldem, jeeli
zostanie napotkana sekcja .de, .ie lub .if.
verbatim
Okrela, e sekcje .de, .ie lub .if musz by skopiowane bez zmian
z oryginalu do tlumaczonego dokumentu.
translate
Wskazuje sekcje .de, .ie lub .if jako moliwe do
przetlumaczenia. Opcja powinna by uywana tylko wtedy, gdy ktora
z tych sekcji zawiera tekst do przetlumaczenia. W przeciwnym
razie wskazane byloby uycie verbatim.
generated
Ta opcja okrela, e plik zostal wygenerowany z innego formatu , a
po4a nie powinno probowa tego wykrywa. Pozwala to na uywanie po4a
wlanie na takich generowanych stronach podrcznika. Opcja nie
pobiera adnych argumentow.
mdoc
Ta opcja jest uyteczna tylko dla stron w formacie mdoc.
Wybiera dokladniejsz obslug formatu mdoc, nakazuj po4a
nietlumaczenie sekcji "NAME" (NAZWA). Strony mdoc, zawierajce
przetlumaczon sekcj "NAME", nie generuj naglowka ani stopki.
Zgodnie ze stron podrcznika groff_mdoc, wymagane s sekcje NAME
(NAZWA), SYNOPSIS (SKLADNIA)oraz DESCRIPTION (OPIS). Chocia nie ma
adnych znanych problemow z przetlumaczonymi sekcjami SYNOPSIS czy
DESCRIPTION, to ich tlumaczenie mona rownie pomin za pomoc:
-o mdoc=NAME,SYNOPSIS,DESCRIPTION
Kwesti mdoc mona take rozwiza, uywajc zalcznika podobnego do
poniszego:
PO4A-HEADER:mode=before;position=^.Dd
.TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"
Ponisze opcje pozwalaj okreli zachowanie nowego makra (zdefiniowanego
poleceniem .de) albo makra nieobslugiwanego przez po4a. Przyjmuj jako
argument rozdzielon przecinkami list makr. Na przyklad:
-o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
Uwaga: jeli po4a nie obsluguje danego makra, a uwaasz, e jest to
standardowe makro roff, prosz to zglosi zespolowi deweloperow po4a.
untranslated
untranslated oznacza, e to makro (i wszystkie jego argumenty) nie
musz by tlumaczone.
noarg
noarg jest jak untranslated, poza tym, e po4a sprawdzi, e do tego
makra nie dodano adnego argumentu.
translate_joined
translate_joined oznacza, e po4a musi zaproponowa tlumaczenie
argumentow makra.
translate_each
translate_each powoduje, e argumenty bd take zaproponowane do
tlumaczenia, z tym e kady z nich bdzie przetlumaczony osobno.
no_wrap
Opcja przyjmuje jako argument rozdzielon przecinkami list par
pocztek:koniec, gdzie pocztek i koniec s poleceniami ograniczajcymi
pocztek i koniec sekcji, ktorej tekst nie powinien by ponownie
zawijany.
Uwaga: nie jest sprawdzane, czy polecenie end ma odpowiadajce
polecenie begin; jakiekolwiek polecenie koczce zatrzyma tryb
no_wrap. Jeeli istnieje makro begin (odpowiednio end) nie majce
pasujcego end (odpowiednio begin), to mona poda istniejce end (jak
fi) lub begin (jak nf) jako zamiennik. Makra te (i ich argumenty)
nie bd tlumaczone.
inline
Opcja pozwala na podanie rozdzielonej przecinkami listy makr, ktore
nie mog dzieli biecego akapitu. Komunikat do przetlumaczenia bdzie
wtedy zawieral foo <.bar baz qux> quux, gdzie bar jest poleceniem,
ktore powinno by wlczone do pliku, a baz qux - jego argumentami.
unknown_macros
Ta opcja okrela zachowanie po4a po napotkaniu nieznanego makra.
Domylnie po4a wywietli ostrzeenie. Moliwe s nastpujce wartoci:
failed (warto domylna), untranslated, noarg, translate_joined,
translate_each.
PISANIE STRON PODRCZNIKA ZGODNYCH Z PO4A::MAN
Modul wci ma duo ogranicze i zawsze bdzie mial, poniewa nie jest
rzeczywistym interpreterem nroffa. Byloby moliwe wykonanie
rzeczywistego interpretera nroffa, aby umoliwi autorom uywanie w swoich
stronach wszystkich istniejcych makr i tworzenie nowych, ale nie
chcielimy tego robi. Byloby to zbyt trudne, a przy tym raczej
niepotrzebne. Uwaamy, e jeeli autorzy stron podrcznika chc, eby ich
strony byly przetlumaczone, to musz tak przeksztalci strony, by uproci
prac tlumaczy.
Tak wic, parser stron man zaimplementowany w po4a ma kilka znanych
ogranicze, ktorych nie chcemy poprawia, i bdcych pulapkami, ktorych
powiniene unika, jeli chcesz, eby tlumacze opiekowali si Twoj
dokumentacj.
Nie programuj w nroffie
nroff jest kompletnym jzykiem programowania z definicjami makr,
instrukcjami warunkowymi itd. Poniewa parser nie jest pelnowartociowym
interpreterem nroffa, zwroci bld podczas przetwarzania stron
zawierajcych te wlaciwoci. (Na moim komputerze jest okolo 200 takich
stron).
Uywaj prostego zbioru makr
Wci istnieje kilka makr, ktorych po4a nie obsluguje. Dzieje si tak
dlatego, e nie znalazlem adnej dokumentacji tych makr. Poniej jest
lista nieobslugiwanych makr znalezionych na moim komputerze. Prosz
zauway, e ta lista nie jest pelna, poniewa program koczy si, zwracajc
bld, ju po napotkaniu pierwszego nieznanego makra. Jeli masz jakie
informacje o niektorych z nich, z przyjemnoci dopisz ich obslug. Z
powodu tych makr okolo 250 stron na moim komputerze nie jest dostpnych
dla po4a::man.
.. ." .AT .b .bank
.BE ..br .Bu .BUGS .BY
.ce .dbmmanage .do .En
.EP .EX .Fi .hw .i
.Id .l .LO .mf
.N .na .NF .nh .nl
.Nm .ns .NXR .OPTIONS .PB
.pp .PR .PRE .PU .REq
.RH .rn .S< .sh .SI
.splitfont .Sx .T .TF .The
.TT .UC .ul .Vb .zZ
Ukrywanie tekstu przez po4a
Czasem autor wie, e niektore czci strony podrcznika nie powinny by
tlumaczone, wic nie powinny by przetwarzane przez po4a. Na przyklad
opcja moe pobiera argument other oraz other moe si take pojawi jako
ostatni element listu. Pierwsze other nie powinno by tlumaczone, a
drugie - powinno.
W takim przypadku, aby po4a pominlo takie komunikaty, autor moe uy
specjalnych konstrukcji groffa:
.if !'po4a'hide' .B other
(wymaga to podania opcji -o groff_code=verbatim)
Aby to zautomatyzowa, mona zdefiniowa nowe makro: .de IR_untranslated
. IR \\$@
..
.IR_untranslated \-q ", " \-\-quiet
(wymaga to podania opcji -o groff_code=verbatim i -o
untranslated=IR_untranslated; przy tej konstrukcji warunek .if
!'po4a'hide' staje si zbdny, poniewa po4a nie przetwarza wntrza
definicji makra)
lub uywajc aliasu:
.als IR_untranslated IR
.IR_untranslated \-q ", " \-\-quiet
(wymaga to podania opcji -o untranslated=als,IR_untranslated)
Wniosek
Podsumowujc t sekcj, pamitaj, eby tworzy proste strony podrcznika
ekranowego i nie stara si by zbyt pomyslowym. Roff pozwala na wiele
rzeczy, ktore nie s obslugiwane przez parser. Na przyklad: nie rob
balaganu, uywajc \c do przerwania przetwarzania tekstu (jak to robi 40
stron podrcznika na moim komputerze). Albo: argumenty makr umieszczaj w
tej samej linii, co samo makro. Wiem, e nroff dopuszcza rozdzielanie
makr i ich argumentow, ale obslugiwanie tego zbytnio by skomplikowalo
parser.
Oczywicie inn moliwoci jest uycie innego formatu, bardziej przyjaznego
tlumaczom (jak POD uywajcy po4a::pod albo jednego z rodziny XML, np.
SGML), ale nie jest to potrzebne dziki po4a::man. Jeli formatem
rodlowym Twojej dokumentacji jest POD lub XML, to byloby mdre, aby
przetlumaczy rodlowy format, a nie ten wygenerowany. W wikszoci
wypadkow po4a::man rozpozna wygenerowane strony i wypisze odpowiednie
ostrzeenie. A nawet odmowi przetwarzana stron wygenerowanych przez POD,
poniewa te strony s perfekcyjnie obslugiwane przez po4a::pod i poniewa
ich odpowiednik nroffa generuje wiele nowych makr, ktorych nie chc
obslugiwa. Na moim komputerze 1432 sporod 4323 stron jest
wygenerowanych z formatu POD i bdzie zignorowanych przez po4a::man.
W wikszoci wypadkow, po4a::man wykryje problem i odmowi przetwarzania
strony, wypisujc odpowiedni komunikat. W kilku rzadkich wypadkach,
program zakoczy si bez adnego ostrzeenia, ale plik wynikowy bdzie
niepoprawny. Takie sytuacje s nazywane "bldami";) Jeli spotkasz si z
tak sytuacj, prosz to zglosi wraz z odpowiedni poprawk, jeli to
moliwe...
STATUS MODU/LU
Modulu mona uywa z wikszoci istniejcych stron podrcznika.
Niektore testy s regularnie uruchamiane na komputerach z Linuksem:
o odrzucono jedn trzeci stron poniewa byly one wygenerowane z innego
formatu obslugiwanego przez po4a (np. POD lub SGML).
o 10% pozostalych stron odrzucono z powodu bldu (np. nieobslugiwane
makro groff).
o W kocu mniej ni 1% stron zostal zaakceptowany bez ostrzee przez
po4a, ale wystpily pewne powane problemy (np. usunite lub dodane
slowa).
o Inne strony s zazwyczaj obslugiwane bez ronic bardziej istotnych ni
ronice w liczbie spacji czy zawijaniu linii (problemy z czcionkami
w mniej ni 10% przetworzonych stron).
ZOBACZ TAKE
po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::Pod(3pm).
AUTORZY
Denis Barbier <barbier@linuxfr.org>
Nicolas Francois <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
PRAWA AUTORSKIE I LICENCJA
Copyright 2002-2008 by SPI, inc.
Program jest wolnym oprogramowaniem; mona go redystrybuowa i/lub
modyfikowa zgodnie z warunkami licencji GPL (patrz plik COPYING).