.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Man 3pm"
.TH Locale::Po4a::Man 3pm "2018-12-17" "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::Man \- konwersja stron podręcznika 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::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].
.SH "TŁUMACZENIE Z POMOCĄ PO4A::MAN"
.IX Header "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.
.SS "Zawijanie tekstu"
.IX Subsection "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 czasami groff zachowuje dwie spacje występujące po
nawiasie.
.PP
Tak czy owak, różnica będzie dotyczyła tylko rozmieszczenia dodatkowych
spacji w zawiniętym tekście akapitu.
.SS "Określanie czcionki"
.IX Subsection "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 \s-1POD \s0(formatu dokumentacji
Perla):
.IP "I<tekst> \*(-- kursywa" 4
.IX Item "I<tekst> kursywa"
odpowiednik \efItekst\efP lub \*(L".I tekst\*(R"
.IP "B<tekst> \*(-- tekst wytłuszczony" 4
.IX Item "B<tekst> tekst wytłuszczony"
odpowiednik \efBtekst\efP lub \*(L".B tekst\*(R"
.IP "R<tekst> \*(-- tekst zwykłą czcionką" 4
.IX Item "R<tekst> tekst zwykłą czcionką"
odpowiednik \efRtekst\efP
.IP "CW<tekst<gt> \*(-- tekst o stałej szerokości" 4
.IX Item "CW<tekst<gt> tekst o stałej szerokości"
odpowiednik \ef(CWtekst\efP lub \*(L".CW tekst\*(R"
.PP
Uwaga: \s-1CW\s0 nie jest dostępne dla wszystkich urządzeń groffa. Używanie go nie
jest zalecane. Jest dostarczone dla wygody użytkownika.
.SS "Automatyczna transliteracja znaków"
.IX Subsection "Automatyczna transliteracja znaków"
Po4a automatycznie zamienia niektóre znaki, aby ułatwić tłumaczenia lub
przeglądanie tłumaczeń. Lista takich transliteracji:
.IP "łączniki" 4
.IX Item "łączniki"
Łączniki (\-) i znaki minusa (\e\-) w stronach podręcznika ekranowego są
wszystkie transliterowane do zwykłych myślników (\-) w pliku \s-1PO.\s0 Kiedy
tłumaczenia są zapisywane w pliku wynikowym wszystkie myślniki są zamieniane
na znaki minusa (\e\-).
.Sp
Tłumacze mogą wymusić wstawienie łącznika, używając w swoich tłumaczeniach
kodu \*(L"\e[hy]\*(R" groffa.
.IP "spacje nierozdzielające" 4
.IX Item "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 (\*(L"\e \*(R").
.IP "transliteracje cudzysłowów" 4
.IX Item "transliteracje cudzysłowów"
`` i '' są odpowiednio zamieniane na \e*(lq i \e*(rq.
.Sp
Aby uniknąć tych transliteracji, tłumacze mogą umieścić zerowej szerokości
znak roffa (np. używając odpowiednio `\e&` lub '\e&').
.ie n .SS "Wstawianie ""<"" i "">"" w tłumaczeniach"
.el .SS "Wstawianie ``<'' i ``>'' w tłumaczeniach"
.IX Subsection "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 \s-1POD,\s0 po raz kolejny).
.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 "\fBverbose\fR" 4
.IX Item "verbose"
Zwiększa gadatliwość.
.IP "\fBgroff_code\fR" 4
.IX Item "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:
.RS 4
.IP "\fIfail\fR" 4
.IX Item "fail"
Jest to domyślna wartość. Działanie modułu zakończy się błędem, jeżeli
zostanie napotkana sekcja .de, .ie lub .if.
.IP "\fIverbatim\fR" 4
.IX Item "verbatim"
Określa, że sekcje .de, .ie lub .if muszą być skopiowane bez zmian z
oryginału do tłumaczonego dokumentu.
.IP "\fItranslate\fR" 4
.IX Item "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 \fIverbatim\fR.
.RE
.RS 4
.RE
.IP "\fBgenerated\fR" 4
.IX Item "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.
.IP "\fBmdoc\fR" 4
.IX Item "mdoc"
Ta opcja jest użyteczna tylko dla stron w formacie mdoc.
.Sp
Wybiera dokładniejszą obsługę formatu mdoc, nakazuję po4a nietłumaczenie
sekcji \*(L"\s-1NAME\*(R" \s0(\s-1NAZWA\s0). Strony mdoc, zawierające przetłumaczoną sekcję
\&\*(L"\s-1NAME\*(R",\s0 nie generują nagłówka ani stopki.
.Sp
Zgodnie ze stroną podręcznika groff_mdoc, wymagane są sekcje \s-1NAME \s0(\s-1NAZWA\s0),
\&\s-1SYNOPSIS \s0(SKŁADNIA)oraz \s-1DESCRIPTION \s0(\s-1OPIS\s0).
Chociaż nie ma żadnych znanych problemów z przetłumaczonymi sekcjami \s-1SYNOPSIS\s0
czy \s-1DESCRIPTION,\s0 to ich tłumaczenie można również pominąć za pomocą:
 \-o mdoc=NAME,SYNOPSIS,DESCRIPTION
.Sp
Kwestię mdoc można także rozwiązać, używając załącznika podobnego do poniższego:
 PO4A\-HEADER:mode=before;position=^.Dd
 .TH \s-1DOCUMENT_TITLE 1 \s0\*(L"Month day, year\*(R" \s-1OS \s0\*(L"Section Name\*(R"
.PP
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:
.PP
.Vb 1
\& \-o noarg=FO,OB,AR \-o translate_joined=BA,ZQ,UX
.Ve
.PP
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.
.IP "\fBuntranslated\fR" 4
.IX Item "untranslated"
\&\fBuntranslated\fR oznacza, że to makro (i wszystkie jego argumenty) nie muszą
być tłumaczone.
.IP "\fBnoarg\fR" 4
.IX Item "noarg"
\&\fBnoarg\fR jest jak \fBuntranslated\fR, poza tym, że po4a sprawdzi, że do tego
makra nie dodano żadnego argumentu.
.IP "\fBtranslate_joined\fR" 4
.IX Item "translate_joined"
\&\fBtranslate_joined\fR oznacza, że po4a musi zaproponować tłumaczenie
argumentów makra.
.IP "\fBtranslate_each\fR" 4
.IX Item "translate_each"
\&\fBtranslate_each\fR powoduje, że argumenty będą także zaproponowane do
tłumaczenia, z tym że każdy z nich będzie przetłumaczony osobno.
.IP "\fBno_wrap\fR" 4
.IX Item "no_wrap"
Opcja przyjmuje jako argument rozdzieloną przecinkami listę par
\&\fIpoczątek\fR:\fIkoniec\fR, gdzie \fIpoczątek\fR i \fIkoniec\fR są poleceniami
ograniczającymi początek i koniec sekcji, której tekst nie powinien być
ponownie zawijany.
.Sp
Uwaga: nie jest sprawdzane, czy polecenie \fIend\fR ma odpowiadające polecenie
\&\fIbegin\fR; jakiekolwiek polecenie kończące zatrzyma tryb no_wrap. Jeżeli
istnieje makro \fIbegin\fR (odpowiednio \fIend\fR) nie mające pasującego \fIend\fR
(odpowiednio \fIbegin\fR), to można podać istniejące \fIend\fR (jak fi) lub
\&\fIbegin\fR (jak nf) jako zamiennik. Makra te (i ich argumenty) nie będą
tłumaczone.
.IP "\fBinline\fR" 4
.IX Item "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ł \fIfoo <.bar baz qux> quux\fR, gdzie \fIbar\fR jest poleceniem,
które powinno być włączone do pliku, a \fIbaz qux\fR \- jego argumentami.
.IP "\fBunknown_macros\fR" 4
.IX Item "unknown_macros"
Ta opcja określa zachowanie po4a po napotkaniu nieznanego makra. Domyślnie
po4 kończy działanie z błędem i wyświetla stosowny komunikat. Możliwe są
następujące wartości: \fIfailed\fR (wartość domyślna), \fIuntranslated\fR,
\&\fInoarg\fR, \fItranslate_joined\fR, \fItranslate_each\fR (patrz objaśnienia
powyżej).
.SH "PISANIE STRON PODRĘCZNIKA ZGODNYCH Z PO4A::MAN"
.IX Header "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.
.PP
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ą.
.SS "Nie programuj w nroffie"
.IX Subsection "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).
.SS "Używaj prostego zbioru makr"
.IX Subsection "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.
.PP
.Vb 11
\& ..               ."              .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
.Ve
.SS "Ukrywanie tekstu przez po4a"
.IX Subsection "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 \fIother\fR oraz \fIother\fR może się także pojawić jako
ostatni element listu. Pierwsze \fIother\fR nie powinno być tłumaczone, a
drugie \- powinno.
.PP
W takim przypadku, aby po4a pominęło takie komunikaty, autor może użyć
specjalnych konstrukcji groffa:
.PP
.Vb 1
\& .if !\*(Aqpo4a\*(Aqhide\*(Aq .B other
.Ve
.PP
(wymaga to podania opcji \fB\-o groff_code=verbatim\fR)
.PP
Aby to zautomatyzować, można zdefiniować nowe makro:
\&.de IR_untranslated
 .    \s-1IR\s0 \e\e$@
 ..
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
(wymaga to podania opcji \fB\-o groff_code=verbatim\fR i \fB\-o
untranslated=IR_untranslated\fR; przy tej konstrukcji warunek \fB.if
!'po4a'hide'\fR staje się zbędny, ponieważ po4a nie przetwarza wnętrza
definicji makra)
.PP
lub używając aliasu:
 .als IR_untranslated \s-1IR\s0
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
Wymaga to podania opcji \fB\-o untranslated=als,IR_untranslated\fR.
.SS "Wniosek"
.IX Subsection "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 \ec 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.
.PP
Of course, another possibility is to use another format, more translator
friendly (like \s-1POD\s0 using po4a::pod, or one of the \s-1XML\s0 family like \s-1SGML\s0), but
thanks to po4a::man it isn't needed anymore. That being said, if the source
format of your documentation is \s-1POD,\s0 or \s-1XML,\s0 it may be clever to translate
the source format and not this generated one. In most cases, po4a::man will
detect generated pages and issue a warning. It will even refuse to process
\&\s-1POD\s0 generated pages, because those pages are perfectly handled by po4a::pod,
and because their nroff counterpart defines a lot of new macros I didn't
want to write support for. On my box, 1432 of the 4323 pages are generated
from \s-1POD\s0 and will be ignored by po4a::man.
.PP
In most cases, po4a::man will detect the problem and refuse to process the
page, issuing an adapted message. In some rare cases, the program will
complete without warning, but the output will be wrong. Such cases are
called \*(L"bugs\*(R" ;) If you encounter such case, be sure to report this, along
with a fix when possible…
.SH "STATUS MODUŁU"
.IX Header "STATUS MODUŁU"
Modułu można używać z większością istniejących stron podręcznika.
.PP
Niektóre testy są regularnie uruchamiane na komputerach z Linuksem:
.IP "\(bu" 4
odrzucono jedną trzecią stron ponieważ były one wygenerowane z innego
formatu obsługiwanego przez po4a (np. \s-1POD\s0 lub \s-1SGML\s0).
.IP "\(bu" 4
10% pozostałych stron odrzucono z powodu błędu (np. nieobsługiwane makro
groff).
.IP "\(bu" 4
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).
.IP "\(bu" 4
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).
.SH "ZOBACZ TAKŻE"
.IX Header "ZOBACZ TAKŻE"
\&\fILocale::Po4a::Pod\fR\|(3pm), \fILocale::Po4a::TransTractor\fR\|(3pm),
\&\fIpo4a\fR\|(7)
.SH "AUTORZY"
.IX Header "AUTORZY"
.Vb 3
\& Denis Barbier <barbier@linuxfr.org>
\& Nicolas François <nicolas.francois@centraliens.net>
\& Martin Quinson (mquinson#debian.org)
.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 © 2002\-2008 \s-1SPI,\s0 Inc.
.PP
Program jest wolnym oprogramowaniem; można go redystrybuować i/lub
modyfikować zgodnie z warunkami licencji \s-1GPL \s0(patrz plik \s-1COPYING\s0).