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.
rman [
opcje ] [
plik ]
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/.
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.
- -f|--filter
<ASCII|roff|TkMan|Tk|Sections|HTML|XML|MIME|LaTeX|LaTeX2e|RTF|POD>
- Ustawia filtr wyjścia. Domyślnie jest to
ASCII.
- -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
- 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 Disable aggressive
man page parsing. Aggressive manual, which is on by default, page parsing
elides headers and footers, identifies sections and more. -->
- -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 #
- Set volume (aka section) number of man page (used in roff
format). tables Turn on aggressive table parsing. -->
- -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.
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(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/.
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.
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.
Zrzuca tytuły rozdziałów i (opcjonalnie)
podrozdziałów stron podręcznika. Może być
przydatne dla innego programu przetwarzającego strony man.
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.
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 (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).
Czemu nie?
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ą.
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.
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.
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.
tkman(1),
xman(1),
man(1),
man(7) lub
man(5)
w zależności od odmiany Uniksa.
PolyglotMan
Thomas A. Phelps (
[email protected] )
rozwijane w
University of California, Berkeley
Computer Science Division
Ostatnia aktualizacja tej strony: $Date: 1998/07/13 09:47:28 $
Autorami polskiego tłumaczenia niniejszej strony podręcznika
są: Wojtek Kotwica <
[email protected]> i Robert Luberda
<
[email protected]>
Niniejsze tłumaczenie jest wolną dokumentacją.
Bliższe informacje o warunkach licencji można uzyskać
zapoznając się z
GNU
General Public License w wersji 3 lub nowszej. Nie przyjmuje się
ŻADNEJ ODPOWIEDZIALNOŚCI.
Błędy w tłumaczeniu strony podręcznika prosimy
zgłaszać na adres listy dyskusyjnej
[email protected]