RosettaMan(1)

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 źródła [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 różne inne parametry. Pozostałe 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 ł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 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 $