Provided by:
manpages-pl_20060617-4_all 
NAZWA
man - makra do formatowania stron man
SK/LADNIA
groff -Tascii -man plik ...
groff -Tps -man plik ...
man [sekcja] tytu/l
OPIS
Ta strona podrcznika opisuje pakiet makr groff tmac.an (czsto nazywany
pakietem makr man) oraz odpowiadajce mu konwencje tworzenia stron
podrcznika (man). Pakiet tych makr powinien by uywany przez
deweloperow, kiedy pisz lub przenosz strony man dla Linuksa. Jest on w
pelni kompatybilny z innymi wersjami tego pakietu, wic przenoszenie
stron nie powinno by glownym problemem (wyjtki wlczaj NET-2 BSD, ktore
uywa calkiem innego pakietu makr zwanego mdoc; patrz mdoc(7)).
Prosz zauway, e strony NET-2 BSD mog by uyte z groffem przez proste
podanie opcji -mdoc zamiast zwyklej -man. Jednake bardziej zalecane
jest uywanie opcji -mandoc, poniewa wybierze ona automatycznie
odpowiedni zestaw makr.
PREAMBU/LA
Pierwsz komend na stronie man (po liniach komentarza) powinna by
.TH title section date source manual,
gdzie:
title Tytul strony podrcznika (np. MAN).
section Numer sekcji, w ktorej strona powinna si znale (np.
7).
date Data ostatniego poprawienia -- pamitaj, by zmienia j
za kadym razem, kiedy dokonasz zmiany na stronie,
poniewa jest to najpopularniejsza droga kontrolowania
wersji.
source rodlo komendy.
Dla binariow uywaj czego w rodzaju: GNU, NET-2, SLS
Distribution, MCC Distribution.
Dla wywola systemowych, podaj wersj jdra, ktorej
uywasz: Linux 0.99.11.
Dla wywola bibliotecznych, uyj rodla funkcji: GNU,
4.3BSD, Linux DLL 4.4.1.
manual Tytul podrcznika (np. Linux Programmer's Manual).
Prosz zauway, e strony formatowane za pomoc makr BSD mdoc rozpoczynaj
si od polecenia Dd, a nie TH.
Sekcje podrcznika man s tradycyjnie definiowane nastpujco:
1 Komendy Te komendy mog by wykonywane przez uytkownika z
powloki.
2 Wywo/lania systemowe
Te funkcje musz by obslugiwane przez jdro.
3 Wywo/lania biblioteczne
Wikszo funkcji libc, takich jak qsort(3).
4 Pliki specjalne
Pliki, ktore mona znale w /dev.
5 Formaty plik'ow i konwencje
Format dla pliku /etc/passwd i innych nadajcych si do
odczytu przez czlowieka.
6 Gry
7 Konwencje i r'onorodne
Opis standardowego rozkladu systemu plikow, protokoly
sieciowe, kodowanie znakow ASCII i inne kodowania, ta
strona podrcznika i wiele innych rzeczy.
8 Komendy zarzdzania systemem.
Komendy takie, jak mount(8), ktore wywolywa moe tylko
root .
9 Wywo/lania jdra
Jest to przestarzala sekcja podrcznika. Kiedy uwaano,
e dobrym pomyslem bdzie dokumentowanie tutaj jdra
Linuksa, ale w rzeczywistoci utworzono bardzo malo
stron podrcznika w tej sekcji, a te dokumenty, ktore
istniej, s ju przestarzale. Istniej lepsze rodla
informacji dla deweloperow jdra.
SEKCJE
Sekcje zaczynaj si od .SH, po ktorym wystpuje nazwa. Jeli nazwa zawiera
spacje i pojawia si w tej samej linii co .SH, to umie j midzy
podwojnymi cudzyslowami. Tradycyjne lub sugerowane naglowki to: NAZWA,
SKLADNIA, OPIS, WARTO ZWRACANA, KOD WYJCIA, OBSLUGA BLDOW, BLDY, OPCJE,
UYCIE, PRZYKLADY, PLIKI, RODOWISKO, DIAGNOSTYKA,BEZPIECZESTWO, ZGODNE
Z, UWAGI, USTERKI, AUTOR i ZOBACZ TAKE. Prosz uywa tych tradycyjnych
naglowkow, tam gdzie jest to moliwe; pozwoli to zachowa spojno,
ulatwiajc odbiorcy zrozumienie przekazywanych informacji. Jednake,
prosimy tworzy wlasne naglowki, tam gdzie jeszcze bardziej ulatwi to
odbior informacji. Jedynym wymaganym naglowkiem jest NAZWA, po ktorym
powinna nastpi linijka z opisem programu:
.SH NAZWA
chess \- gra w szachy
Jest niesamowicie wane, aby uywa tego formatu, oraz e wystpuje odwrotny
ukonik przed kresk po nazwie komendy. Ta skladnia (angielska, gdzie
NAZWA to NAME) jest wykorzystywana przez program makewhatis(8) do
tworzenia bazy krotkich opisow komend dla programu whatis(1) i
apropos(1).
Zawarto innych tradycyjnych sekcji jest nastpujca:
SK/LADNIA krotko opisuje interfejs polecenia lub funkcji. W
przypadku polece pokazuje skladni polecenia i jego
argumenty (lcznie z opcjami); pogrubienie jest uywane dla
tekstu wpisywanego doslownie, a kursywa oznacza
zastpowalne argumenty. Nawiasy kwadratowe ([]) otaczaj
argumenty opcjonalne, linie pionowe (|) rozdzielaj moliwe
wybory, a wielokropek (...) oznacza moliwo powtarzania. W
wypadku funkcji pokazuje wszystkie wymagane deklaracje
danych lub dyrektywy #include, po ktorych nastpuje
deklaracja funkcji.
OPIS opisuje, co robi dane polecenie, funkcja lub format.
Objania interakcj z plikami i standardowym wejciem oraz
wartoci zwracane na standardowym wyjciu i standardowym
wyjciu bldow. Pomijane s szczegoly dotyczce implementacji
i rzeczy wewntrznych programu, chyba e s one istotne dla
zrozumienia interfejsu programu. Opisuje normalne
przypadku uycia; objanienie opcji powinno si znale w
sekcji OPCJE. Jeeli potrzebne jest opisanie gramatyki lub
zloonego zbioru polece, naley rozway umieszczenie ich w
oddzielnej sekcji UYCIE (a w sekcji OPIS mona umieci
krotkie wprowadzenie).
WARTO ZWRACANA
okrela list wartoci, ktore opisywana funkcja biblioteczna
zwroci funkcji j wywolujcej, oraz warunki, w ktorych dana
warto bdzie zwracana.
KOD WYJCIA okrela moliwe wartoci kodow zakoczenia programu oraz
warunki, ktore powoduj zwrocenie tych wartoci.
OPCJE opisuje opcje akceptowane przez program oraz sposob, w
jaki zmieniaj one jego zachowanie.
UYCIE opisuje gramatyk jakiegokolwiek jzyka, ktory to
implementuje.
PRZYK/LADY dostarcza jednego lub wicej przykladow opisujcych, jak
funkcja, plik lub polecenie s uywane.
PLIKI zawiera list plikow uywanych przez program lub funkcj,
takich jak pliki konfiguracyjne, pliki uruchomieniowe
oraz pliki uywane w czasie dzialania programu. Naley poda
peln ciek do pliku, w ktorej podczas instalacji powinno
si zmodyfikowa katalogi, tak eby odpowiadaly preferencjom
uytkownika. Wiele programow domylnie instaluje si w
/usr/local, tak e strona podrcznika powinna uywa
/usr/local jako podstawowego katalogu.
RODOWISKO zawiera opis wszystkich zmiennych rodowiskowych,
wplywajcych na program i opisuje ten wplyw.
DIAGNOSTYKA pokrotce objania najczstsze komunikaty bldow oraz sposob
ich obslugi. Nie naley objania komunikatow o bldach
systemowych lub fatalnych sygnalow, ktore mog si pojawi
podczas uruchamiania jakiegokolwiek programu, chyba e s w
jaki specjalny sposob traktowane przez Twoj program.
BEZPIECZESTWO omawia kwestie zwizane z bezpieczestwem. Ostrzega o
niezalecanych konfiguracjach lub zmiennych rodowiska,
poleceniach, ktore mog mie wplyw na bezpieczestwo itd.,
zwlaszcza jeeli nie s oczywiste. Omawianie zagadnie
bezpieczestwa w osobnej sekcji nie jest konieczne, jeeli
bdzie to prostsze do zrozumienia, umie te informacje w
innych sekcjach (takich jak OPIS lub UYCIE). Jednake,
prosz gdzie umieci te informacje o bezpieczestwie!
ZGODNE Z opisuje wszystkie standardy lub konwencje, ktore to
implementuje.
UWAGI zawiera rone uwagi.
B/LDY opisuje ograniczenia, znane usterki lub niedogodnoci oraz
inne problematyczne aktywnoci.
AUTOR zawiera list autorow dokumentacji lub programu, tak eby
mona bylo im mailem wysla zgloszenie o bldzie.
ZOBACZ TAKE opisuje powizane strony podrcznika w kolejnoci
alfabetycznej,po ktorych mog nastpi inne powizane strony
lub dokumenty. Zgodnie z konwencj, ta sekcja jest
ostatnia.
CZCIONKI
Chocia istnieje wiele konwencji dla stron podrcznika w wiecie
Uniksowym, istnienie setek stron specyficznych dla Linuksa definiuje
nasze standardy dotyczce czcionek:
Dla funkcji, argumenty zawsze s podawane kursyw, nawet w sekcji
SK/LADNIA, gdzie reszta funkcji jest wydrukowana w pogrubieniu:
int myfunction(int argc, char **argv);
Nazwy plikow s take zawsze pisane kursyw (np.
/usr/include/stdio.h), poza tymi z sekcji SKLADNIA, gdzie
wlczane pliki s pogrubione (np. #include <stdio.h>).
Makra specjalne, ktore s zwykle pisane duymi literami, s
pogrubiane (np. MAXINT).
Podczas wyliczania listy kodow bldow, kody s pogrubiane (taka
lista zwykle uywa makra .TP).
Wszelkie odwolania do innych stron man (lub temat biecej strony)
s pogrubione. Jeli podany jest numer sekcji podrcznika, podany
jest fontem Roman (zwyklym), bez adnych spacji (np. man(7)).
Komendy do wyboru czcionki s nastpujce:
.B Pogrubienie
.BI Pogrubienie na przemian z kursyw (szczegolnie uytecznie w
specyfikacji funkcji)
.BR Pogrubienie na przemian z czcionk Roman (szczegolnie uyteczne w
odnonikach do innych stron podrcznika)
.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 Maly font naprzemiennie z pogrubieniem
.SM Mala (uyteczne dla akronimow)
Tradycyjnie, kada komenda moe mie do szeciu argumentow, lecz wersja GNU
wydaje si znosi to ograniczenie (wci jednak mona rozway wprowadzenie
limitu 6 argumentow w celu zachowania kompatybilnoci). Argumenty s
oddzielane spacjami. Podwojne cudzyslowy mog by uywane do okrelania
argumentow ze spacjami. Wszystkie argumenty zostan wydrukowane obok
siebie, bez wtrconych spacji, tak e komenda .BR moe zosta uyta do
podania slowa pogrubionego, po ktorym nastpuje znak interpunkcyjny w
foncie Roman. Jeeli nie podano adnych argumentow, polecenie stosuje si
do linii tekstu nastpujcej po nim.
INNE MAKRA I /LACUCHY ZNAK'OW
Poniej przedstawiono inne makra i predefiniowane lacuchy znakow. Jeeli
nie podano inaczej, wszystkie makra powoduj przerw (zakoczenie biecej
linii tekstu). Wiele z tych makr ustawia lub uywa wartoci "powszechnego
wcicia". Warto ta jest ustawiana przez kade makro przyjmujce parametr
i; makra mog pomija i, co oznacza, e bdzie uywana bieca warto
"powszechnego wcicia". W wyniku tego kolejne wcite akapity mog uywa tej
samej wartoci wcicia bez jej kadorazowego podawania. Zwykly (niewcity)
akapit ustawia wcicie na jego domyln warto (0.5 cala). Domylnie wcicie
jest wyraone w ens [szeroko litery "n"]; zaleca si uywanie ens lub ems
jako jednostek wcicia, poniewa automatycznie dostosuj si do zmian
rozmiaru czcionki. Inne kluczowe definicje makr s nastpujce:
Zwyk/le akapity
.LP To samo, co .PP (rozpoczcie nowego akapitu).
.P To samo, co .PP (rozpoczcie nowego akapitu).
.PP Rozpoczcie nowego akapitu i usunicie biecego wcicia.
Pocztek wiszcego wcicia
.RS i Rozpoczyna relatywne wcicie marginesu: przesuwa lewy margines
o i w prawo (jeeli pominito i, to uywana jest warto
"powszechnego wcicia"). Warto "powszechnego wcicia" ustawiana
na 0.5 cala. W wyniku wcinane bd wszystkie kolejne akapity, a
do napotkania odpowiadajcego .RE.
.RE Koczy relatywne wcicie marginesu i ustawia poprzedni warto
wcicia.
Makra wci akapit'ow
.HP i Rozpoczyna akapit od wiszcego wcicia (pierwsza linia akapitu
znajduje si przy lewym marginesie w stosunku do zwyklych
akapitow, a pozostale akapitu linie s wcite).
.IP x i Wcity akapit z opcjonalnym wiszcym znacznikiem. Jeeli pominito
znacznik x, to caly nastpujcy akapit bdzie wcity o i. Jeeli
podano znacznik x, to bdzie on umieszczony zaraz przy lewym
marginesie przed nastpujcym po nim wcitym akapitem (podobnie
jak to robi .TP poza tym, e znacznik jest umieszczony przy
poleceniu, a nie w kolejnej linii). Jeeli znacznik jest zbyt
dlugi to tekst po znaczniku bdzie przeniesiony do kolejnej
linii (tekst nie bdzie usunity ani znieksztalcony). Dla list
nienumerowanych, naley uy tego makra, podajc jako znacznik (bu
(kula) or \(em (mylnik), a dla list numerowanych naley w
znaczniku poda liczb lub cyfr, po ktorej nastpuje kropka;
ulatwi to przetworzenie do innych formatow.
.TP i Rozpoczyna akapit z wiszcym znacznikiem. Znacznik jest
podawany w nastpnej linii. Wyniki s podobne do .IP
Makra odnonik'ow hipertekstowych
(Cecha obslugiwana tylko przez groffa). Aby uy makr lczy
hipertekstowych, potrzebne jest zaladowanie pakietu makr www.tmac. Aby
to zrobi, naley uy dania .mso www.tmac.
.URL url link trailer
Wstawia odnonik hipertekstowy do lokalizacji URI (URL) uri, z
linkiem jako tekstem odnonika, a zaraz po nim bdzie wypisany
trailer. Generujc HTML-a, powinno si to przetlumaczy jako
nastpujce polecenie HTML-a: <A HREF="url">link</A>trailer.
. Te i inne podobne makra s nowe, tak wic wiele narzdzi ich nie
obsluguje, ale poniewa wiele narzdzi (wlcznie z troffem) po
prostu zignoruje niezdefiniowane makra (albo w gorszym
przypadku wstawi wlasny tekst), wic mona bezpiecznie uywa tych
makr.
. Moe by uyteczne zdefiniowanie wlasnego makra URL w stronach
podrcznika ekranowego, aby da moliwo ogldania ich w programach
innych ni groff. Tym sposobem URL, tekst odnonika i podpisu
bdzie widoczny.
. Oto przyklad:
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH ...
(p'oniej na stronie)
Ten program pochodzi z
.URL "http://www.gnu.org/" "Projektu GNU" " z"
.URL "http://www.fsf.org/" "Free Software Foundation" .
. W powyszym przypadku, jeli uywany jest groff, to definicja
makra URL z pakietu www.tmac nadpisze makro zdefiniowane
lokalnie.
Dostpna s take inne makra dla odnonikow. Patrz groff_www(7) po dalsze
informacje.
R'onorodne makra
.DT Ustawia tabulacj na jej domyln warto (co kade pol cala); nie
powoduje przerwy.
.PD d Ustawia odleglo midzy wierszami w akapicie (jeli pominito, to
d=0.4v); nie powoduje przerwy.
.SS t Pod-naglowek t (jak .SH, lecz uywane do podsekcji)
Predefiniowane /lacuch znak'ow
Pakiet man zawiera nastpujce predefiniowane lacuchy znakow:
\*R Symbol rejestracji: (R)
\*S Zmienia domylny rozmiar czcionki
\*(Tm Symbol znaku towarowego: tm
\*(lq Lewy cudzyslow: "
\*(rq Prawy cudzyslow: "
BEZPIECZNY PODZBI'OR
Chocia z technicznego punktu widzenia man jest pakietem makr troffa, to
w rzeczywistoci strony podrcznika ekranowego mog by przetwarzane przez
wiele innych narzdzi, ktore nie implementuj wszystkich wlaciwoci
troffa. Dlatego najlepiej unika pewnych bardziej egzotycznych makr
troffa, tam gdzie jest to moliwe tak, aby inne narzdzia pracowaly
poprawnie. Naley unika uywania preprocesorow troffa (jeeli jest to
konieczne, prosz bardzo, uyj tbl(1), ale zamiast tworzy dwukolumnowe
tabele, sprobuj uy polece IP i TP). Naley unika take uywania wylicze --
wikszo innych narzdzi nie umie ich przetworzy. Lepiej uy prostych
polece, latwych do przetlumaczenia do innych formatow. Nastpujce makra
troffa uwaa si za bezpieczne (chocia w wielu przypadkach bd zignorowane
przez tlumaczy): \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy,
ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.
Mona take uywa wielu sekwencji cytowania (czyli sekwencji zaczynajcych
si od \). Aby uy znaku odwrotnego ukonika w zwyklym tekcie, naley wpisa
\e. Do innych sekwencji, ktorych mona uy, nale (x i xx s zwyklymi
znakami, a N -- dowoln liczb): \', \`, \-, \., \", \%, \*x, \*(xx,
\(xx, \$N, \nx, \n(xx, \fx oraz \f(xx. Naley unika uywania sekwencji
cytowania do rysowania grafiki.
Nie naley uywa nieobowizkowego parametru makra bp (podzial strony).
Naley uywa tylko dodatnich wartoci dla sp (spacja pionowa). Nie naley
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 powtorne zdefiniowanie makra bdzie po prostu
zignorowane.Kade dodatnie wcicie (in) powinno by sparowane z
odpowiadajcym mu wciciem negatywnym (chocia powinno si jednak uywa makr
RS i RE zamiast in). Instrukcje warunkowe (if,ie) powinny mie tylko 't'
lub 'n' w warunku. Powinny by uywane tylko tlumaczenia (tr), ktore mona
zignorowa. Zmiany czcionki (ft oraz sekwencja cytowania \f) powinny mie
tylko wartoci 1, 2, 3, 4, R, I, B, P lub CW (polecenie ft moe take nie
mie adnych parametrow).
Jeeli uywane s makra inne ni te opisane powyej, naley dokladnie
sprawdzi wynik, uywajc kilku narzdzi. Po sprawdzeniu, e te dodatkowe
makra s bezpieczne, prosimy o poinformowanie o nich opiekuna tego
dokumentu, tak eby mona bylo je doda do tej listy.
UWAGI
W kadym wypadku naley wlcza pelne URL-e (lub URI) do samego tekstu;
niektore narzdzia, takie jak man2html(1) potrafi automatycznie
przeksztalci je na odnoniki. Mona take uywa nowego makra URL, aby
wprowadzi informacje zwizane z odnonikami. Podczas podawania URL-i,
naley uywa ich w pelnej postaci (np. <http://www.kernelnotes.org>), eby
narzdzia mogly je automatycznie znale.
Narzdzia przetwarzajce pliki powinny otworzy plik i sprawdzi zawarto
pierwszego znaku nie bdcego bial spacj. Kropka (.) lub pojedynczy
cudzyslow (') na pocztku linii oznacza plik oparty na troffie (taki jak
man lub mdoc). Lewy nawias trojkty (<) oznacza plik oparty na
SGML/XML-u (taki jak HTML lub Docbook). Wszystko inne oznacza zwykly
tekst ASCII (np. wynik "catman").
Wiele stron podrcznika rozpoczyna si od '\", po ktorym nastpuje spacja
i lista znakow, okrelajcych preprocesor, uywany do przetwarzania
strony. Dla zachowania zgodnoci z innymi narzdziami, zalecamy, aby
unika preprocesorow innych ni tbl(1), ktory Linux wykrywa
automatycznie. Jednake, mona doda informacj o tym preprocesorze, tak
eby strona podrcznika mogla by poprawnie odczytana pod innymi
systemami. Poniej przedstawiamy list preprocesorow wraz z
odpowiadajcymi 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/LDY
Wikszo makr opisuje formatowanie (np. typ czcionki i odstpy), zamiast
oznacza zawarto skladniow (np. to jest odnonik do innej strony). Ta
sytuacja utrudnia dostosowywanie formatu man do ronych mediow, w taki
sposob, by zachowa jednolito formatowania dla danego medium i
automatycznie doloy odnoniki do innych stron. Wybierajc ten opisany
powyej bezpieczny podzbior makr, daje si lepsz moliwo automatycznego
przetworzenia strony do innego formatu.
Makro TX z systemu SUN nie jest zaimplementowane.
AUTORZY
-- James Clark (jjc@jclark.com) zaimplementowal ten pakiet makr.
-- Rickard E. Faith (faith@cs.unc.edu) napisal pierwsz wersj tej strony
podrcznika ekranowego.
-- Jens Schweikhardt (schweikh@noc.fdn.de) napisal Linux Man-Page
Mini-HOWTO (ktore mialo wplyw na t stron podrcznika).
-- David A. Wheeler (dwheeler@ida.org) znaczco zmodyfikowal t stron
podrcznika, na przyklad dodajc szczegolowe informajce o sekcjach i
makrach.
ZOBACZ TAKE
apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7),
groff_www(7), whatis(1)
INFORMACJE O T/LUMACZENIU
Powysze tlumaczenie pochodzi z nieistniejcego ju Projektu Tlumaczenia
Manuali i moe nie by aktualne. W razie zauwaenia ronic midzy powyszym
opisem a rzeczywistym zachowaniem opisywanego programu lub funkcji,
prosimy o zapoznanie si z oryginaln (angielsk) wersj strony podrcznika.