po4av0.55

Locale::Po4a::Man

Section: Narzędzia po4a (3pm)
Updated: 2018-12-10
Index Return to Main Contents
 

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
Ta opcja pozwala na zmianę zachowania modułu, kiedy napotka sekcję .de, .ie lub .if. Może przyjmować następujące wartości:
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
Ta opcja określa, że plik został wygenerowany z innego formatu , a po4a nie powinno próbować tego wykrywać. Pozwala to na używanie po4a właśnie na takich generowanych stronach podręcznika. Opcja nie pobiera żadnych argumentów.
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''

Poniższe opcje pozwalają określić zachowanie nowego makra (zdefiniowanego poleceniem .de) albo makra nieobsługiwanego przez po4a. Przyjmują jako argument rozdzieloną przecinkami listę makr. Na przykład:

 -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.

Uwaga: nie jest sprawdzane, czy polecenie end ma odpowiadające polecenie begin; jakiekolwiek polecenie kończące zatrzyma tryb no_wrap. Jeżeli istnieje makro begin (odpowiednio end) nie mające pasującego end (odpowiednio begin), to można podać istniejące end (jak fi) lub begin (jak nf) jako zamiennik. Makra te (i ich argumenty) nie będą tłumaczone.

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.

Of course, another possibility is to use another format, more translator friendly (like POD using po4a::pod, or one of the XML family like SGML), but thanks to po4a::man it isn't needed anymore. That being said, if the source format of your documentation is POD, or XML, it may be clever to translate the source format and not this generated one. In most cases, po4a::man will detect generated pages and issue a warning. It will even refuse to process POD generated pages, because those pages are perfectly handled by po4a::pod, and because their nroff counterpart defines a lot of new macros I didn't want to write support for. On my box, 1432 of the 4323 pages are generated from POD and will be ignored by po4a::man.

In most cases, po4a::man will detect the problem and refuse to process the page, issuing an adapted message. In some rare cases, the program will complete without warning, but the output will be wrong. Such cases are called ``bugs'' ;) If you encounter such case, be sure to report this, along with a fix when possible…  

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.

Program jest wolnym oprogramowaniem; można go redystrybuować i/lub modyfikować zgodnie z warunkami licencji GPL (patrz plik COPYING).


 

Index

NAZWA
OPIS
TŁUMACZENIE Z POMOCĄ PO4A::MAN
Zawijanie tekstu
Określanie czcionki
Automatyczna transliteracja znaków
Wstawianie < i > w tłumaczeniach
OPCJE AKCEPTOWANE PRZEZ MODUŁ
PISANIE STRON PODRĘCZNIKA ZGODNYCH Z PO4A::MAN
Nie programuj w nroffie
Używaj prostego zbioru makr
Ukrywanie tekstu przez po4a
Wniosek
STATUS MODUŁU
ZOBACZ TAKŻE
AUTORZY
TŁUMACZENIE
PRAWA AUTORSKIE I LICENCJA

This document was created by using the manual pages.
Time: 11:07:08 GMT, December 10, 2018
català Deutsch English español français Italiano 日本語 Bokmål polski Português Português (Brasil) Русский український 简体中文 (how to set the default document language)