Ubuntu Manpage: PolyglotMan, rman - odwrotna kompilacja stron podręcznika z postaci sformatowanej do

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)