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|

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

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 $