.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
.\" (faith@cs.unc.edu and dwheeler@ida.org)
.\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" 2007-05-30 created by mtk, using text from old man.7 plus
.\" rewrites and additional text.
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\" This file is distributed under the same license as original manpage
.\" Copyright of the original manpage:
.\" Copyright © 1992-1999 Rickard E. Faith, David A. Wheeler, 2007 Michael Kerrisk 
.\" Copyright © of Polish translation:
.\" Przemek Borys (PTM) <pborys@p-soft.silesia.linux.org.pl>, 1998.
.\" Robert Luberda <robert@debian.org>, 2006, 2012.
.\" Michał Kułach <michal.kulach@gmail.com>, 2013, 2014.
.TH MAN\-PAGES 7 2014\-08\-19 Linux "Podręcznik programisty Linuksa"
.SH NAZWA
man\-pages \- konwencje pisania linuksowych stron podręcznika ekranowego
.SH SKŁADNIA
\fBman\fP [\fIsekcja\fP] \fItytuł\fP
.SH OPIS
Strona opisuje konwencje, do których powinno się stosować podczas pisania
stron podręcznika ekranowego dla projektu Linux \fIman\-pages\fP, 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.
.SS "Sekcje stron podręcznika ekranowego"
.PP
Sekcje podręcznika man są tradycyjnie definiowane następująco:
.TP  10
\fB1 Komendy (programy)\fP
Te komendy mogą być wykonywane przez użytkownika z powłoki.
.TP 
\fB2 Wywołania systemowe\fP
Te funkcje muszą być obsługiwane przez jądro.
.TP 
\fB3 Wywołania biblioteczne\fP
Większość funkcji \fIlibc\fP.
.TP 
\fB4 Pliki specjalne (urządzenia)\fP
Pliki, które można znaleźć w \fI/dev\fP.
.TP 
\fB5 Formaty plików i konwencje\fP
Format dla pliku \fI/etc/passwd\fP i innych nadających się do odczytu przez
człowieka.
.TP 
\fB6 Gry\fP
.TP 
\fB7 Przegląd, konwencje i różnorodne\fP
Przegląd różnych tematów, konwencje, protokoły, standardy kodowania znaków i
inne.
.TP 
\fB8 Polecenia do zarządzania systemem\fP
.\" .TP
.\" .B 9 Kernel routines
.\" This is an obsolete manual section.
.\" Once it was thought a good idea to document the Linux kernel here,
.\" but in fact very little has been documented, and the documentation
.\" that exists is outdated already.
.\" There are better sources of
.\" information for kernel developers.
Komendy takie, jak \fBmount\fP(8), które wywoływać może tylko root .
.SS "Pakiety makr"
Nowe strony podręcznika powinny być pisane z użyciem pakietu makr \fBgroff
an.tmac\fP opisanego w \fBman\fP(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.
.SS "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ń.
.SS "Wiersz tytułowy"
Pierwszą komendą strony podręcznika powinno być polecenie \fBTH\fP:
.RS
.sp
\fB\&.TH\fP \fItytuł sekcja data źródło podręcznik\fP
.sp
.RE
gdzie:
.RS
.TP  10
\fItytuł\fP
Tytuł strony podręcznika, pisany w całości dużymi literami
(np. \fIMAN\-PAGES\fP).
.TP 
\fIsekcja\fP
Numer sekcji, w której strona powinna się znaleźć (np. \fI7\fP).
.TP 
\fIdata\fP
Data ostatniej nietrywialnej zmiany dokonanej w podręczniku. W projekcie
\fIman\-pages\fP konieczna aktualizacja tych dat jest wykonywana automatycznie
przez skrypty, dlatego nie ma konieczności zawierania ręcznej aktualizacji w
łatce). Daty powinny być zapisywane w postaci RRRR\-MM\-DD.
.TP 
\fIźródło\fP
Źródło polecenia, funkcji lub wywołania systemowego.

Dla tych kilku stron z pakietu \fIman\-pages\fP znajdujących się w sekcjach 1. i
8., najprawdopodobniej należy podać \fIGNU\fP.

Dla wywołań systemowych najodpowiedniejsze będzie \fILinux\fP. (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ć \fIGNU C library\fP, \fIGNU\fP
lub pustego łańcucha znaków.

Dla stron w sekcji 4., należy użyć \fILinux\fP.

W razie wątpliwości, prosimy użyć \fILinux\fP lub \fIGNU\fP.
.TP 
\fIpodręcznik\fP
Tytuł podręcznika (np. w sekcjach 2. i 3. stron z pakietu \fIman\-pages\fP
prosimy używać \fILinux Programmer's Manual\fP  (tj. \fIPodręcznik programisty
Linuksa\fP)).
.RE
.SS "Rozdziały stron podręcznika"
Poniższa lista pokazuje rozdziały konwencjonalne lub sugerowane. Większość
stron podręcznika powinna zawierać przynajmniej \fIwyróżnione\fP
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.
.in +0.5i
.nf

.\" May 07: Few current man pages have an ERROR HANDLING section,,,
.\" ERROR HANDLING,
.\" May 07: Almost no current man pages have a USAGE section,,,
.\" USAGE,
.\" DIAGNOSTICS,
.\" May 07: Almost no current man pages have a SECURITY section,,,
.\" SECURITY,
.\" AUTHORS sections are discouraged
.\" AUTHORS             [Discouraged]
\fBNAZWA\fP               (\fBNAME\fP)
\fBSKŁADNIA\fP            (\fBSYNOPSIS\fP)
KONFIGURACJA        (CONFIGURATION) [Zwykle tylko w sekcji 4.]
\fBOPIS\fP                (\fBDESCRIPTION\fP)
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)
WERSJE              (VERSIONS)      [Zwykle tylko w sekcjach 2., 3.]
ATRYBUTY            (ATTRIBUTES)    [Zwykle tylko w sekcjach 2., 3.]
ZGODNE Z            (CONFORMING TO)
UWAGI               (NOTES)
BŁĘDY [IMPLEMENTACJI] (BUGS)
PRZYKŁAD            (EXAMPLE)
\fBZOBACZ TAKŻE\fP        (\fBSEE ALSO\fP)

.fi
.in
W celu zachowania spójności i dla lepszego zrozumienia przekazywanych
informacji \fIprosimy używać zwyczajowych nagłówków wszędzie\fP, \fIgdzie mają
zastosowanie\fP. 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 (\fI.SS\fP) w rozdziałach opisanych tymi nagłówkami.

Poniżej opisujemy zawartość każdej z powyższych sekcji.
.TP  14
\fBNAZWA\fP
Nazwa strony podręcznika systemowego.

Podręcznik \fBman\fP(7) zawiera ważne detale na temat wierszy które powinny
znaleźć się za poleceniem \fB.SH NAZWA\fP. Wszystkie słowa w tym wierszu
(łącznie ze słowami występującymi zaraz za "\e\-") powinny być pisane małymi
literami z wyjątkiem konwencji terminologii lub wymagań językowych, które
mówią inaczej.
.TP 
\fBSKŁADNIA\fP
Zwięzłe podsumowanie interfejsu 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 \fB#include\fP, po
których następuje deklaracja funkcji.

.\" FIXME . Say something here about compiler options
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
\fBfeature_test_macros\fP(7).
.TP 
\fBKONFIGURACJA\fP
Szczegóły konfiguracji urządzenia.

Ta sekcja zazwyczaj występuje tylko w 4. sekcji stron podręcznika
ekranowego.
.TP 
\fBOPIS\fP
Opis tego, co robi dany program, funkcja lub format.

.\" If there is some kind of input grammar or complex set of subcommands,
.\" consider describing them in a separate
.\" .B USAGE
.\" section (and just place an overview in the
.\" .B DESCRIPTION
.\" section).
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 \fBOPCJE\fP.

Przy opisywaniu nowego zachowania lub nowych flag wywołania systemowego lub
funkcji bibliotecznej, proszę pamiętać o zanotowaniu wersji jądra lub
biblioteki C która wprowadziła tę zmianę. Zalecaną metodą przestawienia tej
informacji przy flagach jest postać części listy \fB.TP\fP, w następującej
formie (tutaj dla nowej flagi wywołania systemowego):
.RS 22
.TP 
\fBXYZ_FLAG\fP (od Linuksa 3.7)
Opis flagi...
.RE
.IP
Dołączenie informacji o wersji jest szczególnie ważne dla użytkowników
którzy są zmuszeni korzystać ze starszego jądra lub biblioteki C (co jest
powszechne w przypadku np. systemów wbudowanych).
.TP 
\fBOPCJE\fP
Opis opcji wiersza poleceń akceptowane przez program oraz sposób, w jaki
wpływają na jego zachowanie.

.\" .TP
.\" .B USAGE
.\" describes the grammar of any sublanguage this implements.
Rozdział powinien się pojawiać tylko w sekcjach 1. i 8. stron podręcznika
ekranowego.
.TP 
\fBKOD WYJŚCIA\fP
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.
.TP 
\fBWARTOŚĆ ZWRACANA\fP
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.
.TP 
\fBBŁĘDY\fP
W sekcjach 2. i 3. stron podręcznika jest to lista wartości, które mogą być
przypisane zmiennej \fIerrno\fP w razie wystąpienia błędu, łącznie z
informacjami o przyczynach tego błędu.

\fIElementy listy powinny być wymienione w porządku alfabetycznym\fP.
.TP 
\fBŚRODOWISKO\fP
Lista wszystkich zmiennych środowiskowych, wpływających na program i opis
tego wpływu.
.TP 
\fBPLIKI\fP
Lista plików używanych przez program lub funkcję, takich jak pliki
konfiguracyjne, pliki uruchomieniowe oraz pliki używane w czasie działania
programu.

.\" May 07: Almost no current man pages have a DIAGNOSTICS section;
.\"         "RETURN VALUE" or "EXIT STATUS" is preferred.
.\" .TP
.\" .B DIAGNOSTICS
.\" gives an overview of the most common error messages and how to
.\" cope with them.
.\" You don't need to explain system error messages
.\" or fatal signals that can appear during execution of any program
.\" unless they're special in some way to the program.
.\"
.\" May 07: Almost no current man pages have a SECURITY section.
.\".TP
.\".B SECURITY
.\"discusses security issues and implications.
.\"Warn about configurations or environments that should be avoided,
.\"commands that may have security implications, and so on, especially
.\"if they aren't obvious.
.\"Discussing security in a separate section isn't necessary;
.\"if it's easier to understand, place security information in the
.\"other sections (such as the
.\" .B DESCRIPTION
.\" or
.\" .B USAGE
.\" section).
.\" However, please include security information somewhere!
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 \fI/usr/local\fP, tak że strona podręcznika
powinna używać \fI/usr/local\fP jako podstawowego katalogu.
.TP 
\fBATRYBUTY\fP
Podsumowanie różnych atrybutów funkcji udokumentowanych na danej stronie
podręcznika podzielonych na podsekcje.

Zdefiniowano następujące podsekcje:
.sp
.RS
.TP 
\fBWielowątkowość (zob. pthreads(7))\fP
Podsekcja opisuje atrybuty odnoszące się do aplikacji wielowątkowych:
.RS
.IP * 3
Czy funkcja jest wątkowo bezpieczna.
.IP *
Czy funkcja jest punktem odwołania (ang. cancellation point).
.IP *
Czy funkcja jest bezpieczna pod względem anulowania wywołania
asynchronicznego.
.RE
.IP
Szczegóły tych atrybutów można znaleźć w \fBpthreads\fP(7).
.RE
.TP 
\fBWERSJE\fP
Zwięzłe podsumowanie wersji jądra Linux lub glibc, w których pojawiło się
wywołanie systemowe lub funkcja biblioteczna, albo w której znacznie
zmieniło się jej działania.

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 \fBsyscalls\fP(2) także dostarcza informacji o wersjach
jądra, w których pojawiły się różne wywołania systemowe.
.TP 
\fBZGODNE Z\fP
Opisuje standardy lub konwencje związane z opisywaną w podręczniku funkcją
lub opisywanym poleceniem.

Preferowane terminy do użycia w różnych standardach są wypisane jako
nagłówki w \fBstandards\fP(7).

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 \fBstandards\fP(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ą (".").
.TP 
\fBUWAGI\fP
Różnorodne uwagi.

W sekcjach 2. i 3. stron podręcznika ekranowego może być użyteczne
podzielenie tego rozdziału na podrozdziały (\fBSS\fP) nazywane \fIUwagi
linuksowe\fP i \fIUwagi dotyczące biblioteki glibc\fP.

W sekcji 2 proszę użyć nagłówka \fIRóżnice ABI biblioteki C/jądra\fP aby opisać
uwagi dotyczące różnic (jeśli takie występują) między funkcją opakowującą
biblioteki C dla wywołania systemowego i surowym interfejsem wywołania
systemowego zapewnianym przez jądro.
.TP 
\fBBŁĘDY\fP
Opis ograniczeń, znanych usterek lub niedogodności oraz innych
problematycznych aktywności.
.TP 
\fBPRZYKŁAD\fP
Jeden 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
\fIPrzykładowe programy\fP poniżej.
.TP 
\fBAUTORZY\fP
Lista autorów dokumentacji lub programu.

\fBUżywanie sekcji AUTORZY nie jest zalecane\fP. 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).
.TP 
\fBZOBACZ TAKŻE\fP
Rozdzielona przecinkami lista powiązanych stron podręcznika, po której mogą
występować inne powiązane strony lub dokumenty.

Lista powinna być posortowana po numerze sekcji, a następnie alfabetycznie
po nazwie. Nie należy umieszczać kropki na końcu listy.
.IP
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 \fI.ad l\fP
(nie wyrównuj do prawej strony) i \fI.nh\fP (nie dziel). Aby zapobiec dzieleniu
pojedynczych nazw podręczników należy je poprzedzić łańcuchem "\e%".
.SH STYLISTYKA
Poniższe podrozdziały opisują preferowany styl w projekcie
\fIman\-pages\fP. Szczegóły nie są opisane, dobrym źródłem jest zwykle Chicago
Manual of Style, proszę również przeszukać pliki obecne w drzewie źródeł
projektu.
.SS "Używanie języka neutralnego płciowo"
Tam gdzie się tylko da, należy używać języka neutralnego płciowo. Do tego
celu można posłużyć się słowami "they" ("them", "themself", "their").
.SS "Konwencje czcionek"
.PP
Dla funkcji, argumenty zawsze są podawane kursywą, \fInawet w rozdziale
SKŁADNIA\fP, w którym reszta funkcji jest wydrukowana w pogrubieniu:
.PP
\fB int myfunction(int \fP\fIargc\fP\fB, char **\fP\fIargv\fP\fB);\fP
.PP
Nazwy zmiennych podobnie jak nazwy argumentów powinny być pisane kursywą.
.PP
Nazwy plików (niezależnie od tego, czy są pełnymi ścieżkami czy
odniesieniami do plików nagłówkowych) są zawsze pisane kursywą
(np. \fI<stdio.h>\fP), z wyjątkiem nazw występujących w rozdziale
SKŁADNIA (SYNOPSIS), w którym pliki dołączane są wyróżniane pogrubieniem
(np. \fB#include <stdio.h>\fP). Odwołania do standardowych plików
nagłówkowych dołączanych powinny zawierać nazwę pliku nagłówkowego w
nawiasach trójkątnych, tak jak to jest przyjęte w języku C
(np. \fI<stdio.h>\fP).
.PP
Makra specjalne, które są zwykle pisane dużymi literami, są pogrubiane (np.
\fBMAXINT\fP). Wyjątek: nie pogrubiamy słowa NULL.
.PP
Podczas wyliczania listy kodów błędów, kody są pogrubiane (taka lista zwykle
używa makra \fB\&.TP).\fP
.PP
Pełne polecenia, jeśli są długie, powinny być zapisywane w nowych wierszach
odpowiednio wciętych, z pustym wierszem przed i po poleceniu, na przykład:
.in +4n
.nf

man 7 man\-pages

.fi
.in
Jeśli polecenie jest krótkie, to może być zawarte bezpośrednio w tekście
zdania i napisane kursywą, na przykład \fIman 7 man\-pages\fP. W tym wypadku,
można rozważyć użycie w odpowiednich miejscach polecenia spacji
nierozdzielających ("\e\ "). Opcje polecenia powinny być zapisywane kursywą
(np. \fI\-l\fP).
.PP
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.
.PP
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 \fBfcntl\fP(2) odwołania do tematu tej strony
będą zapisane jako \fBfcntl\fP(). Preferowanym sposobem zapisania tego w pliku
źródłowym strony jest:
.nf

    .BR fcntl ()

.fi
(Używanie tego formatu zamiast "\efB...\efP()" upraszcza pisanie narzędzi
przetwarzających pliki źródłowe stron podręcznika ekranowego).
.PP
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 \- \fIzawsze\fP powinien następować numer sekcji pisany czcionką zwykłą
(niepogrubioną), np. \fBintro\fP(2). Preferowany sposób zapisania tego w kodzie
źródłowym strony jest następujący:
.nf

    .BR intro (2)

.fi
(Dodawanie numerów sekcji w odwołaniach pozwala narzędziom takim jak
\fBman2html\fP(1) na utworzenie stron zawierających poprawne odnośniki
hipertekstowe).

Znaki kontrolne powinny być zapisywane czcionką pogrubioną, bez cytatów
np. \fB^X\fP.
.SS Pisownia
Od wersji 2.59 pakiet \fIman\-pages\fP używa pisowni amerykańskiej (wcześniej
była to losowa mieszanina pisowni amerykańskiej i brytyjskiej). 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.

Oprócz ogólnie znanych różnic jest też kilka subtelniejszych zmian których
trzeba pilnować.
.IP * 3
Amerykański angielski częściej używa form "backward", "upward", "toward"
itd. a angielski zwykle "backwards", upwards", "towards" itd.
.SS "Wersje BSD"
Klasyczny schemat zapisu wersji BSD to \fIx.yBSD\fP, gdzie \fIx.y\fP to wersja
(np. 4.2BSD). Proszę unikać form takich jak \fIBSD 4.3\fP.
.SS "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. Na przykład:

\&.SS Unikod w Linuksie

.SS "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  \fI.in\ +4n\fP i \fI.in\fP).
.SS "Preferowane terminy"
Poniższa tabela pokazuje część preferowanych terminów w stronach
podręcznika, głównie w celu zapewnienia spójności między poszczególnymi
podręcznikami.
.TS
l l l
---
l l l.
Termin	Niezalecany	Uwagi

bit mask	bitmask
built\-in	builtin
Epoch	epoch	T{
For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
T}
filename	file name
filesystem	file system
hostname	host name
inode	i\-node	w tłumaczeniach: i\-węzeł
lowercase	lower case, lower\-case
pathname	path name	w tłumaczeniach: ścieżka
pseudoterminal	pseudo\-terminal
privileged port	T{
reserved port,
system port
T}
real\-time	T{
realtime,
real time
T}
run time	runtime
saved set\-group\-ID	T{
saved group ID,
saved set\-GID
T}
saved set\-user\-ID	T{
saved user ID,
saved set\-UID
T}
set\-group\-ID	set\-GID, setgid
set\-user\-ID	set\-UID, setuid
superuser	T{
super user,
super\-user
T}
superblock	T{
super block,
super\-block
T}
timestamp	time stamp
timezone	time zone
uppercase	upper case, upper\-case
usable	useable
user space	userspace
username	user name
zeros	zeroes
.TE
.PP
Zob. też \fIZapis z dywizem przydawek złożonych\fP poniżej.
.SS "Terminy niezalecane"
Poniższa tabela pokazuje część niezalecanych terminów w stronach
podręcznika, razem z proponowanymi alternatywami, głównie w celu zapewnienia
spójności między poszczególnymi podręcznikami.
.TS
l l l
---
l l l.
Niezalecane	Zalecane	Uwagi

32bit	32\-bit	T{
podobnie 8\-bit, 16\-bit, etc.
T}
current process	calling process	T{
Częsty błąd programistów jądra
T}
manpage	T{
man page, manual page
T}
minus infinity	negative infinity
non\-root	unprivileged user
non\-superuser	unprivileged user
nonprivileged	unprivileged
OS	operating system
plus infinity	positive infinity
pty	pseudoterminal
tty	terminal
Unices	UNIX systems
Unixes	UNIX systems
.TE
.SS "Znaki towarowe"
Proszę używać poprawnego zapisu znaków towarowych. Poniższa lista zawiera
poprawne zapisy różnych znaków towarowych, które są niekiedy zapisywane
niepoprawnie:

     DG/UX
     HP\-UX
     UNIX
     UnixWare
.SS "NULL, NUL, wskaźnik null i znak null"
A \fIwskaźnik null\fP jest wskaźnikiem wskazującym na nic i pojawia się zwykle
jako stała \fINULL\fP. \fINUL\fP jest \fIbajtem null\fP, bajtem o wartości 0,
reprezentowanym w C jako stałą znakowa \fI\(aq\e0\(aq\fP.

Preferowanym terminem na wskaźnik jest "wskaźnik null" lub "NULL"; proszę
unikać terminu "wskaźnik NULL".

Preferowanym terminem w kontekście bajtów jest "bajt null". Proszę unikać
terminu "NUL", ponieważ jest on łatwy do pomylenia z  "NULL". Proszę starać
się nie używać również "bajt zerowy" i "znak null". Bajt który przerywa
łańcuch C powinien być opisywany jako "przerywający bajt null"; łańcuchy te
można nazwać "null\-terminated", lecz proszę unikać terminu "NUL\-terminated".
.SS Odnośniki
Odnośniki tworzy się parą makr \fI.UR\fP/\fI.UE\fP (zob. \fBgroff_man\fP(7)). W ten
sposób tworzy się poprawne odnośniki których można użyć w przeglądarce
internetowej przy renderowaniu strony przez np.:

     BROWSER=firefox man \-H nazwa\-strony
.SS "Używanie e.g., i.e., etc., a.k.a. i podobnych"
Ogólnie rzecz biorąc powinno się unikać skrótów takich jak "e.g.", "i.e.",
"etc.", "a.k.a." na rzecz pełnego zapisu ("for example", "that is", "and so
on", "also known as").

Jedynym miejscem gdzie skróty są dopuszczone to \fIkrótkie\fP wtrącenia
(np. takie jak to).

Zawsze należy zapisywać te skróty z kropką. Dodatkowo "e.g." i "i.e."
powinny zawsze kończyć się przecinkiem.
.SS "Pauza \(dqem\(dq"
Sposobem zapisu pauzy "em" \(em znaku który pojawia się na obu końcach tego
wtrącenia \(em w *roff jest macro "\em(em". Na terminalu ASCII pauza "em"
jest zwykle renderowana jako dwa dywizy, lecz w innych sytuacjach pokazuje
się jako długa pauza. Pauza "em" w języku angielskim powinna być zapisywana
\fIbez\fP otaczających ją spacji.
.SS "Zapis z dywizem przydawek złożonych"
Terminy złożone powinny być zapisywane z dywizem, gdy są używane w formie
przydawki. Przykłady:

    32\-bit value
    command\-line argument
    floating\-point number
    run\-time check
    user\-space function
    wide\-character string
.SS "Zapis z dywizem przedrostków multi, non, pre, re, sub itd."
Ogólną tendencją we współczesnym angielskim jest nie stosowanie zapisu po
przedrostkach takich jak "multi", "non", "pre", "re", "sub" itd. Strony
podręcznika powinny z reguły stosować się do tej zasady tam, gdzie
przedrostki są używane w naturalnych dla angielskiego konstrukcjach z
prostymi przedrostkami. Poniższa lista daje pogląd na preferowane formy:

    interprocess
    multithreaded
    multiprocess
    nonblocking
    nondefault
    nonempty
    noninteractive
    nonnegative
    nonportable
    nonzero
    preallocated
    precreate
    prerecorded
    reestablished
    reinitialize
    rearm
    reread
    subcomponent
    subdirectory
    subsystem

Dywizy powinny być zachowane w przedrostkach używanych w niestandardowych
dla angielskiego słowach, w znakach towarowych, rzeczownikach tego
wymagających, akronimach lub zwrotach złożonych. Przykłady:

    non\-ASCII
    non\-English
    non\-NULL
    non\-real\-time

Proszę zauważyć, że "re\-create" i "recreate" to dwa odrębne czasowniki, przy
czym prawdopodobnie chcemy wykorzystać ten pierwszy.
.SS "Rzeczywisty znak minus"
Gdy wymagany jest prawdziwy znak minus (np. w przypadku liczb takich jak \-1
lub przy zapisywaniu opcji z początkowym dywizem, takich jak \fIls\ \-l\fP),
proszę używać następującej postaci w źródłach stron podręcznika:

    \e\-

Zalecenie to dotyczy też przykładów kodu.
.SS "Stałe znakowe"
Aby utworzyć znak pojedynczego cudzysłowu który wyświetla się poprawnie w
stronach ASCII i UTF\-8 proszę używać następującej stałej znakowej w źródłach
stron podręcznika:

    \e(aqC\e(aq

gdzie \fIC\fP jest cytowanym znakiem. Zalecenie do tyczy się również stałych
znakowych używanych w przykładach kodu.
.SS "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:
.IP * 3
Przykładowe programy powinny być pisane w języku C.
.IP *
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.
.IP *
Przykładowy program powinien być raczej krótki (dobrze by było, gdyby miał
mniej niż 100 linii, idealnie \- mniej niż 50 linii).
.IP *
Przykładowe programy nie powinny sprawdzać błędów wywołań systemowych czy
funkcji bibliotecznych.
.IP *
Przykładowe programy powinny być kompletne i powinny się kompilować za
pomocą \fIcc\ \-Wall\fP bez wypisywania żadnych ostrzeżeń.
.IP *
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).
.IP *
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!)
.IP *
W celu zachowania spójności, wszystkie przykładowe programy powinny się
kończyć jednym z poniższych:

     exit(EXIT_SUCCESS);
     exit(EXIT_FAILURE);

Proszę unikać poniższy form w celu zakończenia programu:

    exit(0);
    exit(1);
    return n;
.IP *
Jeśli przed kodem źródłowym znajduje się wyczerpujące wyjaśnienie, kod
źródłowy powinien być oznaczony podrozdziałem \fIKod źródłowy programu\fP, jak
w przykładzie:

\&.SS Kod źródłowy programu

Zawsze należy go zastosować, jeśli wyjaśnienie zawiera log z sesji powłoki.
.PP
Włączając sesję powłoki pokazującą użycie programu lub innej właściwości
systemu:
.IP * 3
Należy umieścić log z sesji powyżej kodu źródłowego
.IP *
Należy wciąć log z sesji czterema spacjami.
.IP *
Należy używać czcionki pogrubionej dla tekstu wprowadzanego przez
użytkownika, tak aby odróżnić go od tekstu produkowanego przez system.
.PP
Przykłady wyglądu przykładowych programów można znaleźć w \fBwait\fP(2) i
\fBpipe\fP(2).
.SH PRZYKŁAD
Wzorcowymi przykładami tego, jak powinny wyglądać strony podręczników z
pakietu \fIman\-pages\fP, są strony \fBpipe\fP(2) i \fBfcntl\fP(2).
.SH "ZOBACZ TAKŻE"
\fBman\fP(1), \fBman2html\fP(1), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7),
\fBmdoc\fP(7)
.SH "O STRONIE"
Angielska wersja tej strony pochodzi z wydania 3.71 projektu Linux
\fIman\-pages\fP. 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/.
.SH 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>.
.PP
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ą \fB 3.71 \fPoryginału.