.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::TeX 3pm"
.TH Locale::Po4a::TeX 3pm "2020-12-09" "Narzędzia po4a" "Narzędzia po4a"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAZWA"
.IX Header "NAZWA"
Locale::Po4a::TeX \- konwersja dokumentów TeX z/do plików \s-1PO\s0
.SH "OPIS"
.IX Header "OPIS"
Celem projektu po4a (\*(L"\s-1PO\s0 for anything\*(R") 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.
.PP
Locale::Po4a::TeX jest modułem ułatwiającym tłumaczenie dokumentacji w
formacie TeX do innych języków [używanych przez ludzi].
.PP
Użytkownicy najprawdopodobniej powinni używać modułu LaTeX, który dziedziczy
z modułu TeX i zawiera definicję częstych poleceń LaTeX.
.SH "TŁUMACZENIE Z POMOCĄ PO4A::TEX"
.IX Header "TŁUMACZENIE Z POMOCĄ PO4A::TEX"
Tego modułu można bezpośrednio użyć do obsługi ogólnych dokumentów w
formacie TeX. Podzieli on dokument na mniejsze bloki (akapity, bloki
dosłowych tekstów, a nawet jeszcze mniejsze jak tytuły czy indeksy).
.PP
Istnieje kilka opcji (opisanych w następnej sekcji), które mogą dostosować
zachowanie do Twoich wymagań. Jeśli nie pasuje ono do formatu Twojego
dokumentu, zachęcamy do napisania własnego modułu dziedziczącego z tego,
opisującego szczegóły formatu. Szczegóły można znaleźć w sekcji \fB\s-1PRACA\s0
ZMODUŁAMI \s-1POCHODNYMI\s0\fR poniżej.
.PP
Zachowanie modułu może być także zmieniane w pliku TeX za pomocą linii
zaczynających się od \*(L"% po4a:\*(R". Takie zmiany są opisane w sekcji
\&\fB\s-1DOSTOSOWYWANIE ZA\s0 POMOCĄ \s-1OPCJI W PLIKU\s0 ŹRÓDŁOWYM\fR.
.SH "OPCJE AKCEPTOWANE PRZEZ MODUŁ"
.IX Header "OPCJE AKCEPTOWANE PRZEZ MODUŁ"
Opcje tego modułu:
.IP "\fBdebug\fR" 4
.IX Item "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.
.IP "\fBno_wrap\fR" 4
.IX Item "no_wrap"
Rozdzielona przecinkami lista środowisk, które nie powinny być powtórnie
zawijane.
.Sp
Proszę zauważyć, że środowiska verbatim i no_wrap się różnią. W blokach
verbatim nie są analizowane polecenia ani komentarze.
.Sp
Jeżeli środowisko nie było wcześniej zarejestrowane, to po4a założy, że to
środowisko nie potrzebuje żadnych parametrów.
.IP "\fBexclude_include\fR" 4
.IX Item "exclude_include"
Rozdzielona dwukropkami lista plików, które nie powinny być włączane przez
\&\einput i \einclude.
.IP "\fBdefinitions\fR" 4
.IX Item "definitions"
Nazwa pliku zawierającego definicje dla po4a, jak to zdefiniowano w sekcji
\&\fB\s-1DOSTOSOWYWANIE ZA\s0 POMOCĄ \s-1OPCJI W PLIKU\s0 ŹRÓDŁOWYM\fR. Można użyć tej opcji,
jeśli nie jest możliwe umieszczenie definicja w tłumaczonym dokumencie.
.IP "\fBverbatim\fR" 4
.IX Item "verbatim"
Rozdzielona przecinkami lista środowisk, które powinny być przetwarzane tak,
jak zostały podane.
.Sp
Jeżeli środowisko nie było wcześniej zarejestrowane, to po4a założy, że to
środowisko nie potrzebuje żadnych parametrów.
.PP
Użycie tych opcji pozwala zmienić zachowanie poleceń zdefiniowanych w
domyślnych listach.
.SH "DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM"
.IX Header "DOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU ŹRÓDŁOWYM"
Działanie modułu TeX może być zmieniane za pomocą linii zaczynających się od
\&\fB% po4a:\fR, które są interpretowane jako polecenia parsera. Rozpoznawane są
następujące polecenia:
.IP "\fB% po4a: command\fR \fIpolecenie1\fR \fBalias\fR \fIpolecenie2\fR" 4
.IX Item "% po4a: command polecenie1 alias polecenie2"
Mówi, że argumenty polecenia \fIpolecenie1\fR powinny być traktowane jako
argumenty polecenia \fIpolecenie2\fR.
.IP "\fB% po4a: polecenie\fR \fIpolecenie1\fR \fIparametry\fR" 4
.IX Item "% po4a: polecenie polecenie1 parametry"
Pozwala szczegółowo opisać parametry polecenia \fIpolecenie1\fR. Ta informacja
zostanie użyta do sprawdzenia liczby i typów parametrów.
.Sp
Polecenie \fIpolecenie1\fR może być poprzedzone przez następujące znaki:
.RS 4
.IP "gwiazdka (\fB*\fR)" 4
.IX Item "gwiazdka (*)"
po4a wyciągnie to polecenie z akapitów (jeśli jest umieszczone na początku
lub na końcu akapitu). Tłumacze będą musieli wtedy przetłumaczyć te
parametry, które są oznaczone jako odpowiednie do tłumaczenia.
.IP "plus (\fB+\fR)" 4
.IX Item "plus (+)"
Tak jak w przypadku gwiazdki, to polecenie będzie wyodrębnione, jeżeli
pojawi się na końcu bloku, ale jego parametry nie zostaną oddzielnie
przetłumaczone. Tłumacz będzie musiał przetłumaczyć polecenie połączone ze
wszystkimi jego parametrami. Pozwala to zachować więcej kontekstu i jest
użyteczne dla wszystkich poleceń, przyjmujących jako parametr krótkie słowo,
które może mieć wiele znaczeń (i tłumaczeń).
.Sp
Uwaga: w tym przypadku nie trzeba określać, które parametry należy
tłumaczyć, ale po4a musi znać typ i liczbę parametrów.
.IP "minus (\fB\-\fR)" 4
.IX Item "minus (-)"
W takim wypadku, polecenie nie zostanie wydobyte z żadnego bloku. Ale jeżeli
pojawi się samodzielnie w bloku, to tłumaczowi zostaną pokazane tylko te
parametry, które zostały zaznaczone jako możliwe do
przetłumaczenia. Polecenia te zazwyczaj nie powinny być wydzielane z ich
akapitów (aby zachować kontekst), ale nie ma żadnego powodu, żeby męczyć
tłumacza nimi, jeśli cały komunikat jest zawarty w takim poleceniu.
.RE
.RS 4
.Sp
Argument \fIparameters\fR jest zbiorem nawiasów [] (określających argumenty
opcjonalne) lub {} (określających argumenty wymagane).
Aby wskazać, że parametr ma zostać przetłumaczony, można pomiędzy
tymi nawiasami umieścić znak podkreślenia (_). Na przykład:
 % po4a: command *chapter [_]{_}
.Sp
To wskazuje, że polecenie chapter ma dwa parametry: opcjonalny
(krótki tytuł) i obowiązkowy, oba muszą być przetłumaczone.
Aby określić, że polecenie href ma dwa wymagane parametry,
oraz że pierwszy z nich (\s-1URL\s0) ma nie być przetłumaczony, oraz
że polecenie to ma nie być oddzielone od otaczającego go akapitu
(co pozwala tłumaczowi zmienić pozycję linku w zdaniu), można użyć:
 % po4a: command \-href {}{_}
.Sp
W tym wypadku informacja wskazująca, które argumenty muszą być
przetłumaczone jest używana tylko wtedy, gdy akapit jest utworzony tylko z
tej komendy href.
.RE
.IP "\fB% po4a: environment\fR \fIśrodowisko\fR \fIparametery\fR" 4
.IX Item "% po4a: environment środowisko parametery"
This permits to define the parameters accepted by the \fIenv\fR environment.
This information is later used to check the number of arguments of the
\&\ebegin command, and permit to specify which one must be translated.
The syntax of the \fIparameters\fR argument is the same as described for the
others commands.
The first parameter of the \ebegin command is the name of the environment.
This parameter must not be specified in the list of parameters. Here are
some examples:
 % po4a: environment multicols {}
 % po4a: environment equation
.Sp
Tak jak dla poleceń \fIśrodowisko\fR może być poprzedzone plusem (+), aby
wskazać, że polecenie \ebegin musi być przetłumaczone wraz ze wszystkimi jego
argumentami.
.ie n .IP "\fB% po4a: separator\fR \fIśrodowisko\fR \fB""\fR\fIwyrażenie_regularne\fR\fB""\fR" 4
.el .IP "\fB% po4a: separator\fR \fIśrodowisko\fR \fB``\fR\fIwyrażenie_regularne\fR\fB''\fR" 4
.IX Item "% po4a: separator środowisko ""wyrażenie_regularne"""
Wskazuje, że środowisko powinno być podzielone zgodnie z podanym wyrażeniem
regularnym.
.Sp
Wyrażenie regularne jest ograniczone cudzysłowami. Nie powinno tworzyć
żadnej wstecznych referencji. Jeśli potrzeba pogrupować, to należy użyć
(?:). Może także wymagać kilku znaków cytowania.
.Sp
Na przykład moduł LaTeX używa wyrażenia regularnego \*(L"(?:&|\e\e\e\e)\*(R" , aby
osobno przetłumaczyć każdą komórkę tabeli (linie są rozdzielone przez '\e\e' a
komórki przez '&').
.Sp
Środowisko jest rozszerzane do typu wyświetlanego pliku \s-1PO.\s0 Można tego użyć,
aby pierwszy wymagany argument polecenia title podzielić na \*(L"\e\e\e\e\*(R". W tym
przypadku środowiskiem jest title{#1}.
.IP "\fB% po4a: verbatim environment\fR \fIśrodowisko\fR" 4
.IX Item "% po4a: verbatim environment środowisko"
Określa, że \fIśrodowisko\fR jest środowiskiem dosłownym,tj. takim, w którym
wszelkie komentarze i polecenia są ignorowane.
.Sp
Jeżeli środowisko nie było wcześniej zarejestrowane, to po4a założy, że to
środowisko nie potrzebuje żadnych parametrów.
.SH "PRACA Z MODUŁAMI POCHODNYMI"
.IX Header "PRACA Z MODUŁAMI POCHODNYMI"
.IP "\fBpre_trans\fR" 4
.IX Item "pre_trans"
.PD 0
.IP "\fBpost_trans\fR" 4
.IX Item "post_trans"
.IP "\fBadd_comment\fR" 4
.IX Item "add_comment"
.PD
Add a string as a comment to be added around the next translated element.
This is mostly useful to the texinfo module, as comments are automatically
handled in TeX.
.IP "\fBtranslate\fR" 4
.IX Item "translate"
Funkcje opakowujące translate TransTractora  filtrami uruchamianymi przed
przetwarzaniem i po nim.
.Sp
Komentarze akapitu są wstawiane jako komentarz \s-1PO\s0 dla pierwszego
tłumaczonego komunikatu dla tego akapitu.
.IP "\fBget_leading_command\fR($buffer)" 4
.IX Item "get_leading_command($buffer)"
Funkcja zwraca:
.RS 4
.IP "Nazwę polecenia" 4
.IX Item "Nazwę polecenia"
Jeżeli na początku podanego bufora nie znaleziono żadnego polecenia, tekst
będzie pusty. Są brane pod uwagę tylko te polecenia, które można
rozdzielić. Hash \f(CW%separated_command\fR zawiera ich listę.
.IP "Wariant" 4
.IX Item "Wariant"
Określa użyty wariant. Na przykład gwiazdka (*) może być dodana na końcu
sekcji poleceń, aby określić że nie powinny być numerowane. W tym przypadku
pole to będzie zawierać \*(L"*\*(R". Jeśli wariant nie istnieje, pole będzie pustym
łańcuchem znaków.
.IP "Tablicę par  (typ argumentu, argument)" 4
.IX Item "Tablicę par (typ argumentu, argument)"
Typem argumentu może być albo \*(L"{\*(R" (dla argumentów wymaganych), albo \*(L"[\*(R" (dla
argumentów opcjonalnych).
.IP "Pozostały bufor" 4
.IX Item "Pozostały bufor"
Reszta bufora po usunięciu początkowego polecenia i jego argumentów. Jeśli
nie znaleziono polecenia, oryginalny bufor jest zwracany niezmieniony w tym
polu.
.RE
.RS 4
.RE
.IP "\fBget_trailing_command\fR($buffer)" 4
.IX Item "get_trailing_command($buffer)"
To samo co, \fBget_leading_command\fR, ale dla poleceń z końca bufora.
.IP "\fBtranslate_buffer\fR" 4
.IX Item "translate_buffer"
Rekurencyjnie tłumaczy bufor, wydzielając z niego początkowe i końcowe
polecenia (które powinny być tłumaczone oddzielnie).
.Sp
Jeżeli w bieżącym środowisku zmienna \f(CW%translate_buffer_env\fR zawiera definicję
funkcji, to ta funkcja zostanie użyta zamiast \fBtranslate_buffer()\fR do
przetłumaczenia zawartości bufora.
.IP "\fBread\fR" 4
.IX Item "read"
Przeładowanie funkcji \fBread()\fR TransTractora.
.IP "\fBread_file\fR" 4
.IX Item "read_file"
Rekurencyjnie czyta plik, dodając te pliki włączane, które nie są wymienione
w tablicy \f(CW@exclude_include\fR. Plik włączane są wyszukiwane poleceniem
\&\fBkpsewhich\fR z biblioteki Kpathsea.
.Sp
Poza częścią włączania plików, jest to przekopiowane z funkcji read
TransTractora.
.IP "\fBparse_definition_file\fR" 4
.IX Item "parse_definition_file"
Procedura parsowania pliku zawierającego dyrektywę po4a (definicje nowych
poleceń).
.IP "\fBparse_definition_line\fR" 4
.IX Item "parse_definition_line"
Przetwarza linię definicji w formacie \*(L"% po4a: \*(R".
.Sp
Dalsze informacje można znaleźć w sekcji \fB\s-1DOSTOSOWYWANIE ZA\s0 POMOCĄ \s-1OPCJI W
PLIKU\s0 ŹRÓDŁOWYM\fR.
.IP "\fBis_closed\fR" 4
.IX Item "is_closed"
.PD 0
.IP "\fBparse\fR" 4
.IX Item "parse"
.IP "\fBdocheader\fR" 4
.IX Item "docheader"
.PD
.SH "FUNKCJE WEWNĘTRZNE, używane do pisania parserów"
.IX Header "FUNKCJE WEWNĘTRZNE, używane do pisania parserów"
Funkcje poleceń i środowiska pobierają następujące argumenty (oraz dodatkowo
obiekt \f(CW$self\fR):
.IP "Nazwę polecenia" 4
.IX Item "Nazwę polecenia"
.PD 0
.IP "Wariant" 4
.IX Item "Wariant"
.IP "Tablica krotek (typ, argument)" 4
.IX Item "Tablica krotek (typ, argument)"
.IP "Bieżące środowisko" 4
.IX Item "Bieżące środowisko"
.PD
.PP
Pierwsze 3 argumenty są wyodrębniane przez get_leading_command lub
get_trailing_command.
.PP
Funkcje poleceń i środowiska zwracają tłumaczenia poleceń z jego argumentami
i nowe środowisko.
.PP
Funkcje środowiska są wywoływane, jeśli znaleziono polecenie \ebegin. Są one
wywoływane z poleceniem \ebegin i jego argumentami.
.PP
Moduł TeX proponuje tylko jedną funkcję poleceń i jedną funkcję środowiska:
generic_command i generic_environment.
.PP
generic_command używa informacji podanych przez 
register_generic_command albo przez dodanie definicji w pliku TeX:
 % po4a: command \fIpolecenie1\fR \fIparametry\fR
.PP
generic_environment używa informacji podanych przez 
register_generic_environment albo przez dodanie definicji w pliku TeX:
 % po4a: environment \fIśrodowisko\fR \fIparametery\fR
.PP
Obie funkcje tylko przetłumaczą parametry, które były określone jako możliwe
do tłumaczenie (z ""). generic_environment doda nazwę środowiska do stosu
środowiska, a generic_command doda nazwę polecenia, po której nastąpi
identyfikator parametru (jak {#7} lub [#2]).
.SH "STATUS MODUŁU"
.IX Header "STATUS MODUŁU"
Moduł powinien być bardziej przetestowany.
.PP
Było testowany na książce z dokumentacją Pythona.
.SH "LISTA RZECZY DO ZROBIENIA"
.IX Header "LISTA RZECZY DO ZROBIENIA"
.IP "Automatyczne wykrywanie nowych poleceń" 4
.IX Item "Automatyczne wykrywanie nowych poleceń"
Moduł TeX mógłby sparsować argumenty nowego polecenia i spróbować odgadnąć
liczbę i typy argumentów oraz czy powinny być tłumaczone, czy też nie.
.IP "Tłumaczenie separatora środowiska" 4
.IX Item "Tłumaczenie separatora środowiska"
Kiedy jako separatora środowiska użyje się \eitem, to jego argument jest
dołączany do następującego łańcucha znaków.
.IP "Niektóre polecenia powinny być dodane do stosu środowiska." 4
.IX Item "Niektóre polecenia powinny być dodane do stosu środowiska."
Te polecenia powinny być podawane w parach. Umożliwiłoby podawanie poleceń
zaczynających lub kończących dosłowne środowisko.
.IP "Inne" 4
.IX Item "Inne"
Różne inne punkty są oznaczone w źródłach jako \*(L"\s-1TODO\*(R",\s0 czyli do zrobienia.
.SH "ZNANE BŁĘDY"
.IX Header "ZNANE BŁĘDY"
Różne punkty są oznaczone w źródłach jako \*(L"\s-1FIXME\*(R",\s0 czyli do poprawienia.
.SH "ZOBACZ TAKŻE"
.IX Header "ZOBACZ TAKŻE"
\&\fBLocale::Po4a::LaTeX\fR\|(3pm),
\&\fBLocale::Po4a::TransTractor\fR\|(3pm),
\&\fBpo4a\fR\|(7)
.SH "AUTORZY"
.IX Header "AUTORZY"
.Vb 1
\& Nicolas François <nicolas.francois@centraliens.net>
.Ve
.SH "TŁUMACZENIE"
.IX Header "TŁUMACZENIE"
.Vb 1
\& Robert Luberda <robert@debian.org>
.Ve
.SH "PRAWA AUTORSKIE I LICENCJA"
.IX Header "PRAWA AUTORSKIE I LICENCJA"
Copyright © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.
.PP
Program jest wolnym oprogramowaniem; można go redystrybuować i/lub
modyfikować zgodnie z warunkami licencji \s-1GPL\s0 (patrz plik \s-1COPYING\s0).
