Provided by:
manpages-pl_20051117-1_all 
NAZWA
RosettaMan, rman - odwrotna kompilacja stron man z postaci
sformatowanej do różnych formatów źródłowych
SKŁADNIA
rman [ opcje ] [ plik ]
OPIS
RosettaMan przyjmuje strony man podręcznika systemowego z większości
popularnych odmian Unixa i przekształca je na jeden z wielu formatów
tekstu źródłowego. Uprzednio RosettaMan wymagał, by przed
przetwarzaniem strony zostały sformatowane przez nroff. Od wersji 3.0
woli rda [tn]roff i zwykle daje wyniki, które są jeszcze lepsze. Zaś
przetwarzanie źródłowej postaci stron man jest jedyną metodą
tłumaczenia tabel.
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ć dość odległe. Zaimplementowałem jednak znaczący podzbiór używanych
w stronach man, łącznie z tbl (ale nie eqn), testami if, definicjami
makr ogólnych. Wyniki zatem zwykle wyglądają doskonale. Jeśli nie,
sformatuj stronę przy pomocy nroff przed przesłaniem jej do RosettaMan.
Jeśli jednak RosettaMan nie rozpoznaje ważnego makra używanego przez
liczną klasę stron man, to wyślij mi e-mail ze źródłem i stroną
sformatowaną nroff-em a zobaczę, co da się zrobić. Uruchamiając
RosettaMan ze źródłem strony zawierającym makro .so (włączanie innych
albo przekierowanie do innego źródła [tn]roff), powinieneś być w
katalogu nadrzędnym danej strony, gdyż strony są zapisywane przy takim
właśnie założeniu. Na przykład, jeśli przekształcasz
/usr/man/man1/ls.1, to zmień uprzednio katalog na /usr/man.
RosettaMan 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 ź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ć drukowalne tylko-ASCII (usunięte
znaki sterujące), tylko-nagłówki-sekcji, Tk, TkMan, [tn]roff
(tradycyjne źródła stron man), SGML, HTML, MIME, LaTeX, LaTeX2e, RTF,
Perl 5 POD. Modularna budowa umożliwia łatwe dodawanie dodatkowych
formatów wyjściowych.
Najnowsza wersja RosettaMan dostępna jest zawsze z
ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/rman.tar.Z.
OPCJE
Poniższe dwie opcje nie powinny być używane z innymi. Powodują
zakończenie pracy przez RosettaMan bez przetwarzania wejścia.
-h, --help
Pokaż listę opcji wiersza poleceń i zakończ pracę.
-v, --version
Pokaż numer wersji i zakończ pracę.
Filtr powiniene poda jako pierwszy, gdy ta ustawia rne inne
parametry. Pozostae opcje podaj po nim.
-f, --filter [ASCII|roff|TkMan|Tk|Sections|HTML|SGML|MIME|
LaTeX|LaTeX2e|RTF|POD]
Ustaw filtr wyjścia. Domyślnie jest to ASCII.
-S, --source
RosettaMan 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 źródłowej.
-F, --format, --formatted
RosettaMan 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.
-l, --title acuch-printf
W trybie HTML ustawia tytuł (znacznik <TITLE>) stron man,
pobierając parametry takie jak opcja -r.
-r, --reference, --manref acuch-printf
W trybach HTML i SGML określa postać URL, przy pomocy której
pozyskiwać inne strony man. Łańcuch może używać dwu podanych
parametrów: nazwy strony man i jej sekcji. (Zobacz sekcja
Przykłady.) Jeżeli łańcuch jest pusty (tak jak ustawiony z
powłoki przez "-r ''"), ma wartość `-' lub `off', to odnośniki
występujące na stronie man nie będą wymienione na znaczniki
HREF, lecz tylko zapisane czcionką pochyłą (italic). Jeśli Twój
printf obsługuje określanie pozycji XPG3, to może to być dość
elastyczne.
-V, --volumes <lista rozdzielana drukropkami>
Ustawia listę dozwolonych wolumenów (części) sprawdzanych
podczas wyszukiwania powiązań z innymi stronami man. Domyślnie
jest to 1:2:3:4:5:6:7:8:9:o:l:n:p (nazwy części mogą być
wieloznakowe). Jeżeli po łańcuchu zawierającym znaki różne od
białych znaków występuje bezpośrednio lewy nawias, następnie
jedna z nazw wolumenów, zaś kończy się opcjonalnymi innymi
znakami i prawym nawiasem -- to taki łańcuch zgłaszany jest jako
odnośnik do innej strony man. Jeśli w użytej opcji -V łańcuch
zaczyna się od znaku równości, to nie są dozwolone żadne
dodatkowe znaki pomiędzy dopasowaną nazwą wolumenu a prawym
nawiasem. (Opcja ta jest potrzebna dla SCO UNIX.)
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.
-b, --subsections
Oprócz tytułów sekcji próbuj rozpoznawać tytuły podsekcji. W
niektórych odmianach może to powodować kłopoty.
-K, --nobreak
Wskaż, że strony man nie posiadają łamania strony, zatem nie
szukaj w pobliżu 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ą poprzez troff, podczas gdy
nroff -man służy do formatowania stron do czytania na ekranie, a
zatem usunęli łamanie stron.) RosettaMan zwykle obsługuje tę
sytuację poprawnie, nawet bez tej flagi.
-k, --keep
Pozostaw nagłówki i stopki jako kanoniczny raport na końcu
strony.
-c, --changeleft
Przesuń changebars, takie jak znajdowane w stronach man Tcl/Tk,
do lewej.
-n, --name nazwa
Ustaw nazwę strony man (używane w formacie roff). Jeśli nazwę
pliku podano w postaci "nazwa.sekcja", to nazwa i sekcja są
określane automatycznie. Jeśli strona jest analizowana ze źródła
[tn]roff i posiada wiersz .TH, to są one wyłuskiwane z tego
wiersza.
-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.
-s, section #
Ustaw numer wolumenu (części, sekcji) strony man (używane w
formacie roff).
-t, --tabstops #
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 # kolumn. Domyślnie co 8.
UWAGI NT.TYPÓW FILTRÓW
ROFF
W niektórych odmianach Unixa strony man 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.
TkMan
TkMan, hipertekstowa przeglądarka stron man, posługuje się programem
RosettaMan do pokazywania stron man bez, zwykle zbędnych, nagłówków i
stopek na każdej stronie. Zbiera również nagłówki sekcji (i opcjonalnie
podsekcji), 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
ftp://ftp.smli.com/pub/tcl/
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ą używanym
w HTML. Wynik taki może być wstawiony do tekstowego widgetu Tk przez
wykonanie eval <textwidget> insert end <text>. Format ten powinien być
stosunkowo łatwy do analizowania przez inne programy, które potrzebują
zarówno tekstu jak i znaczników. Zobacz też ASCII.
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 dolnej kreski
(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 col -b również usuwa takie formatowanie, ale pozostawia
brzydkie nagłówki i stopki stron. Zobacz także Tk.
Sections
Zrzuca tytuły sekcji i (opcjonalnie) podsekcji. Może być przydatne dla
innego programu przetwarzającego strony man.
HTML
Przy prostym rozszerzeniu serwera HTTP dla Mosaic czy innej
przeglądarki WWW [np.Netscape], RosettaMan może w locie tworzyć
wysokiej jakości kod HTML. Kilka takich rozszerzeń i wskazanie na inne
dołączone są w katalogu contrib programu RosettaMan.
SGML
Ten filtr zmierza do Docbook DTD, ale mam nadzieję, że ktoś faktycznie
zainteresowany tą opcją wygładzi tworzone znaczniki. Spróbuj, a
zobaczysz, jak blisko są one obecnie.
MIME
MIME (Multipurpose Internet Mail Extensions), jak zdefiniowano w RFC
1563, odpowiednie do spożycia przez programy pocztowe obsługujące MIME
albo jako wzbogacone dokumenty Emacsa (>=19.26).
LaTeX i LaTeX2e
Czemu nie?
RTF
Użyj wyniku na Mac-u, NeXT lub czymkolwiek. Może weź losowe strony man
i lepiej połącz je z systemem dokumentacji NeXTa. Może NeXT ma swoje
własne makra stron man, które to robią.
PostScript i FrameMaker
W celu uzyskania PostScriptu użyj groff lub psroff. By utworzyć MIF
dla FrameMakera posłuż się jego wbudowanym filtrem. W obu przypadkach
potrzebujesz źródła [tn]roff, więc jeśli dysponujesz wyłącznie
sformatowaną wersją strony man, użyj najpierw filtru roff z RosettaMan.
PRZYKŁADY
Konwersja sformatowanej strony podręcznika man o nazwie ls.1 na powrót
do postaci źródłowej [tn]roff:
rman -f roff /usr/local/man/cat1/ls.1 > /usr/local/man/man1/ls.1
W celu zaoszczędzenia miejsca długie strony man są często kompresowane.
Kompresja jest szczególnie efektywna dla stron sformatowanych, gdyż
zawierają wiele spacji. Ponieważ jest to długa strona, prawdopodobnie
posiada podsekcje, które próbujemy wydzielić (niektóre zestawy makr nie
wyróżniają podsekcji wystarczająco dobrze, by RosettaMan je wykrył).
Zamieńmy ją na format LaTeX-u:
pcat /usr/catman/a_man/cat1/automount.z | rman -b -n automount -s 1 -f
latex > automount.man
Albo też:
man 1 automount | rman -b -n automount -s 1 -f latex > automount.man
Dla użytkowników HTML/Mosaic [czy Netscape] RosettaMan może, bez zmiany
kodu źródłowego, utworzyć odnośniki (links) HTML do innych stron man w
formacie HTML albo utworzonych wcześniej albo w locie. Załóżmy
najpierw, że wstępnie stworzone wersje HTML stron man umieszczane będą
w /usr/man/html. Utwórzmy je jedna po drugiej w następujący sposób:
rman -f html -r 'http:/usr/man/html/%s.%s.html' /usr/man/cat1/ls.1 >
/usr/man/html/ls.1.html
Jeżeli rozszerzyłeś swego klienta HTML tak, by tworzył kod HTML w
locie, to powinieneś posłużyć się czymś takim
rman -f html -r 'http:~/bin/man2html?%s:%s' /usr/man/cat1/ls.1
przy bieżącym tworzeniu wersji HTML stron man.
BŁĘDY/NIEZGODNOŚCI
RosettaMan nie we wszystkich przypadkach jest doskonały, ale zwykle
wykonuje dobrą robotę, i w każdym przypadku redukuje kłopot z konwersją
stron podręcznika man do niewielkich poprawek edycyjnych.
Tabele w sformatowanych stronach, szczególnie H-P, nie są obsługiwane
najlepiej. Upewnij się, że jako parametr podajesz plik źródłowy strony,
co umożliwi rozpoznanie tabel.
Przeglądarka stron man o nazwie woman wykorzystuje swoją własną
koncepcję formatowania stron podręcznika systemowego. Rozwiązanie to
może być mylące dla RosettaMan. Możesz ominąć ten problem przesyłając
sformatowany tekst strony man wprost do RosettaMan.
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 RosettaMan.
ZOBACZ TAKŻE
tkman(1), fIxman(1), man(1), man(7) lub man(5)
w zależności od swojej odmiany UNIXa.
COPYRIGHT
RosettaMan
Copyright (c) 1993-1996 Thomas A. Phelps (phelps@ACM.org)
All Rights Reserved.
developed at the
University of California, Berkeley
Computer Science Division
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.
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.
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.
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.
Manual page last updated on $Date: 2000/10/22 16:15:29 $
RosettaMan(1)