Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::Man.3pm

NAZWA

Locale::Po4a::Man - Konwersja stron podrXcznika z/do plikow PO

OPIS

Celem projektu po4a (``po for anything'') jest uXatwienie tXumaczeX (oraz, co ciekawsze, zarzXdzania tXumaczeniami) przy uXyciu narzXdzi gettext w tych obszarach, gdzie nie byXy uXywane, jak na przykXad w obszarze dokumentacji.

Locale::Po4a::Man jest moduXem uXatwiajXcym tXumaczenie dokumentacji w formacie nroff (jXzyk stron podrXcznika ekranowego) do innych jXzykow [uXywanych przez ludzi].

TXUMACZENIE Z POMOCX PO4A::MAN

ModuX bardzo siX stara, aby uXatwiX Xycie tXumacza. Dlatego tekst prezentowany tXumaczowi nie jest dosXownX kopiX oryginalnego tekstu strony podrXcznika. W istocie, ukrywane sX surowe czXXci formatu nroff, tak Xeby tXumacze nie zrobili w nich baXaganu.

Zawijanie tekstu

Teksty niewciXtych akapitow sX automatycznie zawijane dla wygody tXumacza. MoXe to prowadziX do niewielkich roXnic w wygenerowanym pliku wyjXciowym, poniewaX reguXy zawijania tekstu uXywane przez groffa nie sX jasne. Na przykXad dwie spacje po nawiasie sX czasem zachowywane, podczas gdy reguXy typografii [angielskiej - przyp. tXum.] wymagajX zachowania dwoch spacji tylko po znaku kropki (no dobra, angielski nie jest moim natywnym jXzykiem, wiXc nie jestem tego pewien. JeXli masz jakieX inne informacjX, to prosimy o ich przekazanie).

Tak czy owak, roXnica bXdzie dotyczyXa tylko rozmieszczenia dodatkowych spacji w zawiniXtym tekXcie akapitu.

OkreXlanie czcionki

Pierwsza zmiana dotyczy specyfikacji zmian czcionek. W nroffie istnieje kilka sposobow okreXlenia, Xe podane sXowo powinno byX napisane czcionkX maXX, wytXuszczonX lub kursywX. W tekXcie do przetXumaczenia moXna to zrobiX tylko na jeden sposob, zapoXyczony z formatu pod (formatu dokumentacji Perla):

I<tekst> --- kursywa

odpowiednik \fItekst\fP lub ``.I tekst''

B<tekst> --- tekst wytXuszczony

odpowiednik \fBtekst\fP lub ``.B tekst''

R<tekst> --- tekst zwykXX czcionkX

odpowiednik \fRtekst\fP

CW<tekst<gt> --- tekst o staXej szerokoXci

odpowiednik \f(CWtekst\fP lub ``.CW tekst''

Uwaga: CW nie jest dostXpne dla wszystkich urzXdzeX groffa. UXywanie go nie jest zalecane. Jest dostarczone dla wygody uXytkownika.

Automatyczna transliteracja znakow

Po4a automatycznie zamienia niektore znaki, aby uXatwiX tXumaczenia lub przeglXdanie tXumaczeX. Lista takich transliteracji:

XXczniki

XXczniki (-) i znaki minusa (\-) w stronach podrXcznika ekranowego sX wszystkie transliterowane do zwykXych myXlnikow (-) w pliku PO. Kiedy tXumaczenia sX zapisywane w pliku wynikowym wszystkie myXlniki sX zamieniane na znaki minusa (\-).

TXumacze mogX wymusiX wstawienie XXcznika, uXywajXc w swoich tXumaczeniach kodu ``\[hy]'' groffa.

spacje nierozdzielajXce

TXumacze mogX uXywaX nierozdzielajXcych spacji w swoich tXumaczeniach. Takie spacje nierozdzielajXce (0xA0 w latin1) bXdX przetXumaczone jako spacje nierozdzielajXce roff (``\ '').

transliteracje cudzysXowow

`` i '' sX odpowiednio zamieniane na \*(lq i \*(rq.

Aby uniknXX tych transliteracji, tXumacze mogX umieXciX zerowej szerokoXci znak roffa (np. uXywajXc odpowiednio `\&` lub '\&').

Wstawianie "<" i ">" w tXumaczeniach

Wstawianie ``<'' i ``>'' w tXumaczeniach

PoniewaX znaki te sX uXywane do oddzielania czXXci objXtych zmianX czcionki, nie moXna ich uXywaX wprost. Zamiast nich trzeba uXyX E<lt> i E<gt> (jak w pod, po raz kolejny).

OPCJE AKCEPTOWANE PRZEZ TEN MODUX

Opcje tego moduXu:

debug

Uaktywnia debugowanie kilku wewnXtrznych mechanizmow moduXu. Informacje o tym, ktore czXXci mogX byX debugowane, moXna znaleXX w XrodXach.

verbose

ZwiXksza gadatliwoXX.

groff_code

Ta opcja pozwala na zmianX zachowania moduXu, kiedy napotka sekcjX .de, .ie lub .if. MoXe przyjmowaX nastXpujXce wartoXci:

fail

Jest to domyXlna wartoXX. DziaXanie moduXu zakoXczy siX bXXdem, jeXeli zostanie napotkana sekcja .de, .ie lub .if.

verbatim

OkreXla, Xe sekcje .de, .ie lub .if muszX byX skopiowane bez zmian z oryginaXu do tXumaczonego dokumentu.

translate

Wskazuje sekcje .de, .ie lub .if jako moXliwe do przetXumaczenia. Opcja powinna byX uXywana tylko wtedy, gdy ktoraX z tych sekcji zawiera tekst do przetXumaczenia. W przeciwnym razie wskazane byXoby uXycie verbatim.

generated

Ta opcja okreXla, Xe plik zostaX wygenerowany z innego formatu , a po4a nie powinno probowaX tego wykrywaX. Pozwala to na uXywanie po4a wXaXnie na takich generowanych stronach podrXcznika. Opcja nie pobiera Xadnych argumentow.

mdoc

Ta opcja jest uXyteczna tylko dla stron w formacie mdoc.

Wybiera dokXadniejszX obsXugX formatu mdoc, nakazujX po4a nietXumaczenie sekcji ``NAME'' (NAZWA). Strony mdoc, zawierajXce przetXumaczonX sekcjX ``NAME'', nie generujX nagXowka ani stopki.

Zgodnie ze stronX podrXcznika groff_mdoc, wymagane sX sekcje NAME (NAZWA), SYNOPSIS (SKXADNIA)oraz DESCRIPTION (OPIS). ChociaX nie ma Xadnych znanych problemow z przetXumaczonymi sekcjami SYNOPSIS czy DESCRIPTION, to ich tXumaczenie moXna rownieX pominXX za pomocX:
 -o mdoc=NAME,SYNOPSIS,DESCRIPTION

KwestiX mdoc moXna takXe rozwiXzaX, uXywajXc zaXXcznika podobnego do poniXszego:
 PO4A-HEADER:mode=before;position=^.Dd
 .TH DOCUMENT_TITLE 1 ``Month day, year'' OS ``Section Name''

PoniXsze opcje pozwalajX okreXliX zachowanie nowego makra (zdefiniowanego poleceniem .de) albo makra nieobsXugiwanego przez po4a. PrzyjmujX jako argument rozdzielonX przecinkami listX makr. Na przykXad:

  -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
 
 

Uwaga: jeXli po4a nie obsXuguje danego makra, a uwaXasz, Xe jest to standardowe makro roff, proszX to zgXosiX zespoXowi deweloperow po4a.

untranslated

untranslated oznacza, Xe to makro (i wszystkie jego argumenty) nie muszX byX tXumaczone.

noarg

noarg jest jak untranslated, poza tym, Xe po4a sprawdzi, Xe do tego makra nie dodano Xadnego argumentu.

translate_joined

translate_joined oznacza, Xe po4a musi zaproponowaX tXumaczenie argumentow makra.

translate_each

translate_each powoduje, Xe argumenty bXdX takXe zaproponowane do tXumaczenia, z tym Xe kaXdy z nich bXdzie przetXumaczony osobno.

no_wrap

Opcja przyjmuje jako argument rozdzielonX przecinkami listX par poczXtek:koniec, gdzie poczXtek i koniec sX poleceniami ograniczajXcymi poczXtek i koniec sekcji, ktorej tekst nie powinien byX ponownie zawijany.

Uwaga: nie jest sprawdzane, czy polecenie end ma odpowiadajXce polecenie begin; jakiekolwiek polecenie koXczXce zatrzyma tryb no_wrap. JeXeli istnieje makro begin (odpowiednio end) nie majXce pasujXcego end (odpowiednio begin), to moXna podaX istniejXce end (jak fi) lub begin (jak nf) jako zamiennik. Makra te (i ich argumenty) nie bXdX tXumaczone.

inline

Opcja pozwala na podanie rozdzielonej przecinkami listy makr, ktore nie mogX dzieliX bieXXcego akapitu. Komunikat do przetXumaczenia bXdzie wtedy zawieraX foo <.bar baz qux> quux, gdzie bar jest poleceniem, ktore powinno byX wXXczone do pliku, a baz qux - jego argumentami.

unknown_macros

Ta opcja okreXla zachowanie po4a po napotkaniu nieznanego makra. DomyXlnie po4a wyXwietli ostrzeXenie. MoXliwe sX nastXpujXce wartoXci: failed (wartoXX domyXlna), untranslated, noarg, translate_joined, translate_each.

PISANIE STRON PODRXCZNIKA ZGODNYCH Z PO4A::MAN

ModuX wciXX ma duXo ograniczeX i zawsze bXdzie miaX, poniewaX nie jest rzeczywistym interpreterem nroffa. ByXoby moXliwe wykonanie rzeczywistego interpretera nroffa, aby umoXliwiX autorom uXywanie w swoich stronach wszystkich istniejXcych makr i tworzenie nowych, ale nie chcieliXmy tego robiX. ByXoby to zbyt trudne, a przy tym raczej niepotrzebne. UwaXamy, Xe jeXeli autorzy stron podrXcznika chcX, Xeby ich strony byXy przetXumaczone, to muszX tak przeksztaXciX strony, by uproXciX pracX tXumaczy.

Tak wiXc, parser stron man zaimplementowany w po4a ma kilka znanych ograniczeX, ktorych nie chcemy poprawiaX, i bXdXcych puXapkami, ktorych powinieneX unikaX, jeXli chcesz, Xeby tXumacze opiekowali siX TwojX dokumentacjX.

Nie programuj w nroffie

nroff jest kompletnym jXzykiem programowania z definicjami makr, instrukcjami warunkowymi itd. PoniewaX parser nie jest peXnowartoXciowym interpreterem nroffa, zwroci bXXd podczas przetwarzania stron zawierajXcych te wXaXciwoXci. (Na moim komputerze jest okoXo 200 takich stron).

UXywaj prostego zbioru makr

WciXX istnieje kilka makr, ktorych po4a nie obsXuguje. Dzieje siX tak dlatego, Xe nie znalazXem Xadnej dokumentacji tych makr. PoniXej jest lista nieobsXugiwanych makr znalezionych na moim komputerze. ProszX zauwaXyX, Xe ta lista nie jest peXna, poniewaX program koXczy siX, zwracajXc bXXd, juX po napotkaniu pierwszego nieznanego makra. JeXli masz jakieX informacje o niektorych z nich, z przyjemnoXciX dopiszX ich obsXugX. Z powodu tych makr okoXo 250 stron na moim komputerze nie jest dostXpnych 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, Xe niektore czXXci strony podrXcznika nie powinny byX tXumaczone, wiXc nie powinny byX przetwarzane przez po4a. Na przykXad opcja moXe pobieraX argument other oraz other moXe siX takXe pojawiX jako ostatni element listu. Pierwsze other nie powinno byX tXumaczone, a drugie - powinno.

W takim przypadku, aby po4a pominXXo takie komunikaty, autor moXe uXyX specjalnych konstrukcji groffa:

  .if !'po4a'hide' .B other
 
 

(wymaga to podania opcji -o groff_code=verbatim)

Aby to zautomatyzowaX, moXna zdefiniowaX 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 siX zbXdny, poniewaX po4a nie przetwarza wnXtrza definicji makra)

lub uXywajXc aliasu:
 .als IR_untranslated IR

  .IR_untranslated \-q ", " \-\-quiet
 
 

(wymaga to podania opcji -o untranslated=als,IR_untranslated)

Wniosek

PodsumowujXc tX sekcjX, pamiXtaj, Xeby tworzyX proste strony podrXcznika ekranowego i nie staraX siX byX zbyt pomysXowym. Roff pozwala na wiele rzeczy, ktore nie sX obsXugiwane przez parser. Na przykXad: nie rob baXaganu, uXywajXc \c do przerwania przetwarzania tekstu (jak to robi 40 stron podrXcznika na moim komputerze). Albo: argumenty makr umieszczaj w tej samej linii, co samo makro. Wiem, Xe nroff dopuszcza rozdzielanie makr i ich argumentow, ale obsXugiwanie tego zbytnio by skomplikowaXo parser.

OczywiXcie innX moXliwoXciX jest uXycie innego formatu, bardziej przyjaznego tXumaczom (jak pod uXywajXcy po4a::pod albo jednego z rodziny xml, np. sgml), ale nie jest to potrzebne dziXki po4a::man. JeXli formatem XrodXowym Twojej dokumentacji jest pod lub xml, to byXoby mXdre, aby przetXumaczyX XrodXowy format, a nie ten wygenerowany. W wiXkszoXci wypadkow po4a::man rozpozna wygenerowane strony i wypisze odpowiednie ostrzeXenie. A nawet odmowi przetwarzana stron wygenerowanych przez Pod, poniewaX te strony sX perfekcyjnie obsXugiwane przez po4a::pod i poniewaX ich odpowiednik nroffa generuje wiele nowych makr, ktorych nie chcX obsXugiwaX. Na moim komputerze 1432 spoXrod 4323 stron jest wygenerowanych z formatu pod i bXdzie zignorowanych przez po4a::man.

W wiXkszoXci wypadkow, po4a::man wykryje problem i odmowi przetwarzania strony, wypisujXc odpowiedni komunikat. W kilku rzadkich wypadkach, program zakoXczy siX bez Xadnego ostrzeXenia, ale plik wynikowy bXdzie niepoprawny. Takie sytuacje sX nazywane ``bXXdami'';) JeXli spotkasz siX z takX sytuacjX, proszX to zgXosiX wraz z odpowiedniX poprawkX, jeXli to moXliwe...

STATUS MODUXU

Tego moduXu moXna uXywaX z wiXkszoXciX istniejXcych stron podrXcznika.

Niektore testy sX regularnie uruchamiane na komputerach z Linuksem:

•

odrzucono jednX trzeciX stron poniewaX byXy one wygenerowane z innego formatu obsXugiwanego przez po4a (np. pod lub SGML).

•

10% pozostaXych stron odrzucono z powodu bXXdu (np. nieobsXugiwane makro groff).

•

W koXcu mniej niX 1% stron zostaX zaakceptowany bez ostrzeXeX przez po4a, ale wystXpiXy pewne powaXne problemy (np. usuniXte lub dodane sXowa).

•

Inne strony sX zazwyczaj obsXugiwane bez roXnic bardziej istotnych niX roXnice w liczbie spacji czy zawijaniu linii (problemy z czcionkami w mniej niX 10% przetworzonych stron).

ZOBACZ TAKXE

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)
 
 

TXUMACZENIE

  Robert Luberda <robert@debian.org>
 
 

PRAWA AUTORSKIE I LICENCJA

Copyright 2002-2008 by SPI, inc.

Program jest wolnym oprogramowaniem; moXna go redystrybuowaX i/lub modyfikowaX zgodnie z warunkami licencji GPL (patrz plik COPYING).