man

formatowanie i wy�wietlanie dost�pnych stron podr�cznika man

man.1.man
man.7.man

1. man.1.man

Manpage of man

man

Section: User Commands (1)
Updated: 2 wrze�nia 1995
Index Return to Main Contents

NAZWA

man - formatowanie i wy�wietlanie dost�pnych stron podr�cznika man
manpath - wyznaczanie �cie�ki poszukiwania stron podr�cznika odpowiedniej dla danego u�ytkownika

SK�ADNIA

man: [-adfhkKtwW] [-m system] [-p �a�cuch_znak�w] [-C plik_konfiguracyjny] [-M �cie�ka] [-P pager] [-S lista_rozdzia��w] [rozdzia�] nazwa...

OPIS

man formatuje i wy�wietla dost�pne w systemie strony podr�cznika man. Je�eli zostanie podany rozdzia�, man sprawdza tylko ten rozdzia� podr�cznika. Je�eli nazwa zawiera znak /, to man pr�buje najpierw znale�� podany plik, wi�c mo�na np. wyda� polecenie man ./foo.5 a nawet man /cd/foo/bar.1.gz.

Ni�ej znajdziesz informacje, gdzie man szuka plik�w stron podr�cznika.

OPCJE

-C plik_konfiguracyjny: Okre�la plik konfiguracyjny, kt�rego nale�y u�y�. Domy�lnym jest /etc/man.conf. (Zobacz man.conf(5).)
-M �cie�ka: Okre�la list� katalog�w, w kt�rych b�d� szukane strony podr�cznika man. Katalogi nale�y rozdziela� dwukropkami. Pusta lista jest r�wnoznaczna z nie podaniem tej opcji. Zobacz �CIE�KA PRZESZUKIWANIA DLA STRON PODR�CZNIKA.
-P pager: Okre�la, kt�ry pager ma zosta� u�yty. Je�eli podana jest ta opcja, ignorowana jest zmienna �rodowiskowa MANPAGER, kt�rej u�ycie z kolei powoduje zignorowanie zmiennej �rodowiskowej PAGER. Domy�lnie man u�ywa /usr/bin/less-is.
-S lista_rozdzia��w: Rozdzielona dwukropkami lista rozdzia��w podr�cznika, kt�re maj� by� przeszukane. Je�eli podana jest ta opcja, zmienna �rodowiskowa MANSECT jest ignorowana.
-a: Domy�lnie man ko�czy dzia�anie po wy�wietleniu pierwszej znalezionej strony. Podanie tej opcji powoduje wy�wietlenie wszystkich stron podr�cznika, kt�re pasuj� do nazwa, a nie tylko pierwszej.
-c: Przeformatowuje �r�d�ow� stron� podr�cznika, nawet je�eli istnieje aktualna strona cat. Mo�e to by� istotne, je�eli strona cat jest sformatowana dla ekranu z inn� liczb� kolumn.
-d: Zamiast stron podr�cznika wy�wietla mn�stwo informacji diagnostycznych.
-D: Wy�wietla zar�wno stron� podr�cznika jak i informacje diagnostyczne.
-f: R�wnowa�ne whatis.
-h: Wy�wietla kr�tk� informacj� pomocy i ko�czy prac�.
-k: R�wnowa�ne apropos.
-K: Szuka podanego �a�cucha znak�w we *wszystkich* stronach podr�cznika. Uwaga: b�dzie to prawdopodobnie bardzo powolne! Podanie rozdzia��w pomaga przyspieszy� szukanie. (Dla og�lnej orientacji: na mojej maszynie zajmuje to ok. minuty na ka�de 500 stron podr�cznika.)
-m system: Podanie alternatywnego zestawu stron podr�cznika, odpowiedniego dla systemu o podanej nazwie.
-p �a�cuch_znak�w: Podanie listy nazw preprocesor�w, ktore zostan� uruchomione przed nroff i troff. Nie wszystkie intalacje maj� pe�ny zestaw preprocesor�w. Niekt�re z nich oraz oznaczaj�ce je litery to: eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r). Podanie tej opcji powoduje zignorowanie zmiennej �rodowiskowej MANROFFSEQ.
-t: Sformatuj stron� podr�cznika za pomoc� /usr/bin/groff-Tps-mandoc, a wynik wy�lij na stdout (standardowe wyj�cie). Mo�e by� konieczne przepuszczenie wyniku z /usr/bin/groff -Tps -mandoc przez jaki� filtr przed wydrukowaniem.
-w lub --path: Nie wy�wietlaj stron podr�cznika, podaj tylko gdzie znajduj� si� pliki, kt�re by�yby sformatowane i wy�wietlone. Je�eli nie podano �adnych argument�w: wy�wietla (na stdout) list� katalog�w, w kt�rych man poszukuje stron podr�cznika. Je�eli manpath jest dowi�zaniem man to "manpath" jest r�wnowa�ne "man --path".
-W: Podobne do -w, lecz podaje nazwy plik�w, ka�d� w osobnej linii, bez dodatkowych informacji. Przydaje si� w poleceniach pow�oki, np. man -aW man | xargs ls -l

STRONY CAT

Man b�dzie pr�bowa� zachowa� sformatowane strony podr�cznika aby skr�ci� czas potrzebny na sformatowanie ich po raz kolejny, kiedy te strony b�d� znowu potrzebne. Tradycyjnie, sformatowane wersje stron podr�cznika z katalogu DIR/manX s� zachowywane w DIR/catX, ale mo�na te� w pliku /etc/man.conf okre�li� inne zasady. Strony cat nie s� tworzone, je�eli wymagany katalog nie istnieje.

Mo�liwe jest uczynienie programu man suidowym na u�ytkownika man. Wtedy, je�li katalogi cat maj� w�a�ciciela man i prawa dost�pu 0755 (zapisywalne tylko przez u�ytkownika man), a pliki cat maj� w�a�ciciela man i prawa dost�pu 0644 lub 0444 (zapisywalne przez u�ytkownika man lub przez nikogo), to �aden zwyk�y u�ytkownik nie mo�e zmienia� stron cat lub umieszcza� w katalogach cat innych plik�w. Je�eli man nie jest suidowy to katalog cat powinien mie� prawa dost�pu 0777, o ile wszyscy u�ytkownicy powinni mie� mo�liwo�� pozostawiania tam stron cat.

Opcja -c wymusza przeformatowanie strony nawet je�eli istnieje ju� odpowiednia strona cat.

�CIE�KA PRZESZUKIWANIA DLA STRON PODR�CZNIKA

man stosuje wymy�ln� metod� poszukiwania plik�w stron podr�cznika, opart� na opcjach wywo�ania, zmiennych �rodowiskowych, pliku konfiguracyjnym /etc/man.conf oraz na pewnych wbudowanych konwencjach i heurystyce.

Najpierw, gdy argument nazwa polecenia man zawiera uko�nik (/), man zak�ada, �e jest on nazw� w�a�ciwego pliku i nie prowadzi poszukiwania.

Ale zazwyczaj, gdy nazwa nie zawiera uko�nika, man poszukuje pliku, kt�ry m�g�by stanowi� stron� podr�cznika o zadanym temacie, w r�nych katalogach.

Je�li zostanie podana opcja -M �cie�ka, to �cie�ka jest rozdzielon� dwukropkami list� przeszukiwanych przez program man katalog�w.

Gdy opcja -M nie zostanie podana, ale zostanie zdefiniowana zmienna �rodowiskowa MANPATH, warto�� tej zmiennej stanowi list� przeszukiwanych przez program man katalog�w.

Je�li �cie�ka nie zostanie podana w spos�b jawny ani za pomoc� -M ani poprzez MANPATH, man rozwija swoj� w�asn� �cie�k� w oparciu o zawarto�� pliku konfiguracyjnego /etc/man.conf. Instrukcje MANPATH w pliku konfiguracyjnym okre�laj� poszczeg�lne katalogi w��czane do �cie�ki przeszukiwania.

Ponadto, instrukcje MANPATH_MAP dodaj� do �cie�ki przeszukiwania katalogi zale�ne od �cie�ki przeszukiwania dla polece� (tzn. zawartej w zmiennej �rodowiskowej PATH ). Instrukcja MANPATH_MAP dodaje do �cie�ki przeszukiwania dla stron podr�cznika po jednym katalogu dla ka�dego katalogu zawartego w �cie�ce przeszukiwania dla polece�. man przegl�da zmienn� PATH i dodaje odpowiednie katalogi do �cie�ki przeszukiwania dla stron podr�cznika. Zatem przy w�a�ciwym u�yciu MANPATH_MAP, po wydaniu polecenia man xyz, otrzyma si� stron� podr�cznika dla programu, kt�ry zosta�by uruchomiony poprzez wydanie polecenia xyz.

Dodatkowo, dla ka�dego katalogu w �cie�ce przeszukiwania dla polece� (b�dziemy go nazywa� "katalogiem polece�"), dla kt�rego nie ma instrukcji MANPATH_MAP, man automatycznie poszukuje "bliskiego" katalogu stron podr�cznika jako podkatalogu w�a�ciwego katalogu polece� lub w katalogu nadrz�dnym dla katalogu polece�.

Mo�na wy��czy� automatyczne "bliskie" przeszukiwania do��czaj�c instrukcj� NOAUTOPATH do /etc/man.conf.

Jak opisano powy�ej, w ka�dym z katalog�w �cie�ki przeszukiwania man poszukuje pliku o nazwie tytu�.rozdzia�, z opcjonalnym przyrostkiem dla numeru rozdzia�u i mo�liwym przyrostkiem kompresji. Je�li nie znajdzie takiego pliku, b�dzie szuka� w podkatalogach o nazwach manN i catN, gdzie N jest numerem rozdzia�u podr�cznika. Je�li plik znajduje si� w podkatalogu RcatN, man zak�ada, �e jest to sformatowany plik strony podr�cznika (cat page). W przeciwnym przypadku, man zak�ada, �e jest ona niesformatowana. W obu przypadkach, je�li nazwa pliku zawiera znany przyrostek kompresji (jak .gz), man zak�ada, �e jest ona spakowania gzipem.

Aby zobaczy�, gdzie (lub czy) man znajdzie stron� podr�cznika o okre�lonym tytule, nale�y pos�u�yc si� opcj� --path (-w).

�RODOWISKO

MANPL: Je�li zmienna MANPL jest zdefinowana, to jej warto�� jest u�ywana do okre�lenia d�ugo�ci strony. W przeciwnym przypadku, ca�a strona podr�cznika b�dzie stanowi� jedn� (d�ug�) stron�.
MANROFFSEQ: Je�li zmienna MANROFFSEQ jest zdefinowana, to jej warto�� jest u�ywana do zdefinowania zestawu preprocesor�w uruchamianych przed nroff i troff. Domy�lnie strony s� przepuszczane przez preprocesor tbl przed u�yciem nroff.
MANSECT: Je�li zmienna MANSECT jest zdefiniowana, to jej warto�� jest u�ywana do okre�lenia jakie rozdzia�y podr�cznika powinny zosta� przeszukane.
MANWIDTH: Je�li zmienna MANWIDTH jest zdefiniowana, to jej warto�� jest u�ywana jako szeroko�� wy�wietlanych stron podr�cznika man. W przeciwnym wypadku, strony b�d� wy�wietlane na ca�ej szeroko�ci ekranu.
MANPAGER: Je�li zmienna MANPAGER jest zdefiniowana, to jej warto�� jest u�ywana jako nazwa programu do wy�wietlania strony podr�cznika man. Je�li nie jest zdefiniowana, to u�ywana jest zmienna PAGER. Je�eli ta r�wnie� nie ma nadanej warto�ci, to u�ywany jest /usr/bin/less-is.
LANG: Je�li zmienna LANG jest zdefiniowana, to jej warto�� okre�la nazw� podkatalogu, w kt�rym man najpierw b�dzie szuka� stron podr�cznika. Zatem polecenie `LANG=pl man 1 co�' (w sh lub bash) spowoduje, �e man b�dzie szuka� strony "co�" w .../../co�.1, a nast�pnie, je�eli takiego pliku nie znajdzie, w .../co�.1, gdzie ... jest katalogiem ze �cie�ki przeszukiwania.
NLSPATH, LC_MESSAGES, LANG: Zmienne �rodowiskowe NLSPATH i LC_MESSAGES (lub LANG, je�eli ta druga nie istnieje) steruj� przeszukiwaniem katalog�w z komunikatami. (Komunikaty angielskie s� wkompilowane, wi�c dla angielskiego taki katalog nie jest potrzebny.) Zauwa�, �e programy takie jak col(1), wo�ane przez man, r�wnie� u�ywaj� np. LC_TYPE.
PATH: PATH pomaga okre�li� �cie�k� przeszukiwania dla plik�w stron podr�cznika. Zobacz �CIE�KA PRZESZUKIWANIA DLA STRON PODR�CZNIKA.
SYSTEM: SYSTEM jest u�ywana do pobierania domy�lnej alternatywnej nazwy systemu (do u�ywania razem z opcj� -m).

ZOBACZ TAK�E

apropos(1), whatis(1), less(1), groff(1), man.conf(5).

B��DY

Opcja -t dzia�a tylko je�eli jest zainstalowany jaki� program dzia�aj�cy jak troff.
Je�eli zamiast my�lnik�w pojawi� si� migaj�ce \255 lub <AD>, to nale�y ustawi� w �rodowisku u�ytkownika `LESSCHARSET=latin1'.

ZAKO�CZENIE

Je�li do pliku .emacs u�ytkownika dodana zostanie linia

(global-set-key [(f1)] (lambda () (interactive) (manual-entry (current-word))))

to naci�ni�cie F1 spowoduje wy�wietlenie strony podr�cznika dla funkcji bibliotecznej, na kt�rej ustawiony jest kursor.

Aby uzyska� czysto tekstow� wersj� strony podr�cznika, bez cofni�� i podkre�le�, nale�y wyda� polecenie

# man co� | col -b > co�.mantxt

Index

NAZWA
SK�ADNIA
OPIS
OPCJE
STRONY CAT
�CIE�KA PRZESZUKIWANIA DLA STRON PODR�CZNIKA
�RODOWISKO
ZOBACZ TAK�E
B��DY
ZAKO�CZENIE

This document was created by man2html using the manual pages.
Time: 00:25:02 GMT, November 20, 2008

2. man.7.man

Manpage of MAN

MAN

Section: Podr�cznik linuksowego programisty (7)
Updated: 2004-07-27
Index Return to Main Contents

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
[.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,
x,
(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 m(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.