oracular (3) Locale::Po4a::Man.3pm.gz
NAZWA
Locale::Po4a::Man - konwersja stron podręcznika 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::Man jest modułem ułatwiającym tłumaczenie dokumentacji w formacie nroff (język stron
podręcznika ekranowego) do innych języków [używanych przez ludzi].
TŁUMACZENIE Z POMOCĄ PO4A::MAN
Moduł bardzo się stara, aby ułatwić życie tłumacza. Dlatego tekst prezentowany tłumaczowi nie jest
dosłowną kopią oryginalnego tekstu strony podręcznika. W istocie, ukrywane są surowe części formatu
nroff, tak żeby tłumacze nie zrobili w nich bałaganu.
Zawijanie tekstu
Teksty niewciętych akapitów są automatycznie zawijane dla wygody tłumacza. Może to prowadzić do
niewielkich różnic w wygenerowanym pliku wyjściowym, ponieważ reguły zawijania tekstu używane przez
groffa nie są jasne - na przykład czasami groff zachowuje dwie spacje występujące po nawiasie.
Tak czy owak, różnica będzie dotyczyła tylko rozmieszczenia dodatkowych spacji w zawiniętym tekście
akapitu.
Określanie czcionki
Pierwsza zmiana dotyczy specyfikacji zmian czcionek. W nroffie istnieje kilka sposobów określenia, że
podane słowo powinno być napisane czcionką małą, wytłuszczoną lub kursywą. W tekście do przetłumaczenia
można to zrobić tylko na jeden sposób, zapożyczony z formatu POD (formatu dokumentacji Perla):
I<tekst> -- kursywa
odpowiednik \fItekst\fP lub ".I tekst"
B<tekst> -- tekst wytłuszczony
odpowiednik \fBtekst\fP lub ".B tekst"
R<tekst> -- tekst zwykłą czcionką
odpowiednik \fRtekst\fP
CW<tekst<gt> -- tekst o stałej szerokości
odpowiednik \f(CWtekst\fP lub ".CW tekst"
Uwaga: CW nie jest dostępne dla wszystkich urządzeń groffa. Używanie go nie jest zalecane. Jest
dostarczone dla wygody użytkownika.
Automatyczna transliteracja znaków
Po4a automatycznie zamienia niektóre znaki, aby ułatwić tłumaczenia lub przeglądanie tłumaczeń. Lista
takich transliteracji:
łączniki
Łączniki (-) i znaki minusa (\-) w stronach podręcznika ekranowego są wszystkie transliterowane do
zwykłych myślników (-) w pliku PO. Kiedy tłumaczenia są zapisywane w pliku wynikowym wszystkie
myślniki są zamieniane na znaki minusa (\-).
Tłumacze mogą wymusić wstawienie łącznika, używając w swoich tłumaczeniach kodu "\[hy]" groffa.
spacje nierozdzielające
Tłumacze mogą używać nierozdzielających spacji w swoich tłumaczeniach. Takie spacje nierozdzielające
(0xA0 w latin1) będą przetłumaczone jako spacje nierozdzielające roff ("\ ").
transliteracje cudzysłowów
`` i '' są odpowiednio zamieniane na \*(lq i \*(rq.
Aby uniknąć tych transliteracji, tłumacze mogą umieścić zerowej szerokości znak roffa (np. używając
odpowiednio `\&` lub '\&').
Wstawianie "<" i ">" w tłumaczeniach
Ponieważ znaki te są używane do oddzielania części objętych zmianą czcionki, nie można ich używać wprost.
Zamiast nich trzeba użyć E<lt> i E<gt> (jak w POD, po raz kolejny).
OPCJE AKCEPTOWANE PRZEZ MODUŁ
Opcje tego modułu:
debug
Uaktywnia debugowanie kilku wewnętrznych mechanizmów modułu. Informacje o tym, które części mogą być
debugowane, można znaleźć w źródłach.
verbose
Zwiększa gadatliwość.
groff_code
This option controls the behavior of the module when it encounter a .de, .ie or .if section. It can
take the following values:
fail
Jest to domyślna wartość. Działanie modułu zakończy się błędem, jeżeli zostanie napotkana sekcja
.de, .ie lub .if.
verbatim
Określa, że sekcje .de, .ie lub .if muszą być skopiowane bez zmian z oryginału do tłumaczonego
dokumentu.
translate
Wskazuje sekcje .de, .ie lub .if jako możliwe do przetłumaczenia. Opcja powinna być używana tylko
wtedy, gdy któraś z tych sekcji zawiera tekst do przetłumaczenia. W przeciwnym razie wskazane
byłoby użycie verbatim.
generated
This option specifies that the file was generated, and that po4a should not try to detect if the man
pages was generated from another format. This option is mandatory to use po4a on generated man
pages. Note that translating generated pages instead of sources ones is often more fragile, and thus
a bad idea.
mdoc
Ta opcja jest użyteczna tylko dla stron w formacie mdoc.
Wybiera dokładniejszą obsługę formatu mdoc, nakazuję po4a nietłumaczenie sekcji "NAME" (NAZWA).
Strony mdoc, zawierające przetłumaczoną sekcję "NAME", nie generują nagłówka ani stopki.
Zgodnie ze stroną podręcznika groff_mdoc, wymagane są sekcje NAME (NAZWA), SYNOPSIS (SKŁADNIA)oraz
DESCRIPTION (OPIS). Chociaż nie ma żadnych znanych problemów z przetłumaczonymi sekcjami SYNOPSIS
czy DESCRIPTION, to ich tłumaczenie można również pominąć za pomocą:
-o mdoc=NAME,SYNOPSIS,DESCRIPTION
Kwestię mdoc można także rozwiązać, używając załącznika podobnego do poniższego:
PO4A-HEADER:mode=before;position=^.Dd
.TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"
The following options specify the behavior of a user-defined macro (with a .de request), or of a
classical macro that is not supported by po4a. They take as argument a comma-separated list of macros.
For example:
-o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
Uwaga: jeśli po4a nie obsługuje danego makra, a uważasz, że jest to standardowe makro roff, proszę to
zgłosić zespołowi deweloperów po4a.
untranslated
untranslated oznacza, że to makro (i wszystkie jego argumenty) nie muszą być tłumaczone.
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ć tłumaczenie argumentów makra.
translate_each
translate_each powoduje, że argumenty będą także zaproponowane do tłumaczenia, z tym że każdy z nich
będzie przetłumaczony osobno.
no_wrap
Opcja przyjmuje jako argument rozdzieloną przecinkami listę par początek:koniec, gdzie początek i
koniec są poleceniami ograniczającymi początek i koniec sekcji, której tekst nie powinien być
ponownie zawijany.
Note: no test is done to ensure that an end command matches its begin command; any ending command
stop the no_wrap mode. If you have a begin (respectively end) macro that has no end (respectively
begin), you can specify an existing end (like fi) or begin (like nf) as a counterpart. These macros
(and their arguments) won't be translated.
inline
Opcja pozwala na podanie rozdzielonej przecinkami listy makr, które nie mogą dzielić bieżącego
akapitu. Komunikat do przetłumaczenia będzie wtedy zawierał foo <.bar baz qux> quux, gdzie bar jest
poleceniem, które powinno być włączone do pliku, a baz qux - jego argumentami.
unknown_macros
Ta opcja określa zachowanie po4a po napotkaniu nieznanego makra. Domyślnie po4 kończy działanie z
błędem i wyświetla stosowny komunikat. Możliwe są następujące wartości: failed (wartość domyślna),
untranslated, noarg, translate_joined, translate_each (patrz objaśnienia powyżej).
PISANIE STRON PODRĘCZNIKA ZGODNYCH Z PO4A::MAN
Moduł wciąż ma dużo ograniczeń i zawsze będzie miał, ponieważ nie jest rzeczywistym interpreterem nroffa.
Byłoby możliwe wykonanie rzeczywistego interpretera nroffa, aby umożliwić autorom używanie w swoich
stronach wszystkich istniejących makr i tworzenie nowych, ale nie chcieliśmy tego robić. Byłoby to zbyt
trudne, a przy tym raczej niepotrzebne. Uważamy, że jeżeli autorzy stron podręcznika chcą, żeby ich
strony były przetłumaczone, to muszą tak przekształcić strony, by uprościć pracę tłumaczy.
Tak więc, parser stron man zaimplementowany w po4a ma kilka znanych ograniczeń, których nie chcemy
poprawiać, i będących pułapkami, których powinieneś unikać, jeśli chcesz, żeby tłumacze opiekowali się
Twoją dokumentacją.
Nie programuj w nroffie
nroff jest kompletnym językiem programowania z definicjami makr, instrukcjami warunkowymi itd. Ponieważ
parser nie jest pełnowartościowym interpreterem nroffa, zwróci błąd podczas przetwarzania stron
zawierających te właściwości. (Na moim komputerze jest około 200 takich stron).
Używaj prostego zbioru makr
Wciąż istnieje kilka makr, których po4a nie obsługuje. Dzieje się tak dlatego, że nie znalazłem żadnej
dokumentacji tych makr. Poniżej jest lista nieobsługiwanych makr znalezionych na moim komputerze. Proszę
zauważyć, że ta lista nie jest pełna, ponieważ program kończy się, zwracając błąd, już po napotkaniu
pierwszego nieznanego makra. Jeśli masz jakieś informacje o niektórych z nich, z przyjemnością dopiszę
ich obsługę. Z powodu tych makr około 250 stron na moim komputerze nie jest dostępnych 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 niektóre części strony podręcznika nie powinny być tłumaczone, więc nie powinny być
przetwarzane przez po4a. Na przykład opcja może pobierać argument other oraz other może się także pojawić
jako ostatni element listu. Pierwsze other nie powinno być tłumaczone, a drugie - powinno.
W takim przypadku, aby po4a pominęło takie komunikaty, autor może użyć specjalnych konstrukcji groffa:
.if !'po4a'hide' .B other
(wymaga to podania opcji -o groff_code=verbatim)
Aby to zautomatyzować, można 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ę zbędny, ponieważ po4a nie przetwarza wnętrza definicji makra)
lub używając aliasu:
.als IR_untranslated IR
.IR_untranslated \-q ", " \-\-quiet
Wymaga to podania opcji -o untranslated=als,IR_untranslated.
Wniosek
Podsumowując tę sekcję, pamiętaj, żeby tworzyć proste strony podręcznika ekranowego i nie starać się być
zbyt pomysłowym. Roff pozwala na wiele rzeczy, które nie są obsługiwane przez parser. Na przykład: nie
rób bałaganu, używając \c do przerwania przetwarzania tekstu (jak to robi 40 stron podręcznika na moim
komputerze). Albo: argumenty makr umieszczaj w tej samej linii, co samo makro. Wiem, że nroff dopuszcza
rozdzielanie makr i ich argumentów, ale obsługiwanie tego zbytnio by skomplikowało parser.
Oczywiście inną możliwością jest użycie innego formatu, bardziej przyjaznego tłumaczom (jak POD używający
po4a::pod albo jednego z rodziny XML, np. SGML), ale nie jest to potrzebne dzięki po4a::man. Jeśli
formatem źródłowym Twojej dokumentacji jest POD lub XML, to byłoby mądre, aby przetłumaczyć źródłowy
format, a nie ten wygenerowany. W większości wypadków po4a::man rozpozna wygenerowane strony i wypisze
odpowiednie ostrzeżenie. A nawet odmówi przetwarzana stron wygenerowanych przez POD, ponieważ te strony
są perfekcyjnie obsługiwane przez po4a::pod i ponieważ ich odpowiednik nroffa generuje wiele nowych makr,
których nie chcę obsługiwać. Na moim komputerze 1432 spośród 4323 stron jest wygenerowanych z formatu POD
i będzie zignorowanych przez po4a::man.
W większości wypadków, po4a::man wykryje problem i odmówi przetwarzania strony, wypisując odpowiedni
komunikat. W kilku rzadkich wypadkach, program zakończy się bez żadnego ostrzeżenia, ale plik wynikowy
będzie niepoprawny. Takie sytuacje są nazywane "błędami";) Jeśli spotkasz się z taką sytuacją, proszę to
zgłosić wraz z odpowiednią poprawką, jeśli to możliwe…
STATUS MODUŁU
Modułu można używać z większością istniejących stron podręcznika.
Niektóre testy są regularnie uruchamiane na komputerach z Linuksem:
• odrzucono jedną trzecią stron ponieważ były one wygenerowane z innego formatu obsługiwanego przez
po4a (np. POD lub SGML).
• 10% pozostałych stron odrzucono z powodu błędu (np. nieobsługiwane makro groff).
• W końcu mniej niż 1% stron został zaakceptowany bez ostrzeżeń przez po4a, ale wystąpiły pewne poważne
problemy (np. usunięte lub dodane słowa).
• Inne strony są zazwyczaj obsługiwane bez różnic bardziej istotnych niż różnice w liczbie spacji czy
zawijaniu linii (problemy z czcionkami w mniej niż 10% przetworzonych stron).
ZOBACZ TAKŻE
Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
AUTORZY
Denis Barbier <barbier@linuxfr.org> Nicolas François <nicolas.francois@centraliens.net> Martin Quinson (mquinson#debian.org)
TŁUMACZENIE
Robert Luberda <robert@debian.org>
PRAWA AUTORSKIE I LICENCJA
Copyright © 2002-2008 SPI, Inc.
This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or
later (see the COPYING file).