NAZWA

       man - makra do formatowania stron man

SKŁADNIA

       groff -Tascii -man plik ...

       groff -Tps -man plik ...

       man [sekcja] tytuł

OPIS

       Ta  strona  podręcznika  opisuje  pakiet makr groff an.tmac (często nazywany pakietem makr
       man). Pakiet tych makr powinien być używany przez deweloperów, kiedy piszą  lub  przenoszą
       strony  man  dla  Linuksa.  Jest w pełni kompatybilny z innymi wersjami tego pakietu, więc
       przenoszenie stron nie powinno być głównym problemem (wyjątki włączają  NET-2  BSD,  które
       używa całkiem innego pakietu makr zwanego mdoc; patrz mdoc(7)).

       Proszę  zauważyć,  że strony NET-2 BSD mogą być użyte z groffem przez proste podanie opcji
       -mdoc zamiast zwykłej -man.  Jednakże  bardziej  zalecane  jest  używanie  opcji  -mandoc,
       ponieważ wybierze ona automatycznie odpowiedni zestaw makr.

       Zasady, których powinno się przestrzegać podczas pisania stron podręcznika dla linuksowego
       pakietu man-pages, opisano w man-pages(7).

   Linia tytułowa
       Pierwszą komendą na stronie man (po liniach komentarza, czyli liniach zaczynających się od
       .\") powinna być

              .TH tytuł sekcja data źródło podręcznik

       Szczegółowy opis argumentów przekazywanych do komendy TH można znaleźć w man-pages(7).

       Proszę  zauważyć,  że  strony  formatowane  za  pomocą  makr  BSD mdoc rozpoczynają się od
       polecenia Dd, a nie TH.

   Sekcje
       Sekcje zaczynają się od .SH poprzedzonego przez nazwę sekcji.

       Jedynym wymaganym nagłówkiem jest NAME (NAZWA). Powinien występować w pierwszej sekcji,  a
       kolejna linia powinna zawierać jednoliniowy opis programu:

              .SH NAZWA
              pozycja \- opis

       Jest niesamowicie ważne, aby używać tego formatu, oraz że występuje odwrotny ukośnik przed
       kreską  po  nazwie  pozycji.  Ta  składnia  (angielska,  gdzie  NAZWA   to   NAME)    jest
       wykorzystywana  przez  program  mandb(8)  do  tworzenia  bazy krótkich opisów dla programu
       whatis(1) i apropos(1). (Dalsze szczegóły dotyczące składni rozdziału NAME można znaleźć w
       podręczniku lexgrog(1)).

       Listę   innych  sekcji,  które  mogą  wystąpić  w  stronie  podręcznika  można  znaleźć  w
       man-pages(7).

   Czcionki
       Komendy do wyboru czcionki są następujące:

       .B  Pogrubienie

       .BI Pogrubienie na przemian z kursywą (szczególnie użytecznie w specyfikacji funkcji)

       .BR Pogrubienie na przemian z czcionką  Roman  (szczególnie  użyteczne  w  odnośnikach  do
           innych stron podręcznika)

       .I  Kursywa

       .IB Kursywa naprzemiennie z pogrubieniem

       .IR Kursywa naprzemiennie z fontem roman

       .RB Czcionka roman naprzemiennie z pogrubieniem

       .RI Czcionka roman naprzemiennie z kursywą

       .SB Mała czcionka naprzemiennie z pogrubieniem

       .SM Mała (użyteczne dla akronimów)

       Tradycyjnie,  każda  komenda  może  mieć do sześciu argumentów, lecz wersja GNU wydaje się
       znosić to ograniczenie (wciąż jednak można rozważyć wprowadzenie  limitu  6  argumentów  w
       celu  zachowania  kompatybilności). Argumenty są oddzielane spacjami.  Podwójne cudzysłowy
       mogą być używane  do  określania  argumentów  ze  spacjami.  Wszystkie  argumenty  zostaną
       wydrukowane  obok  siebie,  bez wtrąconych spacji, tak że komenda .BR może zostać użyta do
       podania słowa pogrubionego, po którym  następuje  znak  interpunkcyjny  zapisany  czcionką
       roman.  Jeżeli  nie  podano  żadnych  argumentów,  polecenie  stosuje  się do linii tekstu
       następującej po nim.

   Inne makra i łańcuchy znaków
       Poniżej przedstawiono inne makra i  predefiniowane  łańcuchy  znaków.  Jeżeli  nie  podano
       inaczej,  wszystkie  makra  powodują  przerwę (zakończenie bieżącej linii tekstu). Wiele z
       tych makr ustawia lub używa wartości "powszechnego wcięcia".  Wartość  ta  jest  ustawiana
       przez  każde  makro  przyjmujące  parametr  i; makra mogą pomijać i, co oznacza, że będzie
       używana bieżąca wartość "powszechnego wcięcia". W wyniku tego kolejne wcięte akapity  mogą
       używać  tej  samej  wartości  wcięcia  bez jej każdorazowego podawania. Zwykły (niewcięty)
       akapit ustawia wcięcie na  jego  domyślną  wartość  (0.5  cala).  Domyślnie  wcięcie  jest
       wyrażone  w  "ens"  [szerokość  litery  "n"];  zaleca  się  używanie  "ens" lub "ems" jako
       jednostek wcięcia, ponieważ automatycznie dostosują się do zmian rozmiaru  czcionki.  Inne
       kluczowe definicje makr są następujące:

   Zwykłe akapity
       .LP      To samo, co .PP (rozpoczęcie nowego akapitu).

       .P       To samo, co .PP (rozpoczęcie nowego akapitu).

       .PP      Rozpoczęcie nowego akapitu i usunięcie bieżącego wcięcia.

   Początek wiszącego wcięcia
       .RS i    Rozpoczyna  relatywne  wcięcie  marginesu:  przesuwa  lewy  margines  o i w prawo
                (jeżeli pominięto i, to używana jest  wartość  "powszechnego  wcięcia").  Wartość
                "powszechnego  wcięcia"  ustawiana  na  0.5 cala. W wyniku wcinane będą wszystkie
                kolejne akapity, aż do napotkania odpowiadającego .RE.

       .RE      Kończy relatywne wcięcie marginesu i ustawia poprzednią wartość wcięcia.

   Makra wcięć akapitów
       .HP i    Rozpoczyna akapit od wiszącego wcięcia (pierwsza linia akapitu znajduje się  przy
                lewym  marginesie  w  stosunku do zwykłych akapitów, a pozostałe akapitu linie są
                wcięte).

       .IP x i  Wcięty akapit z opcjonalnym wiszącym znacznikiem. Jeżeli pominięto znacznik x, to
                cały następujący akapit będzie wcięty o i. Jeżeli podano znacznik x, to będzie on
                umieszczony zaraz  przy  lewym  marginesie  przed  następującym  po  nim  wciętym
                akapitem  (podobnie  jak  to robi .TP poza tym, że znacznik jest umieszczony przy
                poleceniu, a nie w kolejnej linii). Jeżeli znacznik jest zbyt długi to  tekst  po
                znaczniku  będzie  przeniesiony  do kolejnej linii (tekst nie będzie usunięty ani
                zniekształcony). Dla list nienumerowanych, należy użyć tego makra,  podając  jako
                znacznik  \(bu  (kula)  lub  \(em  (myślnik),  a  dla  list numerowanych należy w
                znaczniku  podać  liczbę  lub  cyfrę,  po  której  następuje  kropka;  ułatwi  to
                przetworzenie do innych formatów.

       .TP i    Rozpoczyna  akapit  z  wiszącym  znacznikiem.  Znacznik jest podawany w następnej
                linii.  Wyniki są podobne do .IP

   Makra odnośników hipertekstowych
       (Cecha obsługiwana tylko przez groffa). Aby użyć  makr  łączy  hipertekstowych,  potrzebne
       jest załadowanie pakietu makr www.tmac. Aby to zrobić, należy użyć żądania .mso www.tmac.

       .URL url link trailer
                Wstawia  odnośnik  hipertekstowy  do  lokalizacji  URI  (URL) url, z linkiem jako
                tekstem odnośnika, a zaraz po nim  będzie  wypisany  trailer.  Generując  HTML-a,
                powinno   się   to   przetłumaczyć   jako   następujące   polecenie   HTML-a:  <A
                HREF="url">link</A>trailer.

                To i inne podobne makra są nowe, tak więc wiele narzędzi ich nie  obsługuje,  ale
                ponieważ  wiele narzędzi (włącznie z troffem) po prostu zignoruje niezdefiniowane
                makra (albo w gorszym przypadku wstawi własny tekst), więc można ich  bezpiecznie
                używać.

                Może  być  użyteczne  zdefiniowanie  własnego  makra  URL  w stronach podręcznika
                ekranowego, aby dać możliwość oglądania ich w programach innych  niż  groff.  Tym
                sposobem URL, tekst odnośnika i podpisu będzie widoczny.

                Oto przykład:
                      .de URL
                      \\$2 \(laURL: \\$1 \(ra\\$3
                      ..
                      .if \n[.g] .mso www.tmac
                      .TH ...
                      (później na stronie)
                      Ten program pochodzi z
                      .URL "http://www.gnu.org/" "Projektu GNU" " z"
                      .URL "http://www.fsf.org/" "Free Software Foundation" .

                W powyższym przypadku, jeśli używany jest groff, to definicja makra URL z pakietu
                www.tmac nadpisze makro zdefiniowane lokalnie.

       Dostępna są także inne makra dla odnośników. Patrz groff_www(7) po dalsze informacje.

   Różnorodne makra
       .DT      Ustawia tabulację na jej domyślną wartość  (co  każde  pół  cala);  nie  powoduje
                przerwy.

       .PD d    Ustawia  odległość  między wierszami w akapicie (jeśli pominięto, to d=0.4v); nie
                powoduje przerwy.

       .SS t    Pod-nagłówek t (jak .SH, lecz używane do podsekcji)

   Predefiniowane łańcuch znaków
       Pakiet man zawiera następujące predefiniowane łańcuchy znaków:

       \*R    Symbol rejestracji: ®

       \*S    Zmienia domyślny rozmiar czcionki

       \*(Tm  Symbol znaku towarowego: ™

       \*(lq  Lewy podwójny cudzysłów: “

       \*(rq  Prawy podwójny cudzysłów: ”

   Bezpieczny podzbiór
       Chociaż z technicznego punktu widzenia man jest pakietem makr troffa, to w  rzeczywistości
       strony podręcznika ekranowego mogą być przetwarzane przez wiele innych narzędzi, które nie
       implementują wszystkich właściwości troffa.  Dlatego  najlepiej  unikać  pewnych  bardziej
       egzotycznych  makr  troffa,  tam  gdzie  jest to możliwe tak, aby inne narzędzia pracowały
       poprawnie. Należy unikać używania preprocesorów troffa (jeżeli jest to  konieczne,  proszę
       bardzo,  użyj  tbl(1),  ale zamiast tworzyć dwukolumnowe tabele, spróbuj użyć poleceń IP i
       TP). Należy unikać także używania wyliczeń  —  większość  innych  narzędzi  nie  umie  ich
       przetworzyć.  Lepiej użyć prostych poleceń, łatwych do przetłumaczenia do innych formatów.
       Następujące makra troffa uważa  się  za  bezpieczne  (chociaż  w  wielu  przypadkach  będą
       zignorowane  przez  tłumaczy):  \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig,
       in, na, ne, nf, nh, ps, so, sp, ti, tr.

       Można także używać wielu sekwencji cytowania (czyli sekwencji zaczynających się od \). Aby
       użyć  znaku  odwrotnego ukośnika w zwykłym tekście, należy wpisać \e. Do innych sekwencji,
       których można użyć, należą (x i xx są zwykłymi znakami, a N — dowolną liczbą): \', \`, \-,
       \.,  \",  \%,  \*x,  \*(xx,  \(xx, \$N, \nx, \n(xx, \fx oraz \f(xx. Należy unikać używania
       sekwencji cytowania do rysowania grafiki.

       Nie należy używać nieobowiązkowego parametru makra  bp  (podział  strony).  Należy  używać
       tylko dodatnich wartości dla sp (spacja pionowa). Nie należy definiować makr (de) o takich
       samych nazwach jak nazwy makr z tego pakietu lub z pakietu mdoc, ale  o  innym  znaczeniu;
       jest  wysoce  prawdopodobne,  że  takie  powtórne  zdefiniowanie  makra  będzie  po prostu
       zignorowane. Każde dodatnie  wcięcie  (in)  powinno  być  sparowane  z  odpowiadającym  mu
       wcięciem  negatywnym  (chociaż  powinno  się  jednak  używać  makr  RS  i  RE zamiast in).
       Instrukcje warunkowe (if,ie) powinny mieć tylko "t" lub "n" w warunku. Powinny być używane
       tylko  tłumaczenia  (tr),  które  można  zignorować.  Zmiany  czcionki  (ft oraz sekwencja
       cytowania \f) powinny mieć tylko wartości 1, 2, 3, 4, R, I, B, P lub CW (polecenie ft może
       także nie mieć żadnych parametrów).

       Jeżeli  używane  są  makra  inne niż te opisane powyżej, należy dokładnie sprawdzić wynik,
       używając kilku narzędzi. Po sprawdzeniu, że te dodatkowe makra są  bezpieczne,  prosimy  o
       poinformowanie o nich opiekuna tego dokumentu, tak żeby można było je dodać do tej listy.

PLIKI

       /usr/share/groff/[*/]tmac/an.tmac
       /usr/man/whatis

UWAGI

       W  każdym  wypadku  należy  włączać  pełne  URL-e  (lub  URI)  do  samego tekstu; niektóre
       narzędzia, takie jak man2html(1) potrafią automatycznie  przekształcić  je  na  odnośniki.
       Można  także  używać  nowego  makra URL, aby wprowadzić informacje związane z odnośnikami.
       Podczas   podawania    URL-i,    należy    używać    ich    w    pełnej    postaci    (np.
       ⟨http://www.kernelnotes.org⟩) , żeby narzędzia mogły je automatycznie znaleźć.

       Narzędzia  przetwarzające  pliki  powinny  otworzyć  plik i sprawdzić zawartość pierwszego
       znaku nie będącego białą spacją. Kropka (.) lub pojedynczy cudzysłów (') na początku linii
       oznacza  plik oparty na troffie (taki jak man lub mdoc). Lewy nawias trójkątny (<) oznacza
       plik oparty na SGML/XML-u (taki jak HTML lub Docbook). Wszystko inne oznacza zwykły  tekst
       ASCII (np. wynik "catman").

       Wiele  stron podręcznika rozpoczyna się od ´\", po którym następuje spacja i lista znaków,
       określających preprocesor, używany do przetwarzania strony.  Dla  zachowania  zgodności  z
       innymi  narzędziami,  zalecamy,  aby  unikać  preprocesorów innych niż tbl(1), który Linux
       wykrywa automatycznie. Jednakże, można dodać informację  o  tym  preprocesorze,  tak  żeby
       strona   podręcznika   mogła   być  poprawnie  odczytana  pod  innymi  systemami.  Poniżej
       przedstawiamy listę preprocesorów wraz z odpowiadającymi im znakami:

       e  eqn(1)

       g  grap(1)

       p  pic(1)

       r  refer(1)

       t  tbl(1)

       v  vgrind(1)

BŁĘDY

       Większość makr opisuje  formatowanie  (np.  typ  czcionki  i  odstępy),  zamiast  oznaczać
       zawartość  składniową  (np.  to  jest  odnośnik  do  innej  strony).  Ta sytuacja utrudnia
       dostosowywanie formatu man do różnych mediów,  w  taki  sposób,  by  zachować  jednolitość
       formatowania  dla  danego  medium  i  automatycznie  dołożyć  odnośniki  do  innych stron.
       Wybierając ten opisany  powyżej  bezpieczny  podzbiór  makr,  daje  się  lepszą  możliwość
       automatycznego przetworzenia strony do innego formatu.

       Makro TX z systemu SUN nie jest zaimplementowane.

ZOBACZ TAKŻE

       apropos(1),   groff(1),   lexgrog(1),   man(1),   man2html(1),  groff_mdoc(7),  whatis(1),
       groff_man(7), groff_www(7), man-pages(7), mdoc(7)

O STRONIE

       Angielska wersja tej strony  pochodzi  z  wydania  3.71  projektu  Linux  man-pages.  Opis
       projektu,  informacje  dotyczące  zgłaszania błędów, oraz najnowszą wersję oryginału można
       znaleźć pod adresem http://www.kernel.org/doc/man-pages/.

TŁUMACZENIE

       Autorami polskiego tłumaczenia niniejszej strony podręcznika man są: Przemek  Borys  (PTM)
       <pborys@p-soft.silesia.linux.org.pl>,  Robert  Luberda <robert@debian.org> i Michał Kułach
       <michal.kulach@gmail.com>.

       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.71
       oryginału.