MAN(7)

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 tmac.an (często nazywany pakietem makr man) oraz odpowiadające mu konwencje tworzenia stron podręcznika (man). Pakiet tych makr powinien być używany przez deweloperów, kiedy piszą lub przenoszą strony man dla Linuksa. Jest on 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.

PREAMBUŁA
Pierwszą komendą na stronie man (po liniach komentarza) powinna być

    .TH title section date source manual,

gdzie:

    title
        Tytuł strony podręcznika (np. MAN).

    section
        Numer sekcji, w której strona powinna się znaleźć (np. 7).

    date
        Data ostatniego poprawienia — pamiętaj, by zmieniać ją za każdym razem, kiedy dokonasz zmiany na stronie, ponieważ jest to najpopularniejsza droga kontrolowania wersji.

    source
        Źródło komendy.

        Dla binariów używaj czegoś w rodzaju: GNU, NET-2, SLS Distribution, MCC Distribution.

        Dla wywołań systemowych, podaj wersję jądra, której używasz: Linux 0.99.11.

        Dla wywołań bibliotecznych, użyj źródła funkcji: GNU, 4.3BSD, Linux DLL 4.4.1.

    manual
        Tytuł podręcznika (np. Linux Programmer's Manual).

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

Sekcje podręcznika man są tradycyjnie definiowane następująco:

    1 Komendy
        Te komendy mogą być wykonywane przez użytkownika z powłoki.

    2 Wywołania systemowe
        Te funkcje muszą być obsługiwane przez jądro.

    3 Wywołania biblioteczne
        Większość funkcji libc, takich jak qsort(3).

    4 Pliki specjalne
        Pliki, które można znaleźć w /dev.

    5 Formaty plików i konwencje
        Format dla pliku /etc/passwd i innych nadających się do odczytu przez człowieka.

    6 Gry

    7 Konwencje i różnorodne
        Opis standardowego rozkładu systemu plików, protokoły sieciowe, kodowanie znaków ASCII i inne kodowania, ta strona podręcznika i wiele innych rzeczy.

    8 Komendy zarządzania systemem.
        Komendy takie, jak mount(8), które wywoływać może tylko root .

    9 Wywołania jądra
        Jest to przestarzała sekcja podręcznika. Kiedyś uważano, że dobrym pomysłem będzie dokumentowanie tutaj jądra Linuksa, ale w rzeczywistości utworzono bardzo mało stron podręcznika w tej sekcji, a te dokumenty, które istnieją, są już przestarzałe. Istnieją lepsze źródła informacji dla deweloperów jądra.

SEKCJE
Sekcje zaczynają się od .SH, po którym występuje nazwa. Jeśli nazwa zawiera spacje i pojawia się w tej samej linii co .SH, to umieść ją między podwójnymi cudzysłowami. Tradycyjne lub sugerowane nagłówki to: NAZWA, SKŁADNIA, OPIS, WARTOŚĆ ZWRACANA, KOD WYJŚCIA, OBSŁUGA BŁĘDÓW, BŁĘDY, OPCJE, UŻYCIE, PRZYKŁADY, PLIKI, ŚRODOWISKO, DIAGNOSTYKA,BEZPIECZEŃSTWO, ZGODNE Z, UWAGI, USTERKI, AUTOR i ZOBACZ TAKŻE. Proszę używać tych tradycyjnych nagłówków, tam gdzie jest to możliwe; pozwoli to zachować spójność, ułatwiającą odbiorcy zrozumienie przekazywanych informacji. Jednakże, prosimy tworzyć własne nagłówki, tam gdzie jeszcze bardziej ułatwi to odbiór informacji. Jedynym wymaganym nagłówkiem jest NAZWA, po którym powinna nastąpić linijka z opisem programu:

    .SH NAZWA
    chess \- gra w szachy

Jest niesamowicie ważne, aby używać tego formatu, oraz że występuje odwrotny ukośnik przed kreską po nazwie komendy. Ta składnia (angielska, gdzie NAZWA to NAME) jest wykorzystywana przez program makewhatis(8) do tworzenia bazy krótkich opisów komend dla programu whatis(1) i apropos(1).

Zawartość innych tradycyjnych sekcji jest następująca:

SKŁADNIA
    krótko opisuje interfejs polecenia lub funkcji. W przypadku poleceń pokazuje składnię polecenia i jego argumenty (łącznie z opcjami); pogrubienie jest używane dla tekstu wpisywanego dosłownie, a kursywa oznacza zastępowalne argumenty. Nawiasy kwadratowe ([]) otaczają argumenty opcjonalne, linie pionowe (|) rozdzielają możliwe wybory, a wielokropek (...) oznacza możliwość powtarzania. W wypadku funkcji pokazuje wszystkie wymagane deklaracje danych lub dyrektywy #include, po których następuje deklaracja funkcji.

OPIS
    opisuje, co robi dane polecenie, funkcja lub format. Objaśnia interakcję z plikami i standardowym wejściem oraz wartości zwracane na standardowym wyjściu i standardowym wyjściu błędów. Pomijane są szczegóły dotyczące implementacji i rzeczy wewnętrznych programu, chyba że są one istotne dla zrozumienia interfejsu programu. Opisuje normalne przypadku użycia; objaśnienie opcji powinno się znaleźć w sekcji OPCJE. Jeżeli potrzebne jest opisanie gramatyki lub złożonego zbioru poleceń, należy rozważyć umieszczenie ich w oddzielnej sekcji UŻYCIE (a w sekcji OPIS można umieścić krótkie wprowadzenie).

WARTOŚĆ ZWRACANA
    określa listę wartości, które opisywana funkcja biblioteczna zwróci funkcji ją wywołującej, oraz warunki, w których dana wartość będzie zwracana.

KOD WYJŚCIA
    określa możliwe wartości kodów zakończenia programu oraz warunki, które powodują zwrócenie tych wartości.

OPCJE
    opisuje opcje akceptowane przez program oraz sposób, w jaki zmieniają one jego zachowanie.

UŻYCIE
    opisuje gramatykę jakiegokolwiek języka, który to implementuje.

PRZYKŁADY
    dostarcza jednego lub więcej przykładów opisujących, jak funkcja, plik lub polecenie są używane.

PLIKI
    zawiera listę plików używanych przez program lub funkcję, takich jak pliki konfiguracyjne, pliki uruchomieniowe oraz pliki używane w czasie działania programu. Należy podać pełną ścieżkę do pliku, w której podczas instalacji powinno się zmodyfikować katalogi, tak żeby odpowiadały preferencjom użytkownika. Wiele programów domyślnie instaluje się w /usr/local, tak że strona podręcznika powinna używać /usr/local jako podstawowego katalogu.

ŚRODOWISKO
    zawiera opis wszystkich zmiennych środowiskowych, wpływających na program i opisuje ten wpływ.

DIAGNOSTYKA
    pokrótce objaśnia najczęstsze komunikaty błędów oraz sposób ich obsługi. Nie należy objaśniać komunikatów o błędach systemowych lub fatalnych sygnałów, które mogą się pojawić podczas uruchamiania jakiegokolwiek programu, chyba że są w jakiś specjalny sposób traktowane przez Twój program.

BEZPIECZEŃSTWO
    omawia kwestie związane z bezpieczeństwem. Ostrzega o niezalecanych konfiguracjach lub zmiennych środowiska, poleceniach, które mogą mieć wpływ na bezpieczeństwo itd., zwłaszcza jeżeli nie są oczywiste. Omawianie zagadnień bezpieczeństwa w osobnej sekcji nie jest konieczne, jeżeli będzie to prostsze do zrozumienia, umieść te informacje w innych sekcjach (takich jak OPIS lub UŻYCIE). Jednakże, proszę gdzieś umieścić te informacje o bezpieczeństwie!

ZGODNE Z
    opisuje wszystkie standardy lub konwencje, które to implementuje.

UWAGI
    zawiera różne uwagi.

BŁĘDY
    opisuje ograniczenia, znane usterki lub niedogodności oraz inne problematyczne aktywności.

AUTOR
    zawiera listę autorów dokumentacji lub programu, tak żeby można było im mailem wysłać zgłoszenie o błędzie.

ZOBACZ TAKŻE
    opisuje powiązane strony podręcznika w kolejności alfabetycznej,po których mogą nastąpić inne powiązane strony lub dokumenty. Zgodnie z konwencją, ta sekcja jest ostatnia.

CZCIONKI
Chociaż istnieje wiele konwencji dla stron podręcznika w świecie Uniksowym, istnienie setek stron specyficznych dla Linuksa definiuje nasze standardy dotyczące czcionek:

    Dla funkcji, argumenty zawsze są podawane kursywą, nawet w sekcji SKŁADNIA, gdzie reszta funkcji jest wydrukowana w pogrubieniu:
    int myfunction(int argc, char **argv);

    Nazwy plików są także zawsze pisane kursywą (np. /usr/include/stdio.h), poza tymi z sekcji SKŁADNIA, gdzie włączane pliki są pogrubione (np. #include <stdio.h>).

    Makra specjalne, które są zwykle pisane dużymi literami, są pogrubiane (np. MAXINT).

    Podczas wyliczania listy kodów błędów, kody są pogrubiane (taka lista zwykle używa makra .TP).

    Wszelkie odwołania do innych stron man (lub temat bieżącej strony) są pogrubione. Jeśli podany jest numer sekcji podręcznika, podany jest fontem Roman (zwykłym), bez żadnych spacji (np. man(7)).

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 Font roman naprzemiennie z pogrubieniem

.RI Czcionka roman naprzemiennie z kursywą

.SB Mały font 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 w foncie 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) or \(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) uri, 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.

.   Te 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 bezpiecznie używać tych makr.

.   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 cudzysłów: “

\*(rq
    Prawy 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.

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ąty (<) 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)

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

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.

AUTORZY

—   James Clark (jjc@jclark.com) zaimplementował ten pakiet makr.

—   Rickard E. Faith (faith@cs.unc.edu) napisał pierwszą wersję tej strony podręcznika ekranowego.

—   Jens Schweikhardt (schweikh@noc.fdn.de) napisał Linux Man-Page Mini-HOWTO (które miało wpływ na tę stronę podręcznika).

—   David A. Wheeler (dwheeler@ida.org) znacząco zmodyfikował tę stronę podręcznika, na przykład dodając szczegółowe informajce o sekcjach i makrach.

ZOBACZ TAKŻE
apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), groff_www(7), whatis(1)