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/share/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 4.05 projektu Linux man-pages. Opis  projektu,  informacje
       dotyczące   zgłaszania   błędów,   oraz   najnowszą   wersję   oryginału   można   znaleźć   pod  adresem
       https://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ą  4.05 oryginału.

Linux                                              2012-08-05                                             MAN(7)