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. , ż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)

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) <[email protected]>, Robert Luberda <[email protected]> i Michał Kułach <[email protected]>.

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.