.\" -*- coding: UTF-8 -*-
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH PolyglotMan 1   
.SH NAZWA
PolyglotMan, rman \- odwrotna kompilacja stron podręcznika z postaci
sformatowanej do różnych formatów źródłowych: ASCII, roff, TkMan, Tk,
Sections, HTML, SGML, MIME, LaTeX, LaTeX2e, RTF, POD.
.SH SKŁADNIA
rman [ \fIopcje \fP] [ \fIplik \fP]
.SH OPIS
Najbardziej aktualną dokumentację można znaleźć pod adresem
http://polyglotman.sourceforge.net/rman.html

.PP
\fIPolyglotMan\fP przyjmuje strony man podręcznika systemowego z większości
popularnych odmian Uniksa i przekształca je na jeden z wielu formatów tekstu
źródłowego. PolyglotMan był wcześniej znany pod nazwą RosettaMan. Program
wykonywalny jest wciąż nazywa się \fIrman\fP z powodu skryptów, które mogą
zależeć od tej nazwy; można przyjąć, że nazwa ta oznacza "reverse man"
("odwrotny man"). Poprzednio \fIPolyglotMan\fP wymagał, by strony przed
przetwarzaniem zostały sformatowane przez nroff. Od wersji 3.0 \fIwoli źródła
[tn]roff\fP i zwykle daje wyniki, które są jeszcze lepsze. Przetwarzanie
źródłowej postaci stron podręcznika jest jedyną metodą tłumaczenia
tabel. Jednakże przetwarzanie źródeł nie jest tak dojrzałe jak przetwarzanie
stron sformatowanych, dlatego pomocniczo zawsze można spróbować
przetwarzania stron sformatowanych.
.PP
W analizie źródeł [tn]roff powinno się zaimplementować dowolnie duży
podzbiór [tn]roff, czego nie zrobiłem i nie zrobię, zatem wyniki mogą być
czasem niepoprawne. Zaimplementowałem jednak znaczący podzbiór poleceń
[tr]roff używanych w stronach man, łącznie z tbl (ale nie eqn), testami if
oraz definicjami makr ogólnych. Wyniki zatem zwykle wyglądają
doskonale. Jeśli nie, należy sformatować stronę przy pomocy nroff przed
przesłaniem jej do PolyglotMan. Jeśli jednak PolyglotMan nie rozpoznaje
ważnego makra używanego przez liczną klasę stron man, to proszę o wysłanie
mi e\-maila ze źródłem i stroną sformatowaną nroff\-em, a zobaczę, co da się
zrobić. Uruchamiając PolyglotMan ze źródłem strony zawierającym makro .so
(włączanie innych stron albo przekierowanie do innego źródła [tn]roff),
powinno się być w katalogu nadrzędnym danej strony, gdyż strony są
zapisywane przy takim właśnie założeniu. Na przykład przed przekształceniem
/usr/share/man/man1/ls.1 należy zmienić katalog na /usr/share/man.
.PP
\fIPolyglotMan\fP przyjmuje strony podręczników z systemów: SunOS, Sun Solaris,
Hewlett\-Packard HP\-UX, AT&T System V, OSF/1 aka Digital UNIX, DEC Ultrix,
SGI IRIX, Linux, FreeBSD, SCO. Przetwarzanie postaci źródłowej działa dla:
SunOS, Sun Solaris, Hewlett\-Packard HP\-UX, AT&T System V, OSF/1 aka Digital
UNIX, DEC Ultrix. Potrafi tworzyć  strony w formatach: "tylko drukowalne
ASCII" (usunięte znaki sterujące), "tylko nagłówki sekcji", Tk, TkMan,
[tn]roff (tradycyjne źródła stron man), XML, HTML, MIME, LaTeX, LaTeX2e,
RTF, Perl 5 POD. Modularna budowa umożliwia łatwe dodawanie dodatkowych
formatów wyjściowych.
.PP
Najnowsza wersja PolyglotMan dostępna jest zawsze pod adresem
\fIhttp://polyglotman.sourceforge.net/\fP.
.SH OPCJE
Poniższe dwie opcje nie powinny być używane z innymi. Powodują zakończenie
pracy przez PolyglotMan bez przetwarzania wejścia.
.TP  15
\-h|\-\-help 
Wyświetla listę opcji wiersza poleceń i kończy pracę.
.TP  15
\-v|\-\-version 
Wyświetla numer wersji i kończy pracę.
.PP
\fIFiltr powinno się zawsze podawać jako pierwszy parametr, gdyż ustawia on
różne inne parametry. Pozostałe opcje należy podać po nim.\fP
.TP  15
\fI\-f|\-\-filter <ASCII|roff|TkMan|Tk|Sections|HTML|XML|MIME|LaTeX|LaTeX2e|RTF|POD> \fP
Ustawia filtr wyjścia. Domyślnie jest to ASCII.
.TP  15
\-S|\-\-source 
PolyglotMan usiłuje samodzielnie określić, czy dane wejściowe są w postaci
źródłowej czy w sformatowanej; opcji tej należy użyć do zadeklarowania
wejścia w postaci źródłowej.
.TP  15
\-F|\-\-format|\-\-formatted 
PolyglotMan usiłuje samoczynnie określić czy dane wejściowe są w postaci
źródłowej czy w sformatowanej; posłuż się tą opcją do zadeklarowania wejścia
w postaci sformatowanej.
.TP  15
\-l|\-\-title \fIłańcuch\-printf\fP
W trybie HTML ustawia tytuł (znacznik <TITLE>) stron man, pobierając
parametry takie jak opcja \fI\-r\fP.
.TP  15
\-r|\-\-reference|\-\-manref \fIłańcuch\-printf\fP
W trybach HTML i XML określa postać URL, przy pomocy której będą pozyskiwane
inne strony podręcznika. Łańcuch może używać dwu podanych parametrów: nazwy
strony podręcznika i jej sekcji (zobacz rozdział "Przykłady"). Jeżeli
łańcuch jest pusty (tak jak ustawiony z powłoki przez "\fI\-r '\&'\fP"), ma
wartość "\-" lub "off", to odnośniki występujące na stronie podręcznika nie
będą zamieniane na znaczniki HREF, lecz tylko będą zapisywane czcionką
pochyłą (italic). Jeśli printf obsługuje określanie pozycji XPG3, to może to
być dość elastyczne.
.TP  15
\-V|\-\-volumes \fI<lista rozdzielana drukropkami> \fP
Ustawia listę dozwolonych wolumenów (sekcji stron podręcznika) sprawdzanych
podczas wyszukiwania powiązań z innymi stronami man. Domyślnie jest to
\fI1:2:3:4:5:6:7:8:9:o:l:n:p\fP (nazwy części mogą być wieloznakowe). Jeżeli
strona podręcznika zawiera tekst składający się z znaków niebędących
spacjami, po których bezpośrednio występują: nawias otwierający, jedna z
nazw z powyżej zdefiniowanych sekcji opcjonalnie kończąca się innymi znakami
oraz nawias zamykający \(em to taki tekst jest traktowany jako odnośnik do
innej strony podręcznika. Jeżeli w użytej opcji \-V łańcuch znaków zaczyna
się od znaku równości, to nie są dozwolone żadne dodatkowe znaki pomiędzy
dopasowaną nazwą sekcji a nawiasem zamykającym. (Opcja ta jest potrzebna dla
SCO UNIX).
.PP
Poniższe opcje mają zastosowanie tylko wtedy, gdy jako wejście podano strony
sformatowane. Nie mają zastosowania lub nie zawsze są obsługiwane poprawnie
dla stron w postaci źródłowej.
.TP  15
\-b|\-\-subsections 
Oprócz tytułów rozdziałów próbuje rozpoznawać tytuły podrozdziałów. W
niektórych odmianach może to powodować kłopoty.
.TP  15
\-K|\-\-nobreak 
Określa, że strony podręcznika nie mają łamania stron, zatem nie szuka
stopek i nagłówków. (Starsze makra "nroff \-man" zawsze wstawiały łamanie
strony, ale ostatnio niektórzy dostawcy zauważyli, że wydruki robione są
przez \fBtroff\fP(1), podczas gdy "nroff \-man" służy do formatowania stron do
czytania na ekranie, więc usunęli łamanie stron). \fIPolyglotMan\fP zwykle
obsługuje tę sytuację poprawnie, nawet bez tego znacznika.
.TP  15
\-k|\-\-keep 
Keep headers and footers, as a canonical report at the end of the
page. changeleft Move changebars, such as those found in the Tcl/Tk manual
pages, to the left. \-\-> notaggressive \fIDisable \fP aggressive man page
parsing. Aggressive manual, which is on by default, page parsing elides
headers and footers, identifies sections and more. \-\->
.TP  15
\-n|\-\-name \fInazwa\fP
Ustawia nazwę strony man (używane w formacie roff). Jeśli nazwę pliku podano
w postaci "\fInazwa\fP.\fIsekcja\fP", to nazwa i sekcja są określane
automatycznie. Jeśli strona jest analizowana ze źródła [tn]roff i zawiera
wiersz .TH, to są one wyłuskiwane z tego wiersza.
.TP  15
\-p|\-\-paragraph 
Przełącznik trybu akapitów. Zastosowany filtr określa, czy wiersze powinny
być łamane, tak jak zrobiłby to nroff, czy też płynąć razem tworząc
akapity. Głównie do użytku wewnętrznego.
.TP  15
\-s|section \fI#\fP
Set volume (aka section) number of man page (used in roff format).  tables
Turn on aggressive table parsing. \-\->
.TP  15
\-t|\-\-tabstops \fI#\fP
Niektóre zestawy makr używają, gdzie to możliwe, tabulatorów zamiast spacji
w celu zmniejszenia liczby używanych znaków. Ta opcja ustawia pozycje
tabulacji co \fI#\fP kolumn. Domyślnie co 8.
.SH "UWAGI DOTYCZĄCE TYPÓW FILTRÓW"
.SS ROFF
W niektórych odmianach Uniksa strony podręczników dostarczane są bez źródeł
[tn]roff, czyniąc z Twojej drukarki laserowej niewiele więcej niż laserowo
napędzaną drukarkę rozetkową. Ten filtr próbuje odtworzyć pierwotne
dyrektywy [tn]roff, które następnie mogą być skompilowane przez [tn]roff.
.SS TkMan
\fBTkMan\fP(1), hipertekstowa przeglądarka stron podręcznika, posługuje się
programem \fIPolyglotMan\fP do pokazywania stron podręcznika bez \(em zwykle
zbędnych \(em nagłówków i stopek na każdej stronie. Zbiera również nagłówki
rozdziałów (i opcjonalnie podrozdziałów), by z rozwijalnego menu zapewnić
bezpośredni dostęp do odpowiednich części strony. TkMan oraz Tcl/Tk,
narzędzie, w którym jest on napisany, dostępne są przez anonimowe ftp z
\fIftp://ftp.smli.com/pub/tcl/\fP.
.SS Tk
Opcja ta generuje tekst w postaci serii list Tcl składających się z par
"tekst\-znaczniki", gdzie nazwy znaczników z grubsza odpowiadają tym używanym
w HTML\-u. Wynik taki może być wstawiony do tekstowego widgetu Tk przez
wykonanie \fIeval <textwidget> insert end <text>\fP. Format ten
powinien być stosunkowo łatwy do analizowania przez inne programy, które
potrzebują zarówno tekstu, jak i znaczników. Zobacz też ASCII.
.SS ASCII
Przy wydruku na drukarce wierszowej strony man usiłują uzyskać specjalne
efekty tekstu przez nadpisywanie znaków ponownie tymi samymi znakami (by
otrzymać pogrubienie) czy znakami podkreślenia "_" (by otrzymać pokreślenie
znaku). Inne oprogramowanie przetwarzające teksty, jak edytory, wyszukiwarki
czy programy indeksujące musi temu przeciwdziałać. Filtr ASCII pozbywa się
dodatków z opisanego sposobu formatowania. Przepuszczenie przez potok
wyjścia z nroff do \fIcol \-b\fP również je usuwa. Zobacz także filtr Tk.
.SS Sections
Zrzuca tytuły rozdziałów i (opcjonalnie) podrozdziałów stron
podręcznika. Może być przydatne dla innego programu przetwarzającego strony
man.
.SS HTML
Przy prostym rozszerzeniu serwera HTTP dla \fBMosaic\fP(1) czy innej
przeglądarki WWW, \fIPolyglotMan\fP może w locie tworzyć wysokiej jakości kod
HTML. Kilka takich rozszerzeń wraz z odnośnikami do innych rozszerzeń
dołączonych jest w katalogu \fIcontrib\fP w źródłach programu \fIPolyglotMan\fP.
.SS "XML "
Ten filtr jest bliski obsługiwania Docbook DTD, ale mam nadzieję, że ktoś
faktycznie zainteresowany tą opcją wygładzi tworzone znaczniki. Spróbuj, a
zobaczysz, jak blisko są one obecnie.
.SS MIME
MIME (Multipurpose Internet Mail Extensions), jak zdefiniowano w RFC\ 1563,
odpowiednie do użycia przez programy pocztowe obsługujące MIME albo jako
wzbogacone dokumenty Emacsa (>=19.26).
.SS "LaTeX i LaTeX2e"
Czemu nie?
.SS RTF
Używa wyniku na Mac\-u, NeXT lub czymkolwiek. Może wziąć losowe strony man i
lepiej połączyć je z systemem dokumentacji NeXTa. Może NeXT ma swoje własne
makra stron man, które to robią.
.SS "PostScript i FrameMaker"
W celu uzyskania PostScriptu należy użyć \fIgroff\fP lub \fIpsroff\fP. By utworzyć
MIF dla FrameMakera, trzeba posłużyć się jego wbudowanym filtrem. W obu
przypadkach potrzebne będą źródła \fI[tn]roff\fP, więc jeśli dysponuje się
wyłącznie sformatowaną wersją strony podręcznika, należy użyć najpierw
filtru roff z \fIPolyglotMan\fP.
.SH PRZYKŁADY
Konwersja \fIsformatowanej\fP strony podręcznika man o nazwie \fIls.1\fP na powrót
do postaci źródłowej [tn]roff:
.PP
\fIrman \-f roff /usr/local/man/cat1/ls.1 > /usr/local/man/man1/ls.1\fP
.br
.PP
W celu zaoszczędzenia miejsca długie strony man są często kompresowane
(kompresja jest szczególnie efektywna dla stron sformatowanych, które
zawierają wiele spacji. Ponieważ jest to długa strona, prawdopodobnie
zawiera podrozdziały, które próbujemy wydzielić (niektóre zestawy makr nie
wyróżniają podrozdziałów w taki sposób, by \fIPolyglotMan\fP mógł je
wykryć). Skonwertujmy to na format LaTeX:
.br
.PP
\fIpcat /usr/catman/a_man/cat1/automount.z | rman \-b \-n automount \-s 1 \-f
latex > automount.man\fP
.br
.PP
Albo: \fIman 1 automount | rman \-b \-n automount \-s 1 \-f latex >
automount.man \fP
.br
.PP
Dla użytkowników HTML/Mosaic [czy Netscape] \fIPolyglotMan\fP może, bez zmiany
kodu źródłowego, utworzyć odnośniki HTML do innych stron podręcznika w
formacie HTML albo utworzonych wcześniej, albo tworzonych w locie. Załóżmy
najpierw, że wstępnie stworzone wersje HTML strony podręcznika będą
znajdować się w \fI/usr/share/man/html\fP. Utwórzmy je jedna po drugiej w
następujący sposób:
.br
\fIrman \-f html \-r 'http:/usr/share/man/html/%s.%s.html'
/usr/share/man/cat1/ls.1 > /usr/share/man/html/ls.1.html\fP
.br
.PP
Jeżeli rozszerzyłeś swego klienta HTML tak, by tworzył kod HTML w locie, to
powinieneś posłużyć się czymś takim:
.br
\fIrman \-f html \-r 'http:~/bin/man2html?%s:%s' /usr/share/man/cat1/ls.1\fP
.br
podczas generowania HTML\-a.
.SH BŁĘDY/NIEZGODNOŚCI
\fIPolyglotMan\fP nie we wszystkich przypadkach jest doskonały, ale zwykle
działa dobrze i redukuje problem konwertowania stron podręcznika ekranowego
do niewielkich poprawek edycyjnych.
.PP
Tabele w sformatowanych stronach, szczególnie H\-P, nie są obsługiwane
najlepiej. Należy się upewnić, że jako parametr przekazywany jest plik
źródłowy strony, co umożliwi rozpoznanie tabel.
.PP
Przeglądarka stron man o nazwie \fBwoman\fP(1) wykorzystuje swoją własną
koncepcję formatowania stron podręcznika systemowego. Rozwiązanie to może
być mylące dla \fIPolyglotMan\fP. Można ominąć ten problem, przesyłając
sformatowany tekst strony podręcznika wprost do \fIPolyglotMan\fP.
.PP
Format wynikowy [tn]roff posługuje się "\\fB" do włączania pogrubienia
(bold).  Jeżeli Twój zestaw makr wymaga ".B", to będziesz musiał przetworzyć
wynik z \fIPolyglotMan\fP.
.SH "ZOBACZ TAKŻE"
\fBtkman\fP(1), \fBxman\fP(1), \fBman\fP(1), \fBman\fP(7) lub \fBman\fP(5) w zależności od
odmiany Uniksa.
.SH AUTOR
PolyglotMan
.br
Thomas A. Phelps ( \fIphelps@ACM.org \fP)
.br
rozwijane w
.br
University of California, Berkeley
.br
Computer Science Division
.PP
Ostatnia aktualizacja tej strony: $Date: 1998/07/13 09:47:28 $
.PP
.SH TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są:
Wojtek Kotwica <wkotwica@post.pl>
i
Robert Luberda <robert@debian.org>
.
.PP
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach
licencji można uzyskać zapoznając się z
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License w wersji 3
.UE
lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
.PP
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy
dyskusyjnej
.MT manpages-pl-list@lists.sourceforge.net
.ME .
