.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "LOCALE::PO4A::TEX.3PM 1" .TH LOCALE::PO4A::TEX.3PM 1 2025-11-22 "perl v5.42.0" "User Contributed Perl Documentation" .\" 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 \- convert TeX documents and derivatives from/to PO files .SH OPIS .IX Header "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. .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 There are some options (described in the next section) that can customize this behavior. If this doesn\*(Aqt fit to your document format you\*(Aqre encouraged to write your own derivative module from this, to describe your format\*(Aqs details. See the section \fBWRITING DERIVATE MODULES\fR below, for the process description. .PP This module can also be customized by lines starting with "% po4a:" in the TeX file. This process is described in the \fBINLINE CUSTOMIZATION\fR section. .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 \&\fBDOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU Ź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 Use these options to override the default behavior of the defined commands. .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" This describes in detail the parameters of the \fIcommand1\fR command. This information will be used to check the number of arguments and their types. .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 (+)" As for an asterisk, the command will be extracted if it appear at an extremity of a block, but the parameters won\*(Aqt be translated separately. The translator will have to translate the command concatenated to all its parameters. This keeps more context, and is useful for commands with small words in parameter, which can have multiple meanings (and translations). .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 The \fIparameters\fR argument is a set of [] (to indicate an optional argument) or {} (to indicate a mandatory argument). You can place an underscore (_) between these brackets to indicate that the parameter must be translated. For example: % po4a: command *chapter [_]{_} .Sp This indicates that the chapter command has two parameters: an optional (short title) and a mandatory one, which must both be translated. If you want to specify that the href command has two mandatory parameters, that you don\*(Aqt want to translate the URL (first parameter), and that you don\*(Aqt want this command to be separated from its paragraph (which allow the translator to move the link in the sentence), you can use: % 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 defines the parameters accepted by the \fIenv\fR environment and specifies the ones to be translated. This information is later used to check the number of arguments of the \&\ebegin command. 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. .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 The regular expression is delimited by quotes. It should not create any back\-reference. You should use (?:) if you need a group. It may also need some escapes. .Sp Na przykład moduł LaTeX używa wyrażenia regularnego "(?:&|\e\e\e\e)" , aby osobno przetłumaczyć każdą komórkę tabeli (linie są rozdzielone przez \*(Aq\e\e\*(Aq a komórki przez \*(Aq&\*(Aq). .Sp The notion of environment is expanded to the type displayed in the PO file. This can be used to split on "\e\e\e\e" in the first mandatory argument of the title command. In this case, the environment is 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 PO 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ć "*". 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 "{" (dla argumentów wymaganych), albo "[" (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 "% po4a: ". .Sp Dalsze informacje można znaleźć w sekcji \fBDOSTOSOWYWANIE ZA POMOCĄ OPCJI W PLIKU Ź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 uses the information specified by register_generic_command or by adding definition to the TeX file: % po4a: command \fIcommand1\fR \fIparameters\fR .PP generic_environment uses the information specified by register_generic_environment or by adding definition to the TeX file: % po4a: environment \fIenv\fR \fIparameters\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." These commands should be specified by couples. This can be used to specify commands beginning or ending a verbatim environment. .IP Inne 4 .IX Item "Inne" Różne inne punkty są oznaczone w źródłach jako "TODO", czyli do zrobienia. .SH "ZNANE BŁĘDY" .IX Header "ZNANE BŁĘDY" Różne punkty są oznaczone w źródłach jako "FIXME", 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 .Ve .SH TŁUMACZENIE .IX Header "TŁUMACZENIE" .Vb 1 \& Robert Luberda .Ve .SH "PRAWA AUTORSKIE I LICENCJA" .IX Header "PRAWA AUTORSKIE I LICENCJA" Copyright © 2004, 2005 Nicolas FRANÇOIS . .PP 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).