Rechercher une page de manuel
Locale::Po4a::Man.3pm
Langue: pl
Version: 2010-06-01 (fedora - 01/12/10)
Section: 3 (Bibliothèques de fonctions)
Sommaire
NAZWA
Locale::Po4a::Man - Konwersja stron podrÄcznika z/do plików POOPIS
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,DESCRIPTIONKwestiÄ 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 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:
- *
- 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
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).
Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre