Provided by: manpages-pl_0.5-1_all 
NAZWA
man-pages - konwencje pisania linuksowych stron podręcznika ekranowego
SKŁADNIA
man [sekcja] tytuł
OPIS
Strona opisuje konwencje, do których powinno się stosować podczas pisania stron podręcznika ekranowego
dla projektu Linux man-pages, który dokumentuje interfejs programistyczny w przestrzeni użytkownika
udostępniany przez jądro Linux i bibliotekę GNU C. Z tego powodu projekt dotyczy głównie sekcji 2
podręcznika systemowego, jak również wielu podręczników z sekcji 3, 4, 5 i 7. Konwencje opisane tutaj
mogą się także przydać autorom podręczników z innych projektów.
Sekcje stron podręcznika ekranowego
Sekcje podręcznika man są tradycyjnie definiowane następująco:
1 Komendy (programy)
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.
4 Pliki specjalne (urządzenia)
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 Przegląd, konwencje i różnorodne
Przegląd różnych tematów, konwencje, protokoły, standardy kodowania znaków i inne.
8 Polecenia do zarządzania systemem
Komendy takie, jak mount(8), które wywoływać może tylko root .
Pakiety makr
Nowe strony podręcznika powinny być pisane z użyciem pakietu makr groff an.tmac opisanego w man(7). Wybór
ten podyktowany jest zachowaniem spójności: przytłaczająca większość istniejących podręczników
linuksowych używa tego pakietu makr.
Konwencje wyglądu pliku źródłowego
Prosimy ograniczać długość linii kodu źródłowego do maksymalnie 75 znaków, jeśli jest to możliwe. Pomaga
to unikać zawijania wierszy w niektórych programach pocztowych podczas przesyłania łat do podręczników
ekranowych.
Nowe zdania powinny zaczynać się w nowych liniach. Upraszcza to oglądanie efektów łat, które często
operują na poziomie poszczególnych zdań.
Linia tytułowa
Pierwszą komendą strony podręcznika powinno być polecenie TH:
.TH tytuł sekcja data źródło podręcznik
gdzie:
tytuł Tytuł strony podręcznika, pisany w całości dużymi literami (np. MAN-PAGES).
sekcja Numer sekcji, w której strona powinna się znaleźć (np. 7).
data Data ostatniej wersji strony — prosimy pamiętać o uaktualnianiu jej po każdej zmianie
strony podręcznika, ponieważ jest to najpopularniejsza droga kontrolowania wersji. Daty
powinny być zapisywane w postaci RRRR-MM-DD.
źródło Źródło polecenia, funkcji lub wywołania systemowego.
Dla tych kilku stron z pakietu man-pages znajdujących się w sekcjach 1. i 8.,
najprawdopodobniej należy podać GNU.
Dla wywołań systemowych najodpowiedniejsze będzie Linux. (Wcześniej praktykowano
dodawanie numeru wersji jądra, dla której strona podręcznika została napisana lub
zaktualizowana. Nigdy jednak nie zachowano spójności w robieniu tego, co było
najprawdopodobniej gorsze niż niedołączanie numeru wersji. Dlatego też prosimy unikać
dołączania numeru wersji).
Dla wywołań bibliotecznych będących częścią biblioteki glibc lub innych powszechnie
używanych bibliotek GNU, należy użyć GNU C library, GNU lub pustego łańcucha znaków.
Dla stron w sekcji 4., należy użyć Linux.
W razie wątpliwości, prosimy użyć Linux lub GNU.
podręcznik
Tytuł podręcznika (np. w sekcjach 2. i 3. stron z pakietu man-pages prosimy używać Linux
Programmer's Manual (tj. Podręcznik programisty Linuksa)).
Rozdziały stron podręcznika
Poniższa lista pokazuje rozdziały konwencjonalne lub sugerowane. Większość stron podręcznika powinna
zawierać przynajmniej wyróżnione rozdziały. Prosimy pisać nowe strony podręcznika w taki sposób, by
rozdziały pojawiały się w takiej kolejności, w jakiej są podane na liście.
NAZWA (NAME)
SKŁADNIA (SYNOPSIS)
KONFIGURACJA (CONFIGURATION) [Zwykle tylko w sekcji 4.]
OPIS (DESCRIPTION)
OPCJE (OPTIONS) [Zwykle tylko w sekcjach 1., 8.]
KOD ZAKOŃCZENIA (EXIT STATUS) [Zwykle tylko w sekcjach 1., 8.]
WARTOŚĆ ZWRACANA (RETURN VALUE) [Zwykle tylko w sekcjach 2., 3.]
BŁĘDY (ERRORS) [Zwykle tylko w sekcjach 2., 3.]
ŚRODOWISKO (ENVIRONMENT)
PLIKI (FILES)
ATRYBUTY (ATTRIBUTES) [Zwykle tylko w sekcjach 2, 3]
WERSJE (VERSIONS) [Zwykle tylko w sekcjach 2., 3.]
ZGODNE Z (CONFORMING TO)
UWAGI (NOTES)
BŁĘDY [IMPLEMENTACJI] (BUGS)
PRZYKŁAD (EXAMPLE)
ZOBACZ TAKŻE (SEE ALSO)
W celu zachowania spójności i dla lepszego zrozumienia przekazywanych informacji prosimy używać
zwyczajowych nagłówków wszędzie, gdzie mają zastosowanie. Jeśli jest to konieczne, można użyć własnych
nagłówków, zwłaszcza gdy sprawią, że tekst łatwiej będzie zrozumieć (może być to szczególnie użyteczne w
sekcjach 4. i 5.). Jednakże zanim użyje się własnych nagłówków, prosimy rozważyć użycie nagłówków
zwyczajowych i umieszczenie podrozdziałów (.SS) w rozdziałach opisanych tymi nagłówkami.
Poniżej opisujemy zawartość każdej z powyższych sekcji.
NAZWA Nazwa danej strony podręcznika systemowego. Podręcznik man(7) zawiera ważne detale na temat
wierszy które powinny znaleźć się za poleceniem .SH NAZWA. Wszystkie słowa w tym wierszu
(łącznie ze słowami występującymi zaraz za "\-") powinny być pisane małymi literami z
wyjątkiem konwencji terminologii lub wymagań językowych, które mówią inaczej.
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.
Jeżeli do uzyskania deklaracji funkcji (lub zmiennej) z pliku nagłówkowego wymagane jest
zdefiniowanie makra testującego, to informacja o tym powinna zostać umieszczona w rozdziale
SKŁADNIA (SYNOPSIS), tak jak to opisano w feature_test_macros(7).
KONFIGURACJA Szczegóły konfiguracji urządzenia. Ta sekcja zazwyczaj występuje tylko w 4. sekcji stron
podręcznika ekranowego.
OPIS opisuje, co robi dany program, 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ętrzne programu, chyba
że są istotne dla zrozumienia interfejsu programu. Opisuje normalne przypadki użycia;
objaśnienie opcji powinno się znaleźć w rozdziale OPCJE.
OPCJE Opisuje opcje linii poleceń akceptowane przez program oraz sposób, w jaki wpływają na jego
zachowanie. Rozdział powinien się pojawiać tylko w sekcjach 1. i 8. stron podręcznika
ekranowego.
KOD WYJŚCIA Określa możliwe wartości kodów zakończenia programu oraz warunki, które powodują zwrócenie
tych wartości. Rozdział powinien się pojawiać tylko w sekcjach 1. i 8. stron podręcznika
ekranowego.
WARTOŚĆ ZWRACANA
W sekcjach 2. i 3. stron podręcznika, rozdział ten 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.
BŁĘDY W sekcjach 2. i 3. stron podręcznika jest to lista wartości, które mogą być przypisane
zmiennej errno w razie wystąpienia błędu, łącznie z informacjami o przyczynach tego błędu.
Elementy listy powinny być wymienione w porządku alfabetycznym.
ŚRODOWISKO Zawiera opis wszystkich zmiennych środowiskowych, wpływających na program i opisuje ten
wpływ.
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.
ATRYBUTY Podsumowanie różnych atrybutów funkcji udokumentowanych na danej stronie podręcznika
podzielonych na podsekcje. Zdefiniowano następujące podsekcje:
Wielowątkowość (zob. pthreads(7))
Podsekcja opisuje atrybuty odnoszące się do aplikacji wielowątkowych:
* Czy funkcja jest wątkowo bezpieczna.
* Czy funkcja jest punktem odwołania (ang. cancellation point).
* Czy funkcja jest bezpieczna pod względem anulowania wywołania asynchronicznego.
Szczegóły tych atrybutów można znaleźć w pthreads(7).
WERSJE Krótkie podsumowanie wersji jądra Linuksa lub biblioteki glibc, w której to wersji
opisywane wywołanie systemowe lub funkcja biblioteczna się pojawiły lub ich działanie
zostało znacząco zmienione. Z zasady każda strona podręcznika opisująca nowy interfejs
powinna zawierać rozdział WERSJE (VERSIONS). Niestety wiele istniejących stron nie dołącza
tych informacji (gdyż nie było to wymagane w czasie pisania tych stron). Chętnie przyjmiemy
łaty poprawiające ten problem, jednakże z perspektywy programisty informacje o wersji mają
najprawdopodobniej znaczenie tylko w przypadku interfejsów jądra dodanych w Linuksie 2.4
lub kolejnych (tj. zmiany w stosunku do jądra 2.2) oraz w przypadku funkcji bibliotecznych
dołożonych do glibc od wersji 2.1 (tj. zmiany w stosunku do wersji 2.0).
Strona podręcznika syscalls(2) także dostarcza informacji o wersjach jądra, w których
pojawiły się różne wywołania systemowe.
ZGODNE Z Opisuje standardy lub konwencje związane z opisywaną w podręczniku funkcją lub opisywanym
poleceniem. Strony w sekcjach 2. i 3. powinny wskazywać na wersje standardu POSIX.1, z
którymi są zgodne opisywane w nich wywołania oraz informować o tym, czy wywołanie jest
opisane w standardzie C99 (Prosimy nie przejmować się zbytnio innymi standardami jak SUS,
SUSv2 i XPG lub standardami implementacji SVr4 lub BSD 4.x, chyba że wywołanie jest
opisane w tych standardach, ale nie w bieżącej wersji standardu POSIX.1) (Patrz także
standards(7)).
Jeśli wywołanie nie jest zamieszczone w żadnym standardzie, ale zwyczajowo istnieje w
innych systemach, prosimy wymienić te systemy. Jeśli wywołanie jest specyficzne dla
Linuksa, również należy o tym poinformować.
Jeśli rozdział zawiera tylko i wyłącznie listę standardów (a tak jest zazwyczaj), lista ta
powinna być zakończona kropką (".").
UWAGI Zawiera różnorodne uwagi. W sekcjach 2. i 3. stron podręcznika ekranowego może być
użyteczne podzielenie tego rozdziału na podrozdziały (SS) nazywane Uwagi linuksowe i Uwagi
dotyczące biblioteki glibc.
BŁĘDY Opisuje ograniczenia, znane usterki lub niedogodności oraz inne problematyczne aktywności.
PRZYKŁAD Dostarcza jednego lub więcej przykładów opisujących, jak funkcja, plik lub polecenie są
używane. Szczegóły dotyczące pisania przykładowych programów opisano w sekcji Przykładowe
programy poniżej.
AUTORZY Lista autorów dokumentacji lub programu. Używanie sekcji AUTORZY nie jest zalecane. Ogólnie
lepiej jest nie zaśmiecać każdej strony (z upływem czasu coraz większą) listą autorów.
Podczas pisania lub znaczącego zmieniania strony podręcznika, należy umieścić informacje o
prawach autorskich jako komentarz w stronie źródłowej. Autorzy sterowników urządzeń, którzy
chcieliby podać adres, pod którym należy zgłaszać błędy, powinny umieścić go w rozdziale
BŁĘDY (BUGS).
ZOBACZ TAKŻE Zawiera rozdzieloną przecinkami listę powiązanych stron podręcznika, posortowaną po numerze
sekcji, a następnie alfabetycznie po nazwie. Po nich mogą występować inne powiązane strony
lub dokumenty. Nie należy umieszczać kropki na końcu listy.
Gdy w ZOBACZ TAKŻE znajduje się wiele długich nazw podręczników systemowych to, w celu
poprawienia przejrzystości tekstu, można użyć dyrektyw .ad l (nie wyrównuj do prawej
strony) i .nh (nie dziel). Aby zapobiec dzieleniu pojedynczych nazw podręczników należy je
poprzedzić łańcuchem "\%".
Konwencje czcionek
Dla funkcji, argumenty zawsze są podawane kursywą, nawet w rozdziale SKŁADNIA, w którym reszta funkcji
jest wydrukowana w pogrubieniu:
int myfunction(int argc, char **argv);
Nazwy zmiennych podobnie jak nazwy argumentów powinny być pisane kursywą.
Nazwy plików (niezależnie od tego, czy są pełnymi ścieżkami czy odniesieniami do plików w katalogu
/usr/include) są zawsze pisane kursywą (np. <stdio.h>), z wyjątkiem nazw występujących w rozdziale
SKŁADNIA (SYNOPSIS), w którym pliki dołączane są wyróżniane pogrubieniem (np. #include <stdio.h>).
Odwołania do standardowych plików dołączanych znajdujących się w /usr/include powinny zawierać nazwę
pliku nagłówkowego w nawiasach trójkątnych, tak jak to jest przyjęte w języku C (np. <stdio.h>).
Makra specjalne, które są zwykle pisane dużymi literami, są pogrubiane (np. MAXINT). Wyjątek: nie
pogrubiamy słowa NULL.
Podczas wyliczania listy kodów błędów, kody są pogrubiane (taka lista zwykle używa makra .TP).
Pełne polecenia, jeśli są długie, powinny być zapisywane w nowych liniach odpowiednio wciętych, na
przykład:
man 7 man-pages
Jeśli polecenie jest krótkie, to może być zawarte bezpośrednio w tekście zdania i napisane kursywą, na
przykład man 7 man-pages. W tym wypadku, można rozważyć użycie w odpowiednich miejscach polecenia spacji
nierozdzielających ("\ "). Opcje polecenia powinny być zapisywane kursywą, np. -l.
Wyrażenia, jeśli nie są zapisywane w osobnych, wciętych liniach, powinny być podawane kursywą. Ponownie,
jeśli wyrażenie jest włączone do zwykłego tekstu, to właściwe może być używanie spacji nierozdzielających
w tym wyrażeniu.
Każde odwołanie do programu, funkcji itp. będących tematem bieżącej strony podręcznika, powinno nazwę
zapisaną czcionką pogrubioną. Jeśli tematem jest funkcja (tj. bieżąca strona pochodzi z sekcji 2. lub
3.), to po nazwie powinna występować para nawiasów zapisanych czcionką roman (zwykłą). Na przykład w
stronie podręcznika fcntl(2) odwołania do tematu tej strony będą zapisane jako fcntl(). Preferowanym
sposobem zapisania tego w pliku źródłowym strony jest:
.BR fcntl ()
(Używanie tego formatu zamiast "\fB...\fP()" upraszcza pisanie narzędzi przetwarzających pliki źródłowe
stron podręcznika ekranowego).
Wszelkie odwołania do innych stron podręcznika powinny być pisane przy użyciu pogrubionej czcionki dla
nazwy strony, po której - bez rozdzielania spacjami - zawsze powinien następować numer sekcji pisany
czcionką zwykłą (niepogrubioną), np. intro(2). Preferowany sposób zapisania tego w kodzie źródłowym
strony jest następujący:
.BR intro (2)
(Dodawanie numerów sekcji w odwołaniach pozwala narzędziom takim jak man2html(1) na utworzenie stron
zawierających poprawne odnośniki hipertekstowe).
Pisownia
Od wersji 2.59 pakiet man-pages używa pisowni amerykańskiej. Prosimy przestrzegać tej konwencji
dotyczącej pisowni we wszystkich nowo pisanych stronach podręcznika ekranowego i podczas przesyłania nam
łat do istniejących stron.
Wielkie litery
W podsekcjach ("SS") wielką literą należy pisać tylko pierwsze słowo w tytule, z wyjątkiem sytuacji gdy
innego zapisu wymagają zasady językowe lub nazwy własne.
Przykładowe programy i sesje powłoki
Strony podręcznika mogą zawierać przykładowe programy pokazujące, jak używać wywołania systemowego lub
funkcji bibliotecznej. Jednakże proszę zauważyć, że:
* Przykładowe programy powinny być pisane w języku C.
* Zamieszczenie programu przykładowego jest konieczne i użyteczne tylko wtedy, gdy program ten pokazuje
coś, czego nie można w prosty sposób zawrzeć w tekstowym opisie demonstrowanego interfejsu. Program
przykładowy nie robiący nic poza wywoływaniem funkcji interfejsu zazwyczaj nie ma większego sensu.
* Przykładowy program powinien być raczej krótki (dobrze by było, gdyby miał mniej niż 100 linii,
idealnie - mniej niż 50 linii).
* Przykładowe programy nie powinny sprawdzać błędów wywołań systemowych czy funkcji bibliotecznych.
* Przykładowe programy powinny być kompletne i powinny się kompilować za pomocą cc -Wall bez wypisywania
żadnych ostrzeżeń.
* Kiedy tylko to możliwe i właściwe, programy przykładowe powinny pozwalać na eksperymenty, różnicując
swoje zachowanie zależnie od wejścia (idealnie pochodzącego z argumentów linii poleceń lub
alternatywnie z wejścia czytanego przez program).
* Przykładowe programy powinny być sformatowane w stylu "Kernighan & Ritchie" z wcięciami o rozmiarze
czterech spacji. (Nie należy używać znaków tabulacji w kodzie źródłowym!)
Przykłady wyglądu przykładowych programów można znaleźć w wait(2) i pipe(2).
Włączając sesję powłoki pokazującą użycie programu lub innej właściwości systemu, należy używać czcionki
pogrubionej dla tekstu wprowadzanego przez użytkownika, tak aby odróżnić go od tekstu produkowanego przez
system.
Wcięcia definicji struktur, logów sesji powłoki itp.
Definicje struktur, logi z sesji powłoki itp dołączane do tekstu powinny zawierać wcięcia o długości 4
spacji (tj. powinny być umieszczone w bloku otoczonym przez .in +4n i .in).
PRZYKŁAD
Wzorcowymi przykładami tego, jak powinny wyglądać strony podręczników z pakietu man-pages, są strony
pipe(2) i fcntl(2).
ZOBACZ TAKŻE
man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)
O STRONIE
Angielska wersja tej strony pochodzi z wydania 3.52 projektu Linux man-pages. Opis projektu oraz
informacje dotyczące zgłaszania błędów 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.52 oryginału.
Linux 2013-06-21 MAN-PAGES(7)