Provided by: po4a_0.41-1_all bug

NAZWA

       Locale::Po4a::Man - konwersja stron podrcznika z/do plikow PO

OPIS

       Celem projektu po4a ("PO for anything") jest ulatwienie tlumacze (oraz,
       co ciekawsze, zarzdzania tlumaczeniami) przy uyciu narzdzi gettext w
       tych obszarach, gdzie nie byly uywane, jak na przyklad w obszarze
       dokumentacji.

       Locale::Po4a::Man jest modulem ulatwiajcym tlumaczenie dokumentacji w
       formacie nroff (jzyk stron podrcznika ekranowego) do innych jzykow
       [uywanych przez ludzi].

T/LUMACZENIE Z POMOC PO4A::MAN

       Modul bardzo si stara, aby ulatwi ycie tlumacza. Dlatego tekst
       prezentowany tlumaczowi nie jest doslown kopi oryginalnego tekstu
       strony podrcznika. W istocie, ukrywane s surowe czci formatu nroff, tak
       eby tlumacze nie zrobili w nich balaganu.

   Zawijanie tekstu
       Teksty niewcitych akapitow s automatycznie zawijane dla wygody
       tlumacza. Moe to prowadzi do niewielkich ronic w wygenerowanym pliku
       wyjciowym, poniewa reguly zawijania tekstu uywane przez groffa nie s
       jasne - na przyklad czasami groff zachowuje dwie spacje wystpujce po
       nawiasie.

       Tak czy owak, ronica bdzie dotyczyla tylko rozmieszczenia dodatkowych
       spacji w zawinitym tekcie akapitu.

   Okrelanie czcionki
       Pierwsza zmiana dotyczy specyfikacji zmian czcionek. W nroffie istnieje
       kilka sposobow okrelenia, e podane slowo powinno by napisane czcionk
       mal, wytluszczon lub kursyw. W tekcie do przetlumaczenia mona to zrobi
       tylko na jeden sposob, zapoyczony z formatu POD (formatu dokumentacji
       Perla):

       I<tekst> -- kursywa
           odpowiednik \fItekst\fP lub ".I tekst"

       B<tekst> -- tekst wytluszczony
           odpowiednik \fBtekst\fP lub ".B tekst"

       R<tekst> -- tekst zwykl czcionk
           odpowiednik \fRtekst\fP

       CW<tekst<gt> -- tekst o stalej szerokoci
           odpowiednik \f(CWtekst\fP lub ".CW tekst"

       Uwaga: CW nie jest dostpne dla wszystkich urzdze groffa. Uywanie go nie
       jest zalecane. Jest dostarczone dla wygody uytkownika.

   Automatyczna transliteracja znak'ow
       Po4a automatycznie zamienia niektore znaki, aby ulatwi tlumaczenia lub
       przegldanie tlumacze. Lista takich transliteracji:

       lczniki
           Lczniki (-) i znaki minusa (\-) w stronach podrcznika ekranowego s
           wszystkie transliterowane do zwyklych mylnikow (-) w pliku PO.
           Kiedy tlumaczenia s zapisywane w pliku wynikowym wszystkie mylniki
           s zamieniane na znaki minusa (\-).

           Tlumacze mog wymusi wstawienie lcznika, uywajc w swoich
           tlumaczeniach kodu "\[hy]" groffa.

       spacje nierozdzielajce
           Tlumacze mog uywa nierozdzielajcych spacji w swoich tlumaczeniach.
           Takie spacje nierozdzielajce (0xA0 w latin1) bd przetlumaczone jako
           spacje nierozdzielajce roff ("\ ").

       transliteracje cudzyslowow
           `` i '' s odpowiednio zamieniane na \*(lq i \*(rq.

           Aby unikn tych transliteracji, tlumacze mog umieci zerowej
           szerokoci znak roffa (np. uywajc odpowiednio `\&` lub '\&').

   Wstawianie "<" i ">" w t/lumaczeniach
       Poniewa znaki te s uywane do oddzielania czci objtych zmian czcionki,
       nie mona ich uywa wprost. Zamiast nich trzeba uy E<lt> i E<gt> (jak w
       POD, po raz kolejny).

OPCJE AKCEPTOWANE PRZEZ MODU/L

       Opcje tego modulu:

       debug
           Uaktywnia debugowanie kilku wewntrznych mechanizmow modulu.
           Informacje o tym, ktore czci mog by debugowane, mona znale w
           rodlach.

       verbose
           Zwiksza gadatliwo.

       groff_code
           Ta opcja pozwala na zmian zachowania modulu, kiedy napotka sekcj
           .de, .ie lub .if. Moe przyjmowa nastpujce wartoci:

           fail
               Jest to domylna warto. Dzialanie modulu zakoczy si bldem, jeeli
               zostanie napotkana sekcja .de, .ie lub .if.

           verbatim
               Okrela, e sekcje .de, .ie lub .if musz by skopiowane bez zmian
               z oryginalu do tlumaczonego dokumentu.

           translate
               Wskazuje sekcje .de, .ie lub .if jako moliwe do
               przetlumaczenia. Opcja powinna by uywana tylko wtedy, gdy ktora
               z tych sekcji zawiera tekst do przetlumaczenia. W przeciwnym
               razie wskazane byloby uycie verbatim.

       generated
           Ta opcja okrela, e plik zostal wygenerowany z innego formatu , a
           po4a nie powinno probowa tego wykrywa. Pozwala to na uywanie po4a
           wlanie na takich generowanych stronach podrcznika. Opcja nie
           pobiera adnych argumentow.

       mdoc
           Ta opcja jest uyteczna tylko dla stron w formacie mdoc.

           Wybiera dokladniejsz obslug formatu mdoc, nakazuj po4a
           nietlumaczenie sekcji "NAME" (NAZWA). Strony mdoc, zawierajce
           przetlumaczon sekcj "NAME", nie generuj naglowka ani stopki.

           Zgodnie ze stron podrcznika groff_mdoc, wymagane s sekcje NAME
           (NAZWA), SYNOPSIS (SKLADNIA)oraz DESCRIPTION (OPIS).  Chocia nie ma
           adnych znanych problemow z przetlumaczonymi sekcjami SYNOPSIS czy
           DESCRIPTION, to ich tlumaczenie mona rownie pomin za pomoc:
            -o mdoc=NAME,SYNOPSIS,DESCRIPTION

           Kwesti mdoc mona take rozwiza, uywajc zalcznika podobnego do
           poniszego:
            PO4A-HEADER:mode=before;position=^.Dd
            .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"

       Ponisze opcje pozwalaj okreli zachowanie nowego makra (zdefiniowanego
       poleceniem .de) albo makra nieobslugiwanego przez po4a. Przyjmuj jako
       argument rozdzielon przecinkami list makr. Na przyklad:

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

       Uwaga: jeli po4a nie obsluguje danego makra, a uwaasz, e jest to
       standardowe makro roff, prosz to zglosi zespolowi deweloperow po4a.

       untranslated
           untranslated oznacza, e to makro (i wszystkie jego argumenty) nie
           musz by tlumaczone.

       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 tlumaczenie
           argumentow makra.

       translate_each
           translate_each powoduje, e argumenty bd take zaproponowane do
           tlumaczenia, z tym e kady z nich bdzie przetlumaczony osobno.

       no_wrap
           Opcja przyjmuje jako argument rozdzielon przecinkami list par
           pocztek:koniec, gdzie pocztek i koniec s poleceniami ograniczajcymi
           pocztek i koniec sekcji, ktorej tekst nie powinien by ponownie
           zawijany.

           Uwaga: nie jest sprawdzane, czy polecenie end ma odpowiadajce
           polecenie begin; jakiekolwiek polecenie koczce zatrzyma tryb
           no_wrap. Jeeli istnieje makro begin (odpowiednio end) nie majce
           pasujcego end (odpowiednio begin), to mona poda istniejce end (jak
           fi) lub begin (jak nf) jako zamiennik. Makra te (i ich argumenty)
           nie bd tlumaczone.

       inline
           Opcja pozwala na podanie rozdzielonej przecinkami listy makr, ktore
           nie mog dzieli biecego akapitu. Komunikat do przetlumaczenia bdzie
           wtedy zawieral foo <.bar baz qux> quux, gdzie bar jest poleceniem,
           ktore powinno by wlczone do pliku, a baz qux - jego argumentami.

       unknown_macros
           Ta opcja okrela zachowanie po4a po napotkaniu nieznanego makra.
           Domylnie po4a wywietli ostrzeenie. Moliwe s nastpujce wartoci:
           failed (warto domylna), untranslated, noarg, translate_joined,
           translate_each.

PISANIE STRON PODRCZNIKA ZGODNYCH Z PO4A::MAN

       Modul wci ma duo ogranicze i zawsze bdzie mial, poniewa nie jest
       rzeczywistym interpreterem nroffa. Byloby moliwe wykonanie
       rzeczywistego interpretera nroffa, aby umoliwi autorom uywanie w swoich
       stronach wszystkich istniejcych makr i tworzenie nowych, ale nie
       chcielimy tego robi. Byloby to zbyt trudne, a przy tym raczej
       niepotrzebne. Uwaamy, e jeeli autorzy stron podrcznika chc, eby ich
       strony byly przetlumaczone, to musz tak przeksztalci strony, by uproci
       prac tlumaczy.

       Tak wic, parser stron man zaimplementowany w po4a ma kilka znanych
       ogranicze, ktorych nie chcemy poprawia, i bdcych pulapkami, ktorych
       powiniene unika, jeli chcesz, eby tlumacze opiekowali si Twoj
       dokumentacj.

   Nie programuj w nroffie
       nroff jest kompletnym jzykiem programowania z definicjami makr,
       instrukcjami warunkowymi itd. Poniewa parser nie jest pelnowartociowym
       interpreterem nroffa, zwroci bld podczas przetwarzania stron
       zawierajcych te wlaciwoci. (Na moim komputerze jest okolo 200 takich
       stron).

   Uywaj prostego zbioru makr
       Wci istnieje kilka makr, ktorych po4a nie obsluguje. Dzieje si tak
       dlatego, e nie znalazlem adnej dokumentacji tych makr. Poniej jest
       lista nieobslugiwanych makr znalezionych na moim komputerze. Prosz
       zauway, e ta lista nie jest pelna, poniewa program koczy si, zwracajc
       bld, ju po napotkaniu pierwszego nieznanego makra. Jeli masz jakie
       informacje o niektorych z nich, z przyjemnoci dopisz ich obslug. Z
       powodu tych makr okolo 250 stron na moim komputerze nie jest dostpnych
       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 niektore czci strony podrcznika nie powinny by
       tlumaczone, wic nie powinny by przetwarzane przez po4a. Na przyklad
       opcja moe pobiera argument other oraz other moe si take pojawi jako
       ostatni element listu. Pierwsze other nie powinno by tlumaczone, a
       drugie - powinno.

       W takim przypadku, aby po4a pominlo takie komunikaty, autor moe uy
       specjalnych konstrukcji groffa:

        .if !'po4a'hide' .B other

       (wymaga to podania opcji -o groff_code=verbatim)

       Aby to zautomatyzowa, mona 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 zbdny, poniewa po4a nie przetwarza wntrza
       definicji makra)

       lub uywajc aliasu:
        .als IR_untranslated IR

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

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

   Wniosek
       Podsumowujc t sekcj, pamitaj, eby tworzy proste strony podrcznika
       ekranowego i nie stara si by zbyt pomyslowym. Roff pozwala na wiele
       rzeczy, ktore nie s obslugiwane przez parser. Na przyklad: nie rob
       balaganu, uywajc \c do przerwania przetwarzania tekstu (jak to robi 40
       stron podrcznika na moim komputerze). Albo: argumenty makr umieszczaj w
       tej samej linii, co samo makro. Wiem, e nroff dopuszcza rozdzielanie
       makr i ich argumentow, ale obslugiwanie tego zbytnio by skomplikowalo
       parser.

       Oczywicie inn moliwoci jest uycie innego formatu, bardziej przyjaznego
       tlumaczom (jak POD uywajcy po4a::pod albo jednego z rodziny XML, np.
       SGML), ale nie jest to potrzebne dziki po4a::man. Jeli formatem
       rodlowym Twojej dokumentacji jest POD lub XML, to byloby mdre, aby
       przetlumaczy rodlowy format, a nie ten wygenerowany. W wikszoci
       wypadkow po4a::man rozpozna wygenerowane strony i wypisze odpowiednie
       ostrzeenie. A nawet odmowi przetwarzana stron wygenerowanych przez POD,
       poniewa te strony s perfekcyjnie obslugiwane przez po4a::pod i poniewa
       ich odpowiednik nroffa generuje wiele nowych makr, ktorych nie chc
       obslugiwa. Na moim komputerze 1432 sporod 4323 stron jest
       wygenerowanych z formatu POD i bdzie zignorowanych przez po4a::man.

       W wikszoci wypadkow, po4a::man wykryje problem i odmowi przetwarzania
       strony, wypisujc odpowiedni komunikat. W kilku rzadkich wypadkach,
       program zakoczy si bez adnego ostrzeenia, ale plik wynikowy bdzie
       niepoprawny. Takie sytuacje s nazywane "bldami";) Jeli spotkasz si z
       tak sytuacj, prosz to zglosi wraz z odpowiedni poprawk, jeli to
       moliwe...

STATUS MODU/LU

       Modulu mona uywa z wikszoci istniejcych stron podrcznika.

       Niektore testy s regularnie uruchamiane na komputerach z Linuksem:

       o   odrzucono jedn trzeci stron poniewa byly one wygenerowane z innego
           formatu obslugiwanego przez po4a (np. POD lub SGML).

       o   10% pozostalych stron odrzucono z powodu bldu (np. nieobslugiwane
           makro groff).

       o   W kocu mniej ni 1% stron zostal zaakceptowany bez ostrzee przez
           po4a, ale wystpily pewne powane problemy (np. usunite lub dodane
           slowa).

       o   Inne strony s zazwyczaj obslugiwane bez ronic bardziej istotnych ni
           ronice w liczbie spacji czy zawijaniu linii (problemy z czcionkami
           w mniej ni 10% przetworzonych stron).

ZOBACZ TAKE

       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)

PRAWA AUTORSKIE I LICENCJA

       Copyright 2002-2008 by SPI, inc.

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