.\" {PTM/WK/1999-11}
.TH RosettaMan 1
.SH NAZWA
RosettaMan, rman - odwrotna kompilacja stron man z postaci sformatowanej
do rnych formatw rdowych
.SH SKADNIA
rman [ \fIopcje \fR] [ \fIplik \fR] 
.SH OPIS
\fIRosettaMan\fR przyjmuje strony man podrcznika systemowego z wikszoci
popularnych odmian Unixa i przeksztaca je na jeden z wielu formatw tekstu
rdowego. Uprzednio \fIRosettaMan\fR wymaga, by przed przetwarzaniem
strony zostay sformatowane przez nroff. Od wersji 3.0 \fIwoli
rda [tn]roff\fR i zwykle daje wyniki, ktre s jeszcze lepsze. Za
przetwarzanie rdowej postaci stron man jest jedyn metod tumaczenia
tabel.
.PP
W analizie rde [tn]roff powinno si zaimplementowa dowolnie duy
podzbir [tn]roff, czego nie zrobiem i nie zrobi, zatem wyniki mog by
do odlege. Zaimplementowaem jednak znaczcy podzbir uywanych
w stronach man, cznie z tbl (ale nie eqn), testami if, definicjami makr
oglnych. Wyniki zatem zwykle wygldaj doskonale. Jeli nie, sformatuj
stron przy pomocy nroff przed przesaniem jej do RosettaMan. Jeli jednak
RosettaMan nie rozpoznaje wanego makra uywanego przez liczn klas stron
man, to wylij mi e-mail ze rdem i stron sformatowan nroff-em a
zobacz, co da si zrobi. Uruchamiajc RosettaMan ze rdem strony
zawierajcym makro .so (wczanie innych albo przekierowanie
do innego rda [tn]roff), powiniene by w katalogu nadrzdnym danej
strony, gdy strony s zapisywane przy takim wanie zaoeniu. Na przykad,
jeli przeksztacasz /usr/man/man1/ls.1, to zmie uprzednio katalog na /usr/man. 
.PP
\fIRosettaMan \fR przyjmuje strony man z: 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 rdowej
dziaa dla: SunOS, Sun Solaris, Hewlett-Packard HP-UX, AT&T System 
V, OSF/1 aka Digital UNIX, DEC Ultrix. Potrafi tworzy drukowalne
tylko-ASCII (usunite znaki sterujce), tylko-nagwki-sekcji, 
Tk, TkMan, [tn]roff (tradycyjne rda stron man), SGML, HTML, 
MIME, LaTeX, LaTeX2e, RTF, Perl 5 POD. Modularna budowa umoliwia atwe
dodawanie dodatkowych formatw wyjciowych.
.PP
Najnowsza wersja RosettaMan dostpna jest zawsze z
\fIftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/rman.tar.Z\fR. 
.SH OPCJE
Ponisze dwie opcje nie powinny by uywane z innymi. Powoduj zakoczenie
pracy przez RosettaMan bez przetwarzania wejcia.
.TP
.BR -h ", " --help 
Poka list opcji wiersza polece i zakocz prac.
.TP
.BR -v ", " --version 
Poka numer wersji i zakocz prac.
.PP
\fIFiltr powiniene poda jako pierwszy, gdy ta ustawia rne inne parametry.
Pozostae opcje podaj po nim.
.TP
.BR -f ", " --filter " [" ASCII | roff | TkMan | Tk | Sections | HTML | SGML | MIME |
.RS 14
.BR LaTeX | LaTeX2e | RTF | POD ]
.RE
.RS 8
Ustaw filtr wyjcia. Domylnie jest to ASCII.
.RE
.TP
.BR -S ", " --source 
RosettaMan usiuje samoczynnie okreli czy dane wejciowe s w postaci
rdowej czy w sformatowanej; posu si t opcj do zadeklarowania wejcia
w postaci rdowej.
.TP
.BR -F ", " --format ", " --formatted 
RosettaMan usiuje samoczynnie okreli czy dane wejciowe s w postaci
rdowej czy w sformatowanej; posu si t opcj do zadeklarowania wejcia
w postaci sformatowanej.
.TP
.BR -l ", " --title " \fIacuch-printf\fR"
W trybie HTML ustawia tytu (znacznik <TITLE>) stron man, pobierajc parametry
takie jak opcja \fI-r\fR. 
.TP
.BR -r ", " --reference ", " --manref " \fIacuch-printf\fR"
W trybach HTML i SGML okrela posta URL, przy pomocy ktrej pozyskiwa
inne strony man. acuch moe uywa dwu podanych parametrw: nazwy strony
man i jej sekcji. (Zobacz sekcja Przykady.)
Jeeli acuch jest pusty (tak jak ustawiony z powoki przez "-r ''"),
ma warto `-' lub `off', to odnoniki wystpujce na stronie man nie bd
wymienione na znaczniki HREF, lecz tylko zapisane czcionk pochy (italic).
Jeli Twj printf obsuguje okrelanie pozycji XPG3, to moe to by do
elastyczne.
.\" If your printf supports XPG3 positions specifier, this can be quite flexible.
.TP
.BR -V ", " --volumes " \fI<lista rozdzielana drukropkami>\fR"
Ustawia list dozwolonych wolumenw (czci) sprawdzanych
podczas wyszukiwania powiza z innymi stronami man. Domylnie jest to
\fI1:2:3:4:5:6:7:8:9:o:l:n:p\fR (nazwy czci mog by wieloznakowe).
Jeeli po acuchu zawierajcym znaki rne od biaych znakw
wystpuje bezporednio lewy nawias, nastpnie jedna z nazw wolumenw,
za koczy si opcjonalnymi innymi znakami i prawym nawiasem -- to taki acuch
zgaszany jest jako odnonik do innej strony man. Jeli w uytej opcji -V
acuch zaczyna si od znaku rwnoci, to nie s dozwolone adne dodatkowe
znaki pomidzy dopasowan nazw wolumenu a prawym nawiasem. (Opcja ta jest
potrzebna dla SCO UNIX.)
.PP
Ponisze opcje maj zastosowanie tylko wtedy, gdy jako wejcie podano strony
sformatowane. Nie maj zastosowania lub nie zawsze s obsugiwane poprawnie
dla stron w postaci rdowej.
.TP
.BR -b ", " --subsections 
Oprcz tytuw sekcji prbuj rozpoznawa tytuy podsekcji. W niektrych
odmianach moe to powodowa kopoty.
.TP
.BR -K ", " --nobreak 
Wska, e strony man nie posiadaj amania strony, zatem nie szukaj w pobliu
stopek i nagwkw. (Starsze makra nroff -man zawsze wstawiay amanie strony,
ale ostatnio niektrzy dostawcy zauwayli, e wydruki robione s poprzez
troff, podczas gdy nroff -man suy do formatowania stron do czytania
na ekranie, a zatem usunli amanie stron.)
\fIRosettaMan \fR zwykle obsuguje t sytuacj poprawnie, nawet bez tej flagi.
.TP
.BR -k ", " --keep 
Pozostaw nagwki i stopki jako kanoniczny raport na kocu strony.
.TP
.BR -c ", " --changeleft 
Przesu changebars, takie jak znajdowane w stronach man Tcl/Tk, do lewej.
.ig
.\" Analiza poszerzona dziaa tak dobrze, e opcja --nonaggressive
.\" zostaa usunita
.TP
.BR -m ", " --nonaggressive
\fIWycz\fR poszerzon analiz stron man. Domylnie wczona, poszerzona
analiza stron podrcznika man opuszcza nagwki i stopki, identyfikacj
sekcji i inne.
..
.TP
.BR -n ", " --name " \fInazwa\fR"
Ustaw nazw strony man (uywane w formacie roff). Jeli nazw pliku podano
w postaci "\fInazwa\fB.\fIsekcja\fR", to nazwa i sekcja s okrelane
automatycznie. Jeli strona jest analizowana ze rda [tn]roff i posiada
wiersz .TH, to s one wyuskiwane z tego wiersza.
.TP
.BR -p ", " --paragraph 
Przecznik trybu akapitw. Zastosowany filtr okrela, czy wiersze powinny
by amane, tak jak zrobiby to nroff, czy te pyn razem tworzc akapity.
Gwnie do uytku wewntrznego.
.TP
.BR -s ", " section " \fI#\fR"
Ustaw numer wolumenu (czci, sekcji) strony man (uywane w formacie roff).
.\" W rdowych automatyczne, w preformatowanych tak naprawd nie dziaa
.ig
.TP
.BR -T ", " tables
Wcz poszerzon analiz tabel.
..
.TP
.BR -t ", " --tabstops " \fI#\fR"
Niektre zestawy makr uywaj, gdzie to moliwe, tabulatorw zamiast spacji
w celu zmniejszenia liczby uywanych znakw. Ta opcja ustawia pozycje
tabulacji co \fI#\fR kolumn. Domylnie co 8.
.SH UWAGI NT.TYPW FILTRW
.SS ROFF
W niektrych odmianach Unixa strony man dostarczane s bez rde [tn]roff,
czynic z Twojej drukarki laserowej niewiele wicej ni laserowo napdzan
drukark rozetkow.
Ten filtr prbuje odtworzy pierwotne dyrektywy [tn]roff, ktre nastpnie mog
by skompilowane przez [tn]roff.
.SS TkMan
TkMan, hipertekstowa przegldarka stron man, posuguje si programem
\fIRosettaMan\fR do pokazywania stron man bez, zwykle zbdnych, nagwkw
i stopek na kadej stronie. Zbiera rwnie nagwki sekcji (i opcjonalnie
podsekcji), by z rozwijalnego menu zapewni bezporedni dostp
do odpowiednich czci strony. TkMan oraz Tcl/Tk, narzdzie, w ktrym jest
on napisany, dostpne s przez anonimowe ftp z 
\fIftp://ftp.smli.com/pub/tcl/\fR
.SS Tk
Opcja ta generuje tekst w postaci serii list Tcl skadajcych si z par
tekst-znaczniki, gdzie nazwy znacznikw z grubsza odpowiadaj uywanym w HTML.
Wynik taki moe by wstawiony do tekstowego widgetu Tk przez wykonanie
\fIeval <textwidget> insert end <text>\fR.
Format ten powinien by stosunkowo atwy do analizowania przez inne programy,
ktre potrzebuj zarwno tekstu jak i znacznikw. Zobacz te ASCII.
.\" trudno stwierdzi, jaki jest format uywany przez Ensemble
.ig
.SS Ensemble
Ensemble, multimedialny edytor dokumentw strukturalnych, jest obecnie
rozwijany przez grupy badawcze profesorw Michaela A. Harrisona oraz
Susan L. Graham na University of California, Berkeley.  Przy poprawnej
strukturze i specyfikacjach prezentacji (schematy), wygld strony man moe
by znaczco zmieniony przez Ensemble.
..
.SS ASCII
Przy wydruku na drukarce wierszowej strony man usiuj uzyska specjalne
efekty tekstu przez nadpisywanie znakw ponownie tymi samymi znakami
(by otrzyma pogrubienie) czy znakami dolnej kreski (podkrelenia)
(by otrzyma pokrelenie znaku). Inne oprogramowanie przetwarzajce teksty,
jak edytory, wyszukiwarki czy programy indeksujce musi temu przeciwdziaa.
Filtr ASCII pozbywa si dodatkw z opisanego sposobu formatowania.
Przepuszczenie przez potok wyjcia z nroff do \fIcol -b\fR rwnie usuwa
takie formatowanie, ale pozostawia brzydkie nagwki i stopki stron.
Zobacz take Tk.
.SS Sections
Zrzuca tytuy sekcji i (opcjonalnie) podsekcji. Moe by przydatne dla
innego programu przetwarzajcego strony man.
.SS HTML
Przy prostym rozszerzeniu serwera HTTP dla Mosaic czy innej przegldarki
WWW [np.Netscape], \fIRosettaMan\fR moe w locie tworzy wysokiej jakoci
kod HTML. Kilka takich rozszerze i wskazanie na inne doczone s
w katalogu \fIcontrib\fR programu \fIRosettaMan\fR.
.SS SGML
Ten filtr zmierza do Docbook DTD, ale mam nadziej, e kto faktycznie
zainteresowany t opcj wygadzi tworzone znaczniki. Sprbuj, a zobaczysz,
jak blisko s one obecnie.
.SS MIME
MIME (Multipurpose Internet Mail Extensions), jak zdefiniowano w RFC 1563, 
odpowiednie do spoycia przez programy pocztowe obsugujce MIME
albo jako wzbogacone dokumenty Emacsa (>=19.26).
.SS LaTeX i LaTeX2e
Czemu nie? 
.SS RTF
Uyj wyniku na Mac-u, NeXT lub czymkolwiek. Moe we losowe strony man
i lepiej pocz je z systemem dokumentacji NeXTa. Moe NeXT ma swoje wasne
makra stron man, ktre to robi.
.SS PostScript i FrameMaker
W celu uzyskania PostScriptu uyj \fIgroff\fR lub \fIpsroff\fR.
By utworzy MIF dla FrameMakera posu si jego wbudowanym filtrem.
W obu przypadkach potrzebujesz rda \fI[tn]roff\fR, wic jeli dysponujesz
wycznie sformatowan wersj strony man, uyj najpierw filtru roff
z \fIRosettaMan\fR.
.SH PRZYKADY
Konwersja \fIsformatowanej\fR strony podrcznika man o nazwie \fIls.1\fR
na powrt do postaci rdowej [tn]roff: 
.PP
\fIrman -f roff /usr/local/man/cat1/ls.1 > /usr/local/man/man1/ls.1\fR
.PP
W celu zaoszczdzenia miejsca dugie strony man s czsto kompresowane.
Kompresja jest szczeglnie efektywna dla stron sformatowanych, gdy zawieraj
wiele spacji. Poniewa jest to duga strona, prawdopodobnie posiada podsekcje,
ktre prbujemy wydzieli (niektre zestawy makr nie wyrniaj podsekcji
wystarczajco dobrze, by \fIRosettaMan\fR je wykry). Zamiemy j na
format LaTeX-u:
.PP
\fIpcat /usr/catman/a_man/cat1/automount.z | rman -b -n automount -s 1 -f latex > automount.man\fR
.PP
Albo te:
.br
\fIman 1 automount | rman -b -n automount -s 1 -f latex > automount.man \fR
.PP
Dla uytkownikw HTML/Mosaic [czy Netscape] \fIRosettaMan\fR moe, bez zmiany
kodu rdowego, utworzy odnoniki (links) HTML do innych stron man w formacie
HTML albo utworzonych wczeniej albo w locie. Zamy najpierw, e wstpnie
stworzone wersje HTML stron man umieszczane bd w \fI/usr/man/html\fR. 
Utwrzmy je jedna po drugiej w nastpujcy sposb:
.PP
\fIrman -f html -r 'http:/usr/man/html/%s.%s.html' /usr/man/cat1/ls.1 > /usr/man/html/ls.1.html \fR
.PP
Jeeli rozszerzye swego klienta HTML tak, by tworzy kod HTML w locie, to
powiniene posuy si czym takim
.PP
\fIrman -f html -r 'http:~/bin/man2html?%s:%s' /usr/man/cat1/ls.1 \fR
.br
przy biecym tworzeniu wersji HTML stron man.
.SH BDY/NIEZGODNOCI
\fIRosettaMan\fR nie we wszystkich przypadkach jest doskonay, ale zwykle
wykonuje dobr robot, i w kadym przypadku redukuje kopot z konwersj
stron podrcznika man do niewielkich poprawek edycyjnych.
.PP
Tabele w sformatowanych stronach, szczeglnie H-P, nie s obsugiwane
najlepiej. Upewnij si, e jako parametr podajesz plik rdowy strony, co
umoliwi rozpoznanie tabel.
.PP
Przegldarka stron man o nazwie \fIwoman \fR wykorzystuje swoj wasn
koncepcj formatowania stron podrcznika systemowego. Rozwizanie to moe by
mylce dla \fIRosettaMan\fR.
Moesz omin ten problem przesyajc sformatowany tekst strony man wprost
do \fIRosettaMan\fR. 
.PP
Format wynikowy [tn]roff posuguje si fB do wczania pogrubienia (Bold).
Jeeli Twj zestaw makr wymaga .B, to bdziesz musia przetworzy
wynik z \fIRosettaMan\fR.
.SH ZOBACZ TAKE
.BR tkman (1),
.BR fIxman (1),
.BR man (1),
.BR man (7)
lub
.BR man (5)
.br
w zalenoci od swojej odmiany UNIXa.
.SH COPYRIGHT
RosettaMan 
.br
Copyright (c) 1993-1996 Thomas A. Phelps (\fIphelps@ACM.org\fR) 
.br
All Rights Reserved. 
.br
developed at the 
.br
University of California, Berkeley 
.br
Computer Science Division 
.PP
Permission to use, copy, modify, and distribute this software 
and its documentation for educational, research and non-profit 
purposes, without fee, and without a written agreement is hereby 
granted, provided that the above copyright notice and the following 
paragraph appears in all copies. 
.PP
Permission to incorporate this software into commercial products 
may be obtained from the Office of Technology Licensing, 2150 
Shattuck Avenue, Suite 510, Berkeley, CA 94704. 
.PP
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY 
PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL 
DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, 
EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE. 
.PP
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 
AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER 
IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS 
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, 
OR MODIFICATIONS. 
.PP
Manual page last updated on $Date: 2000/10/22 16:15:29 $