Provided by: po4a_0.57-2_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 czasami groff zachowuje
       dwie spacje występujące po nawiasie.

       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 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 początek:koniec, gdzie
           początek 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 po4 kończy
           działanie z błędem i wyświetla stosowny komunikat. Możliwe są następujące wartości:
           failed (wartość domyślna), untranslated, noarg, translate_joined, translate_each
           (patrz objaśnienia powyżej).

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

       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:

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

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

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

       •   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

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

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 SPI, Inc.

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