Linux Certif

Toute la documentation sur la certification Linux LPI

Locale::Po4a::Man.3pm

NAZWA

Locale::Po4a::Man - Konwersja stron podrA.Xcznika z/do plikA~Xw PO

OPIS

Celem projektu po4a (``po for anything'') jest uA°Xatwienie tA°XumaczeA°X (oraz, co ciekawsze, zarzA.Xdzania tA°Xumaczeniami) przy uA°Xyciu narzA.Xdzi gettext w tych obszarach, gdzie nie byA°Xy uA°Xywane, jak na przykA°Xad w obszarze dokumentacji.

Locale::Po4a::Man jest moduA°Xem uA°XatwiajA.Xcym tA°Xumaczenie dokumentacji w formacie nroff (jA.Xzyk stron podrA.Xcznika ekranowego) do innych jA.XzykA~Xw [uA°Xywanych przez ludzi].

TA°XUMACZENIE Z POMOCA.X PO4A::MAN

ModuA°X bardzo siA.X stara, aby uA°XatwiA.X A°Xycie tA°Xumacza. Dlatego tekst prezentowany tA°Xumaczowi nie jest dosA°XownA.X kopiA.X oryginalnego tekstu strony podrA.Xcznika. W istocie, ukrywane sA.X surowe czA.XA°Xci formatu nroff, tak A°Xeby tA°Xumacze nie zrobili w nich baA°Xaganu.

Zawijanie tekstu

Teksty niewciA.Xtych akapitA~Xw sA.X automatycznie zawijane dla wygody tA°Xumacza. MoA°Xe to prowadziA.X do niewielkich rA~XA°Xnic w wygenerowanym pliku wyjA°Xciowym, poniewaA°X reguA°Xy zawijania tekstu uA°Xywane przez groffa nie sA.X jasne. Na przykA°Xad dwie spacje po nawiasie sA.X czasem zachowywane, podczas gdy reguA°Xy typografii [angielskiej - przyp. tA°Xum.] wymagajA.X zachowania dwA~Xch spacji tylko po znaku kropki (no dobra, angielski nie jest moim natywnym jA.Xzykiem, wiA.Xc nie jestem tego pewien. JeA°Xli masz jakieA°X inne informacjA.X, to prosimy o ich przekazanie).

Tak czy owak, rA~XA°Xnica bA.Xdzie dotyczyA°Xa tylko rozmieszczenia dodatkowych spacji w zawiniA.Xtym tekA°Xcie akapitu.

OkreA°Xlanie czcionki

Pierwsza zmiana dotyczy specyfikacji zmian czcionek. W nroffie istnieje kilka sposobA~Xw okreA°Xlenia, A°Xe podane sA°Xowo powinno byA.X napisane czcionkA.X maA°XA.X, wytA°XuszczonA.X lub kursywA.X. W tekA°Xcie do przetA°Xumaczenia moA°Xna to zrobiA.X tylko na jeden sposA~Xb, zapoA°Xyczony z formatu pod (formatu dokumentacji Perla):

I<tekst> --- kursywa

odpowiednik \fItekst\fP lub ``.I tekst''

B<tekst> --- tekst wytA°Xuszczony

odpowiednik \fBtekst\fP lub ``.B tekst''

R<tekst> --- tekst zwykA°XA.X czcionkA.X

odpowiednik \fRtekst\fP

CW<tekst<gt> --- tekst o staA°Xej szerokoA°Xci

odpowiednik \f(CWtekst\fP lub ``.CW tekst''

Uwaga: CW nie jest dostA.Xpne dla wszystkich urzA.XdzeA°X groffa. UA°Xywanie go nie jest zalecane. Jest dostarczone dla wygody uA°Xytkownika.

Automatyczna transliteracja znakA~Xw

Po4a automatycznie zamienia niektA~Xre znaki, aby uA°XatwiA.X tA°Xumaczenia lub przeglA.Xdanie tA°XumaczeA°X. Lista takich transliteracji:

A°XA.Xczniki

A°XA.Xczniki (-) i znaki minusa (\-) w stronach podrA.Xcznika ekranowego sA.X wszystkie transliterowane do zwykA°Xych myA°XlnikA~Xw (-) w pliku PO. Kiedy tA°Xumaczenia sA.X zapisywane w pliku wynikowym wszystkie myA°Xlniki sA.X zamieniane na znaki minusa (\-).

TA°Xumacze mogA.X wymusiA.X wstawienie A°XA.Xcznika, uA°XywajA.Xc w swoich tA°Xumaczeniach kodu ``\[hy]'' groffa.

spacje nierozdzielajA.Xce

TA°Xumacze mogA.X uA°XywaA.X nierozdzielajA.Xcych spacji w swoich tA°Xumaczeniach. Takie spacje nierozdzielajA.Xce (0xA0 w latin1) bA.XdA.X przetA°Xumaczone jako spacje nierozdzielajA.Xce roff (``\ '').

transliteracje cudzysA°XowA~Xw

`` i '' sA.X odpowiednio zamieniane na \*(lq i \*(rq.

Aby uniknA.XA.X tych transliteracji, tA°Xumacze mogA.X umieA°XciA.X zerowej szerokoA°Xci znak roffa (np. uA°XywajA.Xc odpowiednio `\&` lub '\&').

Wstawianie < i > w tA°Xumaczeniach

PoniewaA°X znaki te sA.X uA°Xywane do oddzielania czA.XA°Xci objA.Xtych zmianA.X czcionki, nie moA°Xna ich uA°XywaA.X wprost. Zamiast nich trzeba uA°XyA.X E<lt> i E<gt> (jak w pod, po raz kolejny).

OPCJE AKCEPTOWANE PRZEZ TEN MODUA°X

Opcje tego moduA°Xu:

debug

Uaktywnia debugowanie kilku wewnA.Xtrznych mechanizmA~Xw moduA°Xu. Informacje o tym, ktA~Xre czA.XA°Xci mogA.X byA.X debugowane, moA°Xna znaleA°XA.X w A°XrA~XdA°Xach.

verbose

ZwiA.Xksza gadatliwoA°XA.X.

groff_code

Ta opcja pozwala na zmianA.X zachowania moduA°Xu, kiedy napotka sekcjA.X .de, .ie lub .if. MoA°Xe przyjmowaA.X nastA.XpujA.Xce wartoA°Xci:

fail

Jest to domyA°Xlna wartoA°XA.X. DziaA°Xanie moduA°Xu zakoA°Xczy siA.X bA°XA.Xdem, jeA°Xeli zostanie napotkana sekcja .de, .ie lub .if.

verbatim

OkreA°Xla, A°Xe sekcje .de, .ie lub .if muszA.X byA.X skopiowane bez zmian z oryginaA°Xu do tA°Xumaczonego dokumentu.

translate

Wskazuje sekcje .de, .ie lub .if jako moA°Xliwe do przetA°Xumaczenia. Opcja powinna byA.X uA°Xywana tylko wtedy, gdy ktA~XraA°X z tych sekcji zawiera tekst do przetA°Xumaczenia. W przeciwnym razie wskazane byA°Xoby uA°Xycie verbatim.

generated

Ta opcja okreA°Xla, A°Xe plik zostaA°X wygenerowany z innego formatu , a po4a nie powinno prA~XbowaA.X tego wykrywaA.X. Pozwala to na uA°Xywanie po4a wA°XaA°Xnie na takich generowanych stronach podrA.Xcznika. Opcja nie pobiera A°Xadnych argumentA~Xw.

mdoc

Ta opcja jest uA°Xyteczna tylko dla stron w formacie mdoc.

Wybiera dokA°XadniejszA.X obsA°XugA.X formatu mdoc, nakazujA.X po4a nietA°Xumaczenie sekcji ``NAME'' (NAZWA). Strony mdoc, zawierajA.Xce przetA°XumaczonA.X sekcjA.X ``NAME'', nie generujA.X nagA°XA~Xwka ani stopki.

Zgodnie ze stronA.X podrA.Xcznika groff_mdoc, wymagane sA.X sekcje NAME (NAZWA), SYNOPSIS (SKA°XADNIA)oraz DESCRIPTION (OPIS). ChociaA°X nie ma A°Xadnych znanych problemA~Xw z przetA°Xumaczonymi sekcjami SYNOPSIS czy DESCRIPTION, to ich tA°Xumaczenie moA°Xna rA~XwnieA°X pominA.XA.X za pomocA.X:
 -o mdoc=NAME,SYNOPSIS,DESCRIPTION

KwestiA.X mdoc moA°Xna takA°Xe rozwiA.XzaA.X, uA°XywajA.Xc zaA°XA.Xcznika podobnego do poniA°Xszego:
 PO4A-HEADER:mode=before;position=^.Dd
 .TH DOCUMENT_TITLE 1 ``Month day, year'' OS ``Section Name''

PoniA°Xsze opcje pozwalajA.X okreA°XliA.X zachowanie nowego makra (zdefiniowanego poleceniem .de) albo makra nieobsA°Xugiwanego przez po4a. PrzyjmujA.X jako argument rozdzielonA.X przecinkami listA.X makr. Na przykA°Xad:

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

Uwaga: jeA°Xli po4a nie obsA°Xuguje danego makra, a uwaA°Xasz, A°Xe jest to standardowe makro roff, proszA.X to zgA°XosiA.X zespoA°Xowi deweloperA~Xw po4a.

untranslated

untranslated oznacza, A°Xe to makro (i wszystkie jego argumenty) nie muszA.X byA.X tA°Xumaczone.

noarg

noarg jest jak untranslated, poza tym, A°Xe po4a sprawdzi, A°Xe do tego makra nie dodano A°Xadnego argumentu.

translate_joined

translate_joined oznacza, A°Xe po4a musi zaproponowaA.X tA°Xumaczenie argumentA~Xw makra.

translate_each

translate_each powoduje, A°Xe argumenty bA.XdA.X takA°Xe zaproponowane do tA°Xumaczenia, z tym A°Xe kaA°Xdy z nich bA.Xdzie przetA°Xumaczony osobno.

no_wrap

Opcja przyjmuje jako argument rozdzielonA.X przecinkami listA.X par poczA.Xtek:koniec, gdzie poczA.Xtek i koniec sA.X poleceniami ograniczajA.Xcymi poczA.Xtek i koniec sekcji, ktA~Xrej tekst nie powinien byA.X ponownie zawijany.

Uwaga: nie jest sprawdzane, czy polecenie end ma odpowiadajA.Xce polecenie begin; jakiekolwiek polecenie koA°XczA.Xce zatrzyma tryb no_wrap. JeA°Xeli istnieje makro begin (odpowiednio end) nie majA.Xce pasujA.Xcego end (odpowiednio begin), to moA°Xna podaA.X istniejA.Xce end (jak fi) lub begin (jak nf) jako zamiennik. Makra te (i ich argumenty) nie bA.XdA.X tA°Xumaczone.

inline

Opcja pozwala na podanie rozdzielonej przecinkami listy makr, ktA~Xre nie mogA.X dzieliA.X bieA°XA.Xcego akapitu. Komunikat do przetA°Xumaczenia bA.Xdzie wtedy zawieraA°X foo <.bar baz qux> quux, gdzie bar jest poleceniem, ktA~Xre powinno byA.X wA°XA.Xczone do pliku, a baz qux - jego argumentami.

unknown_macros

Ta opcja okreA°Xla zachowanie po4a po napotkaniu nieznanego makra. DomyA°Xlnie po4a wyA°Xwietli ostrzeA°Xenie. MoA°Xliwe sA.X nastA.XpujA.Xce wartoA°Xci: failed (wartoA°XA.X domyA°Xlna), untranslated, noarg, translate_joined, translate_each.

PISANIE STRON PODRA.XCZNIKA ZGODNYCH Z PO4A::MAN

ModuA°X wciA.XA°X ma duA°Xo ograniczeA°X i zawsze bA.Xdzie miaA°X, poniewaA°X nie jest rzeczywistym interpreterem nroffa. ByA°Xoby moA°Xliwe wykonanie rzeczywistego interpretera nroffa, aby umoA°XliwiA.X autorom uA°Xywanie w swoich stronach wszystkich istniejA.Xcych makr i tworzenie nowych, ale nie chcieliA°Xmy tego robiA.X. ByA°Xoby to zbyt trudne, a przy tym raczej niepotrzebne. UwaA°Xamy, A°Xe jeA°Xeli autorzy stron podrA.Xcznika chcA.X, A°Xeby ich strony byA°Xy przetA°Xumaczone, to muszA.X tak przeksztaA°XciA.X strony, by uproA°XciA.X pracA.X tA°Xumaczy.

Tak wiA.Xc, parser stron man zaimplementowany w po4a ma kilka znanych ograniczeA°X, ktA~Xrych nie chcemy poprawiaA.X, i bA.XdA.Xcych puA°Xapkami, ktA~Xrych powinieneA°X unikaA.X, jeA°Xli chcesz, A°Xeby tA°Xumacze opiekowali siA.X TwojA.X dokumentacjA.X.

Nie programuj w nroffie

nroff jest kompletnym jA.Xzykiem programowania z definicjami makr, instrukcjami warunkowymi itd. PoniewaA°X parser nie jest peA°XnowartoA°Xciowym interpreterem nroffa, zwrA~Xci bA°XA.Xd podczas przetwarzania stron zawierajA.Xcych te wA°XaA°XciwoA°Xci. (Na moim komputerze jest okoA°Xo 200 takich stron).

UA°Xywaj prostego zbioru makr

WciA.XA°X istnieje kilka makr, ktA~Xrych po4a nie obsA°Xuguje. Dzieje siA.X tak dlatego, A°Xe nie znalazA°Xem A°Xadnej dokumentacji tych makr. PoniA°Xej jest lista nieobsA°Xugiwanych makr znalezionych na moim komputerze. ProszA.X zauwaA°XyA.X, A°Xe ta lista nie jest peA°Xna, poniewaA°X program koA°Xczy siA.X, zwracajA.Xc bA°XA.Xd, juA°X po napotkaniu pierwszego nieznanego makra. JeA°Xli masz jakieA°X informacje o niektA~Xrych z nich, z przyjemnoA°XciA.X dopiszA.X ich obsA°XugA.X. Z powodu tych makr okoA°Xo 250 stron na moim komputerze nie jest dostA.Xpnych 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, A°Xe niektA~Xre czA.XA°Xci strony podrA.Xcznika nie powinny byA.X tA°Xumaczone, wiA.Xc nie powinny byA.X przetwarzane przez po4a. Na przykA°Xad opcja moA°Xe pobieraA.X argument other oraz other moA°Xe siA.X takA°Xe pojawiA.X jako ostatni element listu. Pierwsze other nie powinno byA.X tA°Xumaczone, a drugie - powinno.

W takim przypadku, aby po4a pominA.XA°Xo takie komunikaty, autor moA°Xe uA°XyA.X specjalnych konstrukcji groffa:

  .if !'po4a'hide' .B other
 
 

(wymaga to podania opcji -o groff_code=verbatim)

Aby to zautomatyzowaA.X, moA°Xna zdefiniowaA.X 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 siA.X zbA.Xdny, poniewaA°X po4a nie przetwarza wnA.Xtrza definicji makra)

lub uA°XywajA.Xc aliasu:
 .als IR_untranslated IR

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

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

Wniosek

PodsumowujA.Xc tA.X sekcjA.X, pamiA.Xtaj, A°Xeby tworzyA.X proste strony podrA.Xcznika ekranowego i nie staraA.X siA.X byA.X zbyt pomysA°Xowym. Roff pozwala na wiele rzeczy, ktA~Xre nie sA.X obsA°Xugiwane przez parser. Na przykA°Xad: nie rA~Xb baA°Xaganu, uA°XywajA.Xc \c do przerwania przetwarzania tekstu (jak to robi 40 stron podrA.Xcznika na moim komputerze). Albo: argumenty makr umieszczaj w tej samej linii, co samo makro. Wiem, A°Xe nroff dopuszcza rozdzielanie makr i ich argumentA~Xw, ale obsA°Xugiwanie tego zbytnio by skomplikowaA°Xo parser.

OczywiA°Xcie innA.X moA°XliwoA°XciA.X jest uA°Xycie innego formatu, bardziej przyjaznego tA°Xumaczom (jak pod uA°XywajA.Xcy po4a::pod albo jednego z rodziny xml, np. sgml), ale nie jest to potrzebne dziA.Xki po4a::man. JeA°Xli formatem A°XrA~XdA°Xowym Twojej dokumentacji jest pod lub xml, to byA°Xoby mA.Xdre, aby przetA°XumaczyA.X A°XrA~XdA°Xowy format, a nie ten wygenerowany. W wiA.XkszoA°Xci wypadkA~Xw po4a::man rozpozna wygenerowane strony i wypisze odpowiednie ostrzeA°Xenie. A nawet odmA~Xwi przetwarzana stron wygenerowanych przez Pod, poniewaA°X te strony sA.X perfekcyjnie obsA°Xugiwane przez po4a::pod i poniewaA°X ich odpowiednik nroffa generuje wiele nowych makr, ktA~Xrych nie chcA.X obsA°XugiwaA.X. Na moim komputerze 1432 spoA°XrA~Xd 4323 stron jest wygenerowanych z formatu pod i bA.Xdzie zignorowanych przez po4a::man.

W wiA.XkszoA°Xci wypadkA~Xw, po4a::man wykryje problem i odmA~Xwi przetwarzania strony, wypisujA.Xc odpowiedni komunikat. W kilku rzadkich wypadkach, program zakoA°Xczy siA.X bez A°Xadnego ostrzeA°Xenia, ale plik wynikowy bA.Xdzie niepoprawny. Takie sytuacje sA.X nazywane ``bA°XA.Xdami'';) JeA°Xli spotkasz siA.X z takA.X sytuacjA.X, proszA.X to zgA°XosiA.X wraz z odpowiedniA.X poprawkA.X, jeA°Xli to moA°Xliwe...

STATUS MODUA°XU

Tego moduA°Xu moA°Xna uA°XywaA.X z wiA.XkszoA°XciA.X istniejA.Xcych stron podrA.Xcznika.

NiektA~Xre testy sA.X regularnie uruchamiane na komputerach z Linuksem:

•

odrzucono jednA.X trzeciA.X stron poniewaA°X byA°Xy one wygenerowane z innego formatu obsA°Xugiwanego przez po4a (np. pod lub SGML).

•

10% pozostaA°Xych stron odrzucono z powodu bA°XA.Xdu (np. nieobsA°Xugiwane makro groff).

•

W koA°Xcu mniej niA°X 1% stron zostaA°X zaakceptowany bez ostrzeA°XeA°X przez po4a, ale wystA.XpiA°Xy pewne powaA°Xne problemy (np. usuniA.Xte lub dodane sA°Xowa).

•

Inne strony sA.X zazwyczaj obsA°Xugiwane bez rA~XA°Xnic bardziej istotnych niA°X rA~XA°Xnice w liczbie spacji czy zawijaniu linii (problemy z czcionkami w mniej niA°X 10% przetworzonych stron).

ZOBACZ TAKA°XE

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

AUTORZY

  Denis Barbier <barbier@linuxfr.org>
  Nicolas FranA~Xois <nicolas.francois@centraliens.net>
  Martin Quinson (mquinson#debian.org)
 
 

TA°XUMACZENIE

  Robert Luberda <robert@debian.org>
 
 

PRAWA AUTORSKIE I LICENCJA

Copyright 2002-2008 by SPI, inc.

Program jest wolnym oprogramowaniem; moA°Xna go redystrybuowaA.X i/lub modyfikowaA.X zgodnie z warunkami licencji GPL (patrz plik COPYING).