Provided by: manpages-pl_0.5-1_all bug

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.

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