Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::Man.3pm

NAZWA

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

OPIS

Celem projektu po4a (``po for anything'') jest uXatwienie tXumaczen~ (oraz, co ciekawsze, zarzXdzania tXumaczeniami) przy uXyciu narzedzi 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 (jezyk stron podrecznika ekranowego) do innych jezykow [uXywanych przez ludzi].

TXUMACZENIE Z POMOCX PO4A::MAN

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

Zawijanie tekstu

Teksty niewcietych akapitow sX automatycznie zawijane dla wygody tXumacza. MoXe to prowadziae 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 jezykiem, wiec nie jestem tego pewien. JeXli masz jakieX inne informacje, to prosimy o ich przekazanie).

Tak czy owak, roXnica bedzie dotyczyXa tylko rozmieszczenia dodatkowych spacji w zawinietym tekXcie akapitu.

OkreXlanie czcionki

Pierwsza zmiana dotyczy specyfikacji zmian czcionek. W nroffie istnieje kilka sposobow okreXlenia, Xe podane sXowo powinno byae napisane czcionkX maXX, wytXuszczonX lub kursywX. W tekXcie do przetXumaczenia moXna to zrobiae 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 dostepne dla wszystkich urzXdzen~ groffa. UXywanie go nie jest zalecane. Jest dostarczone dla wygody uXytkownika.

Automatyczna transliteracja znakow

Po4a automatycznie zamienia niektore znaki, aby uXatwiae tXumaczenia lub przeglXdanie tXumaczen~. Lista takich transliteracji:

XXczniki

XXczniki (-) i znaki minusa (\-) w stronach podrecznika 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 wymusiae wstawienie XXcznika, uXywajXc w swoich tXumaczeniach kodu ``\[hy]'' groffa.

spacje nierozdzielajXce

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

transliteracje cudzysXowow

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

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

Wstawianie '<' i '>' w tXumaczeniach

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

OPCJE AKCEPTOWANE PRZEZ TEN MODUX

Opcje tego moduXu:

debug

Uaktywnia debugowanie kilku wewnetrznych mechanizmow moduXu. Informacje o tym, ktore czeXci mogX byae debugowane, moXna znaleXae w XrodXach.

verbose

Zwieksza gadatliwoXae.

groff_code

Ta opcja pozwala na zmiane zachowania moduXu, kiedy napotka sekcje .de, .ie lub .if. MoXe przyjmowaae nastepujXce wartoXci:

fail

Jest to domyXlna wartoXae. DziaXanie moduXu zakon~czy sie bXedem, jeXeli zostanie napotkana sekcja .de, .ie lub .if.

verbatim

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

translate

Wskazuje sekcje .de, .ie lub .if jako moXliwe do przetXumaczenia. Opcja powinna byae 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 probowaae tego wykrywaae. Pozwala to na uXywanie po4a wXaXnie na takich generowanych stronach podrecznika. Opcja nie pobiera Xadnych argumentow.

mdoc

Ta opcja jest uXyteczna tylko dla stron w formacie mdoc.

Wybiera dokXadniejszX obsXuge formatu mdoc, nakazuje po4a nietXumaczenie sekcji ``NAME'' (NAZWA). Strony mdoc, zawierajXce przetXumaczonX sekcje ``NAME'', nie generujX nagXowka ani stopki.

Zgodnie ze stronX podrecznika 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 pominXae za pomocX:
 -o mdoc=NAME,SYNOPSIS,DESCRIPTION

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

PoniXsze opcje pozwalajX okreXliae zachowanie nowego makra (zdefiniowanego poleceniem .de) albo makra nieobsXugiwanego przez po4a. PrzyjmujX jako argument rozdzielonX przecinkami liste 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, prosze to zgXosiae zespoXowi deweloperow po4a.

untranslated

untranslated oznacza, Xe to makro (i wszystkie jego argumenty) nie muszX byae 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 zaproponowaae tXumaczenie argumentow makra.

translate_each

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

no_wrap

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

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

inline

Opcja pozwala na podanie rozdzielonej przecinkami listy makr, ktore nie mogX dzieliae bieXXcego akapitu. Komunikat do przetXumaczenia bedzie wtedy zawieraX foo <.bar baz qux> quux, gdzie bar jest poleceniem, ktore powinno byae 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 nastepujXce wartoXci: failed (wartoXae domyXlna), untranslated, noarg, translate_joined, translate_each.

PISANIE STRON PODRECZNIKA ZGODNYCH Z PO4A::MAN

ModuX wciXX ma duXo ograniczen~ i zawsze bedzie miaX, poniewaX nie jest rzeczywistym interpreterem nroffa. ByXoby moXliwe wykonanie rzeczywistego interpretera nroffa, aby umoXliwiae autorom uXywanie w swoich stronach wszystkich istniejXcych makr i tworzenie nowych, ale nie chcieliXmy tego robiae. ByXoby to zbyt trudne, a przy tym raczej niepotrzebne. UwaXamy, Xe jeXeli autorzy stron podrecznika chcX, Xeby ich strony byXy przetXumaczone, to muszX tak przeksztaXciae strony, by uproXciae prace tXumaczy.

Tak wiec, parser stron man zaimplementowany w po4a ma kilka znanych ograniczen~, ktorych nie chcemy poprawiaae, i bedXcych puXapkami, ktorych powinieneX unikaae, jeXli chcesz, Xeby tXumacze opiekowali sie TwojX dokumentacjX.

Nie programuj w nroffie

nroff jest kompletnym jezykiem 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 sie tak dlatego, Xe nie znalazXem Xadnej dokumentacji tych makr. PoniXej jest lista nieobsXugiwanych makr znalezionych na moim komputerze. Prosze zauwaXyae, Xe ta lista nie jest peXna, poniewaX program kon~czy sie, zwracajXc bXXd, juX po napotkaniu pierwszego nieznanego makra. JeXli masz jakieX informacje o niektorych z nich, z przyjemnoXciX dopisze ich obsXuge. Z powodu tych makr okoXo 250 stron na moim komputerze nie jest dostepnych 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
 
 

Wniosek

PodsumowujXc te sekcje, pamietaj, Xeby tworzyae proste strony podrecznika ekranowego i nie staraae sie byae 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 podrecznika 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 dzieki po4a::man. JeXli formatem XrodXowym Twojej dokumentacji jest pod lub xml, to byXoby mXdre, aby przetXumaczyae XrodXowy format, a nie ten wygenerowany. W wiekszoXci 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 chce obsXugiwaae. Na moim komputerze 1432 spoXrod 4323 stron jest wygenerowanych z formatu pod i bedzie zignorowanych przez po4a::man.

W wiekszoXci wypadkow, po4a::man wykryje problem i odmowi przetwarzania strony, wypisujXc odpowiedni komunikat. W kilku rzadkich wypadkach, program zakon~czy sie bez Xadnego ostrzeXenia, ale plik wynikowy bedzie niepoprawny. Takie sytuacje sX nazywane ``bXedami'';) JeXli spotkasz sie z takX sytuacjX, prosze to zgXosiae wraz z odpowiedniX poprawkX, jeXli to moXliwe...

STATUS MODUXU

Tego moduXu moXna uXywaae z wiekszoXciX istniejXcych stron podrecznika.

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 bXedu (np. nieobsXugiwane makro groff).

•

W kon~cu mniej niX 1% stron zostaX zaakceptowany bez ostrzeXen~ przez po4a, ale wystXpiXy pewne powaXne problemy (np. usuniete 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, 2003, 2004, 2005, 2006 by SPI, inc.

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