Ubuntu Manpage: PolyglotMan, rman - odwrotna kompilacja stron podręcznika z postaci sformatowanej do różnych formatów

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.

SKŁADNIA

       rman [ opcje ] [ plik ]

OPIS

Najbardziej aktualną dokumentację można znaleźć pod adresem http://polyglotman.sourceforge.net/rman.html

PolyglotMan 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ę rman z powodu skryptów, które mogą zależeć od tej
nazwy; można przyjąć, że nazwa ta oznacza "reverse man" ("odwrotny man"). Poprzednio PolyglotMan wymagał,
by strony przed przetwarzaniem zostały sformatowane przez nroff. Od wersji 3.0 woli źródła [tn]roff 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.

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.

PolyglotMan 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.

Najnowsza wersja PolyglotMan dostępna jest zawsze pod adresem http://polyglotman.sourceforge.net/.

OPCJE

Poniższe dwie opcje nie powinny być używane z innymi. Powodują zakończenie pracy przez PolyglotMan bez
przetwarzania wejścia.

-h|--help Wyświetla listę opcji wiersza poleceń i kończy pracę.

-v|--version Wyświetla numer wersji i kończy pracę.

Filtr powinno się zawsze podawać jako pierwszy parametr, gdyż ustawia on różne inne parametry. Pozostałe
opcje należy podać po nim.

-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.

-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.

-l|--title łańcuch-printf
W trybie HTML ustawia tytuł (znacznik <TITLE>) stron man, pobierając parametry takie jak
opcja -r.

-r|--reference|--manref łańcuch-printf
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 "-r ''"), 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.

-V|--volumes <lista rozdzielana drukropkami>
Ustawia listę dozwolonych wolumenów (sekcji stron podręcznika) 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 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 — 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).

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 rozdziałów próbuje rozpoznawać tytuły podrozdziałów. W niektórych odmianach
może to powodować kłopoty.

-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 troff(1), podczas gdy "nroff -man" służy
do formatowania stron do czytania na ekranie, więc usunęli łamanie stron). PolyglotMan
zwykle obsługuje tę sytuację poprawnie, nawet bez tego znacznika.

-k|--keep Pozostawia nagłówki i stopki w postaci klasycznego raportu na końcu strony.

-n|--name nazwa
Ustawia 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 zawiera 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 # Ustawia numer wolumenu (części, sekcji) strony podręcznika (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 DOTYCZĄCE TYPÓW FILTRÓW

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.

TkMan
TkMan(1), hipertekstowa przeglądarka stron podręcznika, posługuje się programem PolyglotMan do
pokazywania stron podręcznika bez — zwykle zbędnych — 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 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ą tym używanym w HTML-u. 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 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ż je usuwa. Zobacz także filtr Tk.

Sections
Zrzuca tytuły rozdziałów i (opcjonalnie) podrozdziałów stron podręcznika. Może być przydatne dla innego
programu przetwarzającego strony man.

HTML
Przy prostym rozszerzeniu serwera HTTP dla Mosaic(1) czy innej przeglądarki WWW, PolyglotMan 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 contrib w źródłach programu PolyglotMan.

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.

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).

LaTeX i LaTeX2e
Czemu nie?

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ą.

PostScript i FrameMaker
W celu uzyskania PostScriptu należy użyć groff lub psroff. By utworzyć MIF dla FrameMakera, trzeba
posłużyć się jego wbudowanym filtrem. W obu przypadkach potrzebne będą źródła [tn]roff, więc jeśli
dysponuje się wyłącznie sformatowaną wersją strony podręcznika, należy użyć najpierw filtru roff z
PolyglotMan.

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,  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 PolyglotMan mógł je wykryć). Skonwertujmy to na format LaTeX:

       pcat /usr/catman/a_man/cat1/automount.z | rman -b -n automount -s 1 -f latex > automount.man

       Albo: man 1 automount | rman -b -n automount -s 1 -f latex > automount.man

       Dla  użytkowników  HTML/Mosaic  [czy  Netscape]  PolyglotMan  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
       /usr/share/man/html. Utwórzmy je jedna po drugiej w następujący sposób:
       rman     -f     html     -r     'http:/usr/share/man/html/%s.%s.html'     /usr/share/man/cat1/ls.1      >
       /usr/share/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/share/man/cat1/ls.1
       podczas generowania HTML-a.

BŁĘDY/NIEZGODNOŚCI

       PolyglotMan  nie  we  wszystkich  przypadkach jest doskonały, ale zwykle działa dobrze i redukuje problem
       konwertowania stron podręcznika ekranowego do niewielkich poprawek edycyjnych.

       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.

       Przeglądarka  stron  man  o  nazwie  woman(1)  wykorzystuje  swoją  własną  koncepcję  formatowania stron
       podręcznika systemowego. Rozwiązanie to może być  mylące  dla  PolyglotMan.  Można  ominąć  ten  problem,
       przesyłając sformatowany tekst strony podręcznika wprost do PolyglotMan.

       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 PolyglotMan.

ZOBACZ TAKŻE

       tkman(1), xman(1), man(1), man(7) lub man(5) w zależności od odmiany Uniksa.

AUTOR

       PolyglotMan
       Thomas A. Phelps ( phelps@ACM.org )
       rozwijane w
       University of California, Berkeley
       Computer Science Division

       Ostatnia aktualizacja tej strony: $Date: 1998/07/13 09:47:28 $

TŁUMACZENIE

       Autorami  polskiego  tłumaczenia  niniejszej  strony   podręcznika   man   są:   Wojtek   Kotwica   (PTM)
       <wkotwica@post.pl> i Robert Luberda <robert@debian.org>.

       Polskie  tłumaczenie  jest  częścią  projektu  manpages-pl;  uwagi,  pomoc,  zgłaszanie błędów na stronie
       http://sourceforge.net/projects/manpages-pl/. Jest zgodne z wersją  3.2 oryginału.

                                                                                                  PolyglotMan(1)