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.