Provided by: po4a_0.33.3-1_all bug

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 dwie spacje po nawiasie są czasem zachowywane,
       podczas gdy reguły typografii [angielskiej - przyp. tłum.] wymagają
       zachowania dwóch spacji tylko po znaku kropki (no dobra, angielski nie
       jest moim natywnym językiem, więc nie jestem tego pewien. Jeśli masz
       jakieś inne informację, to prosimy o ich przekazanie).

       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 TEN 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
           pocztek:koniec, gdzie pocztek 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 po4a wyświetli ostrzeżenie. Możliwe są następujące
           wartości: failed (wartość domyślna), untranslated, noarg,
           translate_joined, translate_each.

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.

       Oczywiście inną możliwością jest użycie innego formatu, bardziej
       przyjaznego tłumaczom (jak pod używający po4a::pod albo jednego z
       rodziny xml, np. sgml), ale nie jest to potrzebne dzięki po4a::man.
       Jeśli formatem źródłowym Twojej dokumentacji jest pod lub xml, to
       byłoby mądre, aby przetłumaczyć źródłowy format, a nie ten
       wygenerowany. W większości wypadków po4a::man rozpozna wygenerowane
       strony i wypisze odpowiednie ostrzeżenie. A nawet odmówi przetwarzana
       stron wygenerowanych przez Pod, ponieważ te strony są perfekcyjnie
       obsługiwane przez po4a::pod i ponieważ ich odpowiednik nroffa generuje
       wiele nowych makr, których nie chcę obsługiwać. Na moim komputerze 1432
       spośród 4323 stron jest wygenerowanych z formatu pod i będzie
       zignorowanych przez po4a::man.

       W większości wypadków, po4a::man wykryje problem i odmówi przetwarzania
       strony, wypisując odpowiedni komunikat. W kilku rzadkich wypadkach,
       program zakończy się bez żadnego ostrzeżenia, ale plik wynikowy będzie
       niepoprawny. Takie sytuacje są nazywane "błędami";) Jeśli spotkasz się
       z taką sytuacją, proszę to zgłosić wraz z odpowiednią poprawką, jeśli
       to możliwe...

STATUS MODUŁU

       Tego 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:

       o   odrzucono jedną trzecią stron ponieważ były one wygenerowane z
           innego formatu obsługiwanego przez po4a (np. pod lub SGML).

       o   10% pozostałych stron odrzucono z powodu błędu (np. nieobsługiwane
           makro groff).

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

       o   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

       po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::Pod(3pm).

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

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