blib::man::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 ich tXumaczeniach. Takie spacje nierozdzielajXce (0xA0) 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.

untranslated
noarg
translate_joined
translate_each
    Te 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 oznacza, Xe to makro (i wszystkie jego argumenty) nie muszX byae tXumaczone.

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

    translate_joined oznacza, Xe po4a musi zaproponowaae tXumaczenie argumentow makra.

    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 byae dzielone w bieXXcym akapicie. Komunikat do przetXumaczenia bedzie wtedy zawieraX foo <.bar baz qux> quux, gdzie foo jest poleceniem, ktore powinno byae wXXczone do pliku.

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 uXywaj zbioru makr mdoc
Po4a w ogole nie obsXuguje i nie bedzie obsXugiwaae zbioru makr opisanego w mdoc(7) (i szeroko uXywanego w BSD). ObsXuga tego wymagaXaby napisania zupeXnie nowego parsera, a nie mam na to ochoty. Na moim komputerze wXrod 4323 stron podrecznika ekranowego sX tylko 63 strony oparte na mdoc. Jednak jeXli ktoX zaimplementuje wsparcie dla mdoc, chetnie je doXXcze do po4a.

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

  Unikaj wXXczania plikow, jeXli jest to moXliwe
Makro groff-a ".so" uXywane do wXXczenia innego pliku do bieXXcego jest obsXugiwane, ale z mojego wXasnego doXwiadczenia wynika, Xe cieXej jest manipulowaae takX stronX podrecznika, poniewaX wszystkie pliki powinny byae zainstalowane w odpowiedniej lokalizacji, tak Xeby moXna byXo zobaczyae wynik (np. w jakiX sposob psuje to opcje "-l" programu man).

  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
MyXle, Xe ten moduX wciXX jest w fazie beta, ale moXe byae uXyty dla wiekszoXci istniejXcych stron podrecznika. PrzeprowadziXem pare testow, przetwarzajXc wszystkie pliki na moim komputerze i porownujXc oryginalne wersje z tymi przetworzonymi przez po4a. Wyniki sX nastepujXce:

 # stron             : 5060

 Zignorowanych stron : 1742 (34%)
 bXedow parsera      :  530 (12% z wszystkich; 18% z nieignorowanych)

 dziaXa doskonale    : 1947 (39% z wszystkich; 59% z nieignorowanych; 70% z przetworzonych)
 zmiana zawijania    :  409 ( 8% z wszystkich; 12% z nieignorowanych; 15% z przetworzonych)
 zmiana zawijania
 i/lub czcionki      :  364 ( 7% z wszystkich; 11% z nieignorowanych; 13% z przetworzonych)

 niewykryte problemy :   68 ( 1% z wszystkich; 2% z nieignorowanych; 2% z przetworzonych)

Strony ignorowane dlatego sX ignorowane, Xe nie sX plikami XrodXowymi. Na przykXad sX wygenerowane z formatu POD lub SGML. W takim wypadku zamiast tXumaczyae wygenerowanX strone podrecznika, naleXy przetXumaczyae [rzeczywisty] plik XrodXowy, uXywajXc odpowiedniego moduXu po4a.

Parser kon~czy sie bXedem na stronach opartych na formacie mdoc(7), stronach zawierajXcych instrukcje warunkowe z .if, definiujXcych nowe makra za pomocX .de, uXywajXcych niestandardowych czcionek i, bardziej ogolnie, nie stosujXcych sie do rad zawartych w poprzedniej sekcji.

Strony z niewykrytymi problemami sX przetwarzane przez po4a::man bez Xadnych ostrzeXen~, jednak wygenerowany plik roXni sie od oryginaXu (niektore komunikaty sX obecne w oryginalnej stronie, ale nie w tej wygenerowanej przez po4a i na odwrot). Wszystkie takie przypadki sX bXedami, ale wiekszoXae z nich wynika z problemow wystepujXcych w oryginalnej stronie.

WiekszoXae stron w kategorii "zmienia zawijanie tekstu i/lub czcionke" ma zmienione tylko zawijanie tekstu (byXo to jednak zbyt trudne do automatycznego okreXlenia) albo ma bardziej powaXnX zmiane formatowania (np. ktore znaki sX kursywX, a ktore sX pogrubione, itp.)

Wydaje sie, Xe skoro ignorowane strony moXna przetXumaczyae uXywajXc po4a::pod i skoro zmiany w zawijaniu teksu sX w wiekszoXci wypadkow akceptowalne, obecna wersja po4a moXe przetXumaczyae 80% stron podrecznika obecnych na moim komputerze. Ponadto, wiekszoXae nieprzetXumaczalnych stron moXe byae Xatwo poprawiona stosujXc sztuczki podane powyXej. Czy to nie faaaajne?

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 by SPI, inc.

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