LOCALE::PO4A::MAN.3PM(1) User Contributed Perl Documentation NAZWA Locale::Po4a::Man - konwersja stron podrecznika z/do plikow PO OPIS Celem projektu po4a ("PO for anything") jest ulatwienie tlumaczen (oraz, co ciekawsze, zarzadzania tlumaczeniami) przy uzyciu narzedzi gettext w tych obszarach, gdzie nie byly uzywane, jak na przyklad w obszarze dokumentacji. Locale::Po4a::Man jest modulem ulatwiajacym tlumaczenie dokumentacji w formacie nroff (jezyk stron podrecznika ekranowego) do innych jezykow [uzywanych przez ludzi]. TLUMACZENIE Z POMOCA PO4A::MAN Modul bardzo sie stara, aby ulatwic zycie tlumacza. Dlatego tekst prezentowany tlumaczowi nie jest doslowna kopia oryginalnego tekstu strony podrecznika. W istocie, ukrywane sa surowe czesci formatu nroff, tak zeby tlumacze nie zrobili w nich balaganu. Zawijanie tekstu Teksty niewcietych akapitow sa automatycznie zawijane dla wygody tlumacza. Moze to prowadzic do niewielkich roznic w wygenerowanym pliku wyjsciowym, poniewaz reguly zawijania tekstu uzywane przez groffa nie sa jasne - na przyklad czasami groff zachowuje dwie spacje wystepujace po nawiasie. Tak czy owak, roznica bedzie dotyczyla tylko rozmieszczenia dodatkowych spacji w zawinietym tekscie akapitu. Okreslanie czcionki Pierwsza zmiana dotyczy specyfikacji zmian czcionek. W nroffie istnieje kilka sposobow okreslenia, ze podane slowo powinno byc napisane czcionka mala, wytluszczona lub kursywa. W tekscie do przetlumaczenia mozna to zrobic tylko na jeden sposob, zapozyczony z formatu POD (formatu dokumentacji Perla): I -- kursywa odpowiednik \fItekst\fP lub ".I tekst" B -- tekst wytluszczony odpowiednik \fBtekst\fP lub ".B tekst" R -- tekst zwykla czcionka odpowiednik \fRtekst\fP CW -- tekst o stalej szerokosci odpowiednik \f(CWtekst\fP lub ".CW tekst" Uwaga: CW nie jest dostepne dla wszystkich urzadzen groffa. Uzywanie go nie jest zalecane. Jest dostarczone dla wygody uzytkownika. Automatyczna transliteracja znakow Po4a automatycznie zamienia niektore znaki, aby ulatwic tlumaczenia lub przegladanie tlumaczen. Lista takich transliteracji: laczniki Laczniki (-) i znaki minusa (\-) w stronach podrecznika ekranowego sa wszystkie transliterowane do zwyklych myslnikow (-) w pliku PO. Kiedy tlumaczenia sa zapisywane w pliku wynikowym wszystkie myslniki sa zamieniane na znaki minusa (\-). Tlumacze moga wymusic wstawienie lacznika, uzywajac w swoich tlumaczeniach kodu "\[hy]" groffa. spacje nierozdzielajace Tlumacze moga uzywac nierozdzielajacych spacji w swoich tlumaczeniach. Takie spacje nierozdzielajace (0xA0 w latin1) beda przetlumaczone jako spacje nierozdzielajace roff ("\ "). transliteracje cudzyslowow `` i '' sa odpowiednio zamieniane na \*(lq i \*(rq. Aby uniknac tych transliteracji, tlumacze moga umiescic zerowej szerokosci znak roffa (np. uzywajac odpowiednio `\&` lub '\&'). Wstawianie "<" i ">" w tlumaczeniach Poniewaz znaki te sa uzywane do oddzielania czesci objetych zmiana czcionki, nie mozna ich uzywac wprost. Zamiast nich trzeba uzyc E i E (jak w POD, po raz kolejny). OPCJE AKCEPTOWANE PRZEZ MODUL Opcje tego modulu: debug Uaktywnia debugowanie kilku wewnetrznych mechanizmow modulu. Informacje o tym, ktore czesci moga byc debugowane, mozna znalezc w zrodlach. verbose Zwieksza gadatliwosc. groff_code This option controls the behavior of the module when it encounter a .de, .ie or .if section. It can take the following values: fail Jest to domyslna wartosc. Dzialanie modulu zakonczy sie bledem, jezeli zostanie napotkana sekcja .de, .ie lub .if. verbatim Okresla, ze sekcje .de, .ie lub .if musza byc skopiowane bez zmian z oryginalu do tlumaczonego dokumentu. translate Wskazuje sekcje .de, .ie lub .if jako mozliwe do przetlumaczenia. Opcja powinna byc uzywana tylko wtedy, gdy ktoras z tych sekcji zawiera tekst do przetlumaczenia. W przeciwnym razie wskazane byloby uzycie verbatim. generated This option specifies that the file was generated, and that po4a should not try to detect if the man pages was generated from another format. This option is mandatory to use po4a on generated man pages. Note that translating generated pages instead of sources ones is often more fragile, and thus a bad idea. mdoc Ta opcja jest uzyteczna tylko dla stron w formacie mdoc. Wybiera dokladniejsza obsluge formatu mdoc, nakazuje po4a nietlumaczenie sekcji "NAME" (NAZWA). Strony mdoc, zawierajace przetlumaczona sekcje "NAME", nie generuja naglowka ani stopki. Zgodnie ze strona podrecznika groff_mdoc, wymagane sa sekcje NAME (NAZWA), SYNOPSIS (SKLADNIA)oraz DESCRIPTION (OPIS). Chociaz nie ma zadnych znanych problemow z przetlumaczonymi sekcjami SYNOPSIS czy DESCRIPTION, to ich tlumaczenie mozna rowniez pominac za pomoca: -o mdoc=NAME,SYNOPSIS,DESCRIPTION Kwestie mdoc mozna takze rozwiazac, uzywajac zalacznika podobnego do ponizszego: PO4A-HEADER:mode=before;position=^.Dd .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name" The following options specify the behavior of a user-defined macro (with a .de request), or of a classical macro that is not supported by po4a. They take as argument a comma-separated list of macros. For example: -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX Uwaga: jesli po4a nie obsluguje danego makra, a uwazasz, ze jest to standardowe makro roff, prosze to zglosic zespolowi deweloperow po4a. untranslated untranslated oznacza, ze to makro (i wszystkie jego argumenty) nie musza byc tlumaczone. noarg noarg jest jak untranslated, poza tym, ze po4a sprawdzi, ze do tego makra nie dodano zadnego argumentu. translate_joined translate_joined oznacza, ze po4a musi zaproponowac tlumaczenie argumentow makra. translate_each translate_each powoduje, ze argumenty beda takze zaproponowane do tlumaczenia, z tym ze kazdy z nich bedzie przetlumaczony osobno. no_wrap Opcja przyjmuje jako argument rozdzielona przecinkami liste par poczatek:koniec, gdzie poczatek i koniec sa poleceniami ograniczajacymi poczatek i koniec sekcji, ktorej tekst nie powinien byc ponownie zawijany. Note: no test is done to ensure that an end command matches its begin command; any ending command stop the no_wrap mode. If you have a begin (respectively end) macro that has no end (respectively begin), you can specify an existing end (like fi) or begin (like nf) as a counterpart. These macros (and their arguments) won't be translated. inline Opcja pozwala na podanie rozdzielonej przecinkami listy makr, ktore nie moga dzielic biezacego akapitu. Komunikat do przetlumaczenia bedzie wtedy zawieral foo <.bar baz qux> quux, gdzie bar jest poleceniem, ktore powinno byc wlaczone do pliku, a baz qux - jego argumentami. unknown_macros Ta opcja okresla zachowanie po4a po napotkaniu nieznanego makra. Domyslnie po4 konczy dzialanie z bledem i wyswietla stosowny komunikat. Mozliwe sa nastepujace wartosci: failed (wartosc domyslna), untranslated, noarg, translate_joined, translate_each (patrz objasnienia powyzej). PISANIE STRON PODRECZNIKA ZGODNYCH Z PO4A::MAN Modul wciaz ma duzo ograniczen i zawsze bedzie mial, poniewaz nie jest rzeczywistym interpreterem nroffa. Byloby mozliwe wykonanie rzeczywistego interpretera nroffa, aby umozliwic autorom uzywanie w swoich stronach wszystkich istniejacych makr i tworzenie nowych, ale nie chcielismy tego robic. Byloby to zbyt trudne, a przy tym raczej niepotrzebne. Uwazamy, ze jezeli autorzy stron podrecznika chca, zeby ich strony byly przetlumaczone, to musza tak przeksztalcic strony, by uproscic prace tlumaczy. Tak wiec, parser stron man zaimplementowany w po4a ma kilka znanych ograniczen, ktorych nie chcemy poprawiac, i bedacych pulapkami, ktorych powinienes unikac, jesli chcesz, zeby tlumacze opiekowali sie Twoja dokumentacja. Nie programuj w nroffie nroff jest kompletnym jezykiem programowania z definicjami makr, instrukcjami warunkowymi itd. Poniewaz parser nie jest pelnowartosciowym interpreterem nroffa, zwroci blad podczas przetwarzania stron zawierajacych te wlasciwosci. (Na moim komputerze jest okolo 200 takich stron). Uzywaj prostego zbioru makr Wciaz istnieje kilka makr, ktorych po4a nie obsluguje. Dzieje sie tak dlatego, ze nie znalazlem zadnej dokumentacji tych makr. Ponizej jest lista nieobslugiwanych makr znalezionych na moim komputerze. Prosze zauwazyc, ze ta lista nie jest pelna, poniewaz program konczy sie, zwracajac blad, juz po napotkaniu pierwszego nieznanego makra. Jesli masz jakies informacje o niektorych z nich, z przyjemnoscia dopisze ich obsluge. Z powodu tych makr okolo 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 Ukrywanie tekstu przez po4a Czasem autor wie, ze niektore czesci strony podrecznika nie powinny byc tlumaczone, wiec nie powinny byc przetwarzane przez po4a. Na przyklad opcja moze pobierac argument other oraz other moze sie takze pojawic jako ostatni element listu. Pierwsze other nie powinno byc tlumaczone, a drugie - powinno. W takim przypadku, aby po4a pominelo takie komunikaty, autor moze uzyc specjalnych konstrukcji groffa: .if !'po4a'hide' .B other (wymaga to podania opcji -o groff_code=verbatim) Aby to zautomatyzowac, mozna zdefiniowac 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 sie zbedny, poniewaz po4a nie przetwarza wnetrza definicji makra) lub uzywajac aliasu: .als IR_untranslated IR .IR_untranslated \-q ", " \-\-quiet Wymaga to podania opcji -o untranslated=als,IR_untranslated. Wniosek Podsumowujac te sekcje, pamietaj, zeby tworzyc proste strony podrecznika ekranowego i nie starac sie byc zbyt pomyslowym. Roff pozwala na wiele rzeczy, ktore nie sa obslugiwane przez parser. Na przyklad: nie rob balaganu, uzywajac \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, ze nroff dopuszcza rozdzielanie makr i ich argumentow, ale obslugiwanie tego zbytnio by skomplikowalo parser. Oczywiscie inna mozliwoscia jest uzycie innego formatu, bardziej przyjaznego tlumaczom (jak POD uzywajacy po4a::pod albo jednego z rodziny XML, np. SGML), ale nie jest to potrzebne dzieki po4a::man. Jesli formatem zrodlowym Twojej dokumentacji jest POD lub XML, to byloby madre, aby przetlumaczyc zrodlowy format, a nie ten wygenerowany. W wiekszosci wypadkow po4a::man rozpozna wygenerowane strony i wypisze odpowiednie ostrzezenie. A nawet odmowi przetwarzana stron wygenerowanych przez POD, poniewaz te strony sa perfekcyjnie obslugiwane przez po4a::pod i poniewaz ich odpowiednik nroffa generuje wiele nowych makr, ktorych nie chce obslugiwac. Na moim komputerze 1432 sposrod 4323 stron jest wygenerowanych z formatu POD i bedzie zignorowanych przez po4a::man. W wiekszosci wypadkow, po4a::man wykryje problem i odmowi przetwarzania strony, wypisujac odpowiedni komunikat. W kilku rzadkich wypadkach, program zakonczy sie bez zadnego ostrzezenia, ale plik wynikowy bedzie niepoprawny. Takie sytuacje sa nazywane "bledami";) Jesli spotkasz sie z taka sytuacja, prosze to zglosic wraz z odpowiednia poprawka, jesli to mozliwe STATUS MODULU Modulu mozna uzywac z wiekszoscia istniejacych stron podrecznika. Niektore testy sa regularnie uruchamiane na komputerach z Linuksem: o odrzucono jedna trzecia stron poniewaz byly one wygenerowane z innego formatu obslugiwanego przez po4a (np. POD lub SGML). o 10% pozostalych stron odrzucono z powodu bledu (np. nieobslugiwane makro groff). o W koncu mniej niz 1% stron zostal zaakceptowany bez ostrzezen przez po4a, ale wystapily pewne powazne problemy (np. usuniete lub dodane slowa). o Inne strony sa zazwyczaj obslugiwane bez roznic bardziej istotnych niz roznice w liczbie spacji czy zawijaniu linii (problemy z czcionkami w mniej niz 10% przetworzonych stron). ZOBACZ TAKZE Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7) AUTORZY Denis Barbier Nicolas Francois Martin Quinson (mquinson#debian.org) TLUMACZENIE Robert Luberda PRAWA AUTORSKIE I LICENCJA Copyright (C) 2002-2008 SPI, Inc. This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file). perl v5.38.2 2024-06-26 LOCALE::PO4A::MAN.3PM(1)