Ubuntu Manpage: man-pages - konwencje pisania linuksowych stron podręcznika ekranowego

NAZWA

       man-pages - konwencje pisania linuksowych stron podręcznika ekranowego

SKŁADNIA

       man [sekcja] tytuł

OPIS

This page describes the conventions that should be employed when writing man pages for the
Linux man-pages project, which documents the user-space API provided by the Linux kernel
and the GNU C library. The project thus provides most of the pages in Section 2, many of
the pages that appear in Sections 3, 4, and 7, and a few of the pages that appear in
Sections 1, 5, and 8 of the man pages on a Linux system. The conventions described on
this page may also be useful for authors writing man pages for other projects.

Sekcje stron podręcznika ekranowego
Sekcje podręcznika man są tradycyjnie definiowane następująco:

1 Komendy użytkownika (programy)
Commands that can be executed by the user from within a shell.

2 Wywołania systemowe
Functions which wrap operations performed by the kernel.

3 Wywołania biblioteczne
Wszystkie funkcje biblioteczne z wyłączeniem opakowań wywołań systemowych
(większość z funkcji libc).

4 Pliki specjalne (urządzenia)
Pliki w /dev pozwalające na dostęp do urządzenia poprzez jądro.

5 Formaty plików i pliki konfiguracyjne
Opisują różne czytelne dla człowieka formaty plików i pliki konfiguracyjne.

6 Gry Gry i zabawne programiki dostępne w systemie.

7 Przegląd, konwencje i różnorodne
Przegląd i opsi różnych tematów, konwencje, protokoły, standardy kodowania znaków,
standardowego wyglądu systemu plikó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.

Linia tytułowa
Pierwszą komendą strony podręcznika powinno być polecenie TH:

.TH title section date source manual-section

The arguments of the command are as follows:

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 nietrywialnej zmiany dokonanej w podręczniku. W projekcie man-pages
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.

źródło The name and version of the project that provides the manual page (not necessarily
the package that provides the functionality).

manual-section
Normally, this should be empty, since the default value will be good.

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
BIBLIOTEKA [Normally only in Sections 2, 3]
SKŁADNIA
KONFIGURACJA [Normally only in Section 4]
OPIS
OPCJE [Normally only in Sections 1, 8]
KOD ZAKOŃCZENIA [Normally only in Sections 1, 8]
WARTOŚĆ ZWRACANA [Normally only in Sections 2, 3]
BŁĘDY [Typically only in Sections 2, 3]
ŚRODOWISKO
PLIKI
WERSJE [Normally only in Sections 2, 3]
ATRYBUTY [Normally only in Sections 2, 3]
STANDARDY
UWAGI
CAVEATS
BŁĘDY
PRZYKŁADY
AUTORZY [Discouraged]
ZGŁASZANIE BŁĘDÓW [Not used in man-pages]
PRAWA AUTORSKIE [Not used in man-pages]
ZOBACZ TAKŻE

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 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.

LIBRARY
The library providing a symbol.

It shows the common name of the library, and in parentheses, the name of the
library file and, if needed, the linker flag needed to link a program against it:
(libfoo[, -lfoo]).

SKŁADNIA
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 #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 Opis tego, 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.

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 .TP, w następującej formie (tutaj dla nowej flagi
wywołania systemowego):

XYZ_FLAG (od Linuksa 3.7)
Opis flagi...

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

OPCJE Opis opcji wiersza 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.

Where several different conditions produce the same error, the preferred approach
is to create separate list entries (with duplicate error names) for each of the
conditions. This makes the separate conditions clear, may make the list easier to
read, and allows metainformation (e.g., kernel version number where the condition
first became applicable) to be more easily marked for each condition.

Elementy listy powinny być wymienione w porządku alfabetycznym.

ŚRODOWISKO
Lista wszystkich zmiennych środowiskowych, wpływających na program i opis tego
wpływu.

PLIKI Lista 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. Więcej informacji w podręczniku attributes(7).

WERSJE 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.

As a general rule, every new interface should include a VERSIONS section in its
manual page. Unfortunately, many existing manual pages don't include this
information (since there was no policy to do so when they were written). Patches
to remedy this are welcome, but, from the perspective of programmers writing new
code, this information probably matters only in the case of kernel interfaces that
have been added in Linux 2.4 or later (i.e., changes since Linux 2.2), and library
functions that have been added to glibc since glibc 2.1 (i.e., changes since glibc
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.

STANDARDY
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
standards(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 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 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.

W sekcji 2 proszę użyć nagłówka Różnice biblioteki C/jądra 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.

CAVEATS
Warnings about typical user misuse of an API, that don't constitute an API bug or
design defect.

BŁĘDY Opis ograniczeń, znanych usterek lub niedogodności oraz innych problematycznych
aktywności.

EXAMPLES
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 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).

ZGŁASZANIE BŁĘDÓW
The man-pages project doesn't use a REPORTING BUGS section in manual pages.
Information on reporting bugs is instead supplied in the script-generated COLOPHON
section. However, various projects do use a REPORTING BUGS section. It is
recommended to place it near the foot of the page.

PRAWA AUTORSKIE
The man-pages project doesn't use a COPYRIGHT section in manual pages. Copyright
information is instead maintained in the page source. In pages where this section
is present, it is recommended to place it near the foot of the page, just above SEE
ALSO.

ZOBACZ TAKŻE
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.

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 "\%".

Biorąc pod uwagę rozproszoną i autonomiczną naturę projektów WiOO i jej
dokumentacji, często jest konieczne i w wielu przypadkach pożądane, aby sekcja
ZOBACZ TEŻ zawierała odniesienia do podręczników systemowych udostępnianych przez
inne projekty.

FORMATTING AND WORDING CONVENTIONS

       The  following  subsections  note  some  details  for  preferred  formatting  and  wording
       conventions in various sections of the pages in the man-pages project.

   SKŁADNIA
       Wrap the function prototype(s) in a .nf/.fi pair to prevent filling.

       In general, where more  than  one  function  prototype  is  shown  in  the  SYNOPSIS,  the
       prototypes  should  not be separated by blank lines.  However, blank lines (achieved using
       .PP)  may be added in the following cases:

       •  to separate long lists of function prototypes into  related  groups  (see  for  example
          list(3));

       •  in other cases that may improve readability.

       In the SYNOPSIS, a long function prototype may need to be continued over to the next line.
       The continuation line is indented according to the following rules:

       (1)  If there is a single such prototype that  needs  to  be  continued,  then  align  the
            continuation  line  so  that  when  the page is rendered on a fixed-width font device
            (e.g., on an xterm) the continuation line starts just below the start of the argument
            list  in the line above.  (Exception: the indentation may be adjusted if necessary to
            prevent a very long continuation line  or  a  further  continuation  line  where  the
            function prototype is very long.)  As an example:

                int tcsetattr(int fd, int optional_actions,
                              const struct termios *termios_p);

       (2)  But,  where  multiple  functions  in the SYNOPSIS require continuation lines, and the
            function names have different lengths, then align all continuation lines to start  in
            the same column.  This provides a nicer rendering in PDF output (because the SYNOPSIS
            uses a variable width font where spaces render narrower than most characters).  As an
            example:

                int getopt(int argc, char * const argv[],
                           const char *optstring);
                int getopt_long(int argc, char * const argv[],
                           const char *optstring,
                           const struct option *longopts, int *longindex);

   WARTOŚĆ ZWRACANA
       The preferred wording to describe how errno is set is "errno is set to indicate the error"
       or similar.  This wording is consistent with the wording used in both POSIX.1 and FreeBSD.

   ATRYBUTY
       Note the following:

       •  Wrap the table in this section in a .ad l/.ad  pair  to  disable  text  filling  and  a
          .nh/.hy pair to disable hyphenation.

       •  Ensure  that  the  table  occupies  the  full  page  width  through  the  use of an lbx
          description for one of the columns (usually the first column, though in some cases  the
          last column if it contains a lot of text).

       •  Make  free  use  of  T{/T}  macro pairs to allow table cells to be broken over multiple
          lines (also bearing in mind that pages may sometimes be rendered to  a  width  of  less
          than 80 columns).

       For examples of all of the above, see the source code of various pages.

STYLISTYKA

Poniższe podrozdziały opisują preferowany styl w projekcie man-pages. 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.

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").

Formatting conventions for manual pages describing commands
For manual pages that describe a command (typically in Sections 1 and 8), the arguments
are always specified using italics, even in the SYNOPSIS section.

The name of the command, and its options, should always be formatted in bold.

Formatting conventions for manual pages describing functions
For manual pages that describe functions (typically in Sections 2 and 3), the arguments
are always specified using italics, even in the SYNOPSIS section, where the rest of the
function is specified in bold:

int myfunction(int argc, char **argv);

Nazwy zmiennych podobnie jak nazwy argumentów powinny być pisane kursywą.

Any reference to the subject of the current manual page should be written with the name in
bold followed by a pair of parentheses in Roman (normal) font. For example, in the
fcntl(2) man page, references to the subject of the page would be written as: fcntl().
The preferred way to write this in the source file is:

.BR fcntl ()

(Używanie tego formatu zamiast "\fB...\fP()" upraszcza pisanie narzędzi przetwarzających
pliki źródłowe stron podręcznika ekranowego).

Use semantic newlines
In the source of a manual page, new sentences should be started on new lines, long
sentences should be split into lines at clause breaks (commas, semicolons, colons, and so
on), and long clauses should be split at phrase boundaries. This convention, sometimes
known as "semantic newlines", makes it easier to see the effect of patches, which often
operate at the level of individual sentences, clauses, or phrases.

Lists
There are different kinds of lists:

Tagged paragraphs
These are used for a list of tags and their descriptions. When the tags are
constants (either macros or numbers) they are in bold. Use the .TP macro.

An example is this "Tagged paragraphs" subsection is itself.

Ordered lists
Elements are preceded by a number in parentheses (1), (2). These represent a set
of steps that have an order.

When there are substeps, they will be numbered like (4.2).

Positional lists
Elements are preceded by a number (index) in square brackets [4], [5]. These
represent fields in a set. The first index will be:

0 When it represents fields of a C data structure, to be consistent with
arrays.
1 When it represents fields of a file, to be consistent with tools like
cut(1).

Alternatives list
Elements are preceded by a letter in parentheses (a), (b). These represent a set
of (normally) exclusive alternatives.

Bullet lists
Elements are preceded by bullet symbols (\[bu]). Anything that doesn't fit
elsewhere is usually covered by this type of list.

Numbered notes
Not really a list, but the syntax is identical to "positional lists".

There should always be exactly 2 spaces between the list symbol and the elements. This
doesn't apply to "tagged paragraphs", which use the default indentation rules.

Formatting conventions (general)
Paragraphs should be separated by suitable markers (usually either .PP or .IP). Do not
separate paragraphs using blank lines, as this results in poor rendering in some output
formats (such as PostScript and PDF).

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. <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 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. <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 wierszach odpowiednio
wciętych, z pustym wierszem przed i po poleceniu, 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.

When showing example shell sessions, user input should be formatted in bold, for example

$ date
Thu Jul 7 13:01:27 CEST 2016

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

Znaki kontrolne powinny być zapisywane czcionką pogrubioną, bez cytatów np. ^X.

Pisownia
Od wersji 2.59 pakiet man-pages 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ć.

• Amerykański angielski częściej używa form "backward", "upward", "toward" itd. a
angielski zwykle "backwards", upwards", "towards" itd.

• Opinions are divided on "acknowledgement" vs "acknowledgment". The latter is
predominant, but not universal usage in American English. POSIX and the BSD license
use the former spelling. In the Linux man-pages project, we use "acknowledgement".

Wersje BSD
Klasyczny schemat zapisu wersji BSD to x.yBSD, gdzie x.y to wersja (np. 4.2BSD). Proszę
unikać form takich jak BSD 4.3.

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

Wcięcia definicji struktur, logów sesji powłoki itp.
When structure definitions, shell session logs, and so on are included in running text,
indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the
.EX and .EE macros, and surround them with suitable paragraph markers (either .PP or .IP).
For example:

.PP
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
.PP

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.

Termin Niezalecany Uwagi
───────────────────────────────────────────────────────────────────
bit mask bitmask

built-in builtin
Epoch epoch For the UNIX Epoch
(00:00:00, 1 Jan
1970 UTC)
filename file name
filesystem file system
hostname host name
inode i-node
lowercase lower case, lower-case
nonzero non-zero
pathname path name
pseudoterminal pseudo-terminal
privileged port reserved port, system
port
real-time realtime, real time
run time runtime
saved set-group-ID saved group ID, saved
set-GID
saved set-user-ID saved user ID, saved
set-UID
set-group-ID set-GID, setgid
set-user-ID set-UID, setuid
superuser super user, super-user
superblock super block,
super-block
symbolic link symlink
timestamp time stamp
timezone time zone
uppercase upper case, upper-case
usable useable
user space userspace
username user name
x86-64 x86_64 Except if referring
to result of
"uname -m" or
similar
zeros zeroes

Zob. też Zapis z dywizem przydawek złożonych poniżej.

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.

Niezalecane Zalecane Uwagi
───────────────────────────────────────────────────────────────────

32bit 32-bit podobnie 8-bit, 16-bit,
etc.
current process calling process Częsty błąd programistów
jądra piszących strony
podręcznika ekranowego
manpage man page, manual page
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

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

NULL, NUL, null pointer, and null byte
A wskaźnik null jest wskaźnikiem wskazującym na nic i pojawia się zwykle jako stała NULL.
NUL jest bajtem null, bajtem o wartości 0, reprezentowanym w C jako stałą znakowa '\0'.

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".

Odnośniki
Odnośniki tworzy się parą makr .UR/.UE (zob. groff_man(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

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.", "cf.",
"a.k.a." na rzecz pełnego zapisu ("for example", "that is", "and so on", "compare to",
"also known as").

Jedynym miejscem gdzie skróty są dopuszczone to krótkie 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.

Pauza "em"
Sposobem zapisu pauzy "em" — znaku który pojawia się na obu końcach tego wtrącenia — w
*roff jest macro "\[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 bez otaczających ją spacji.

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

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.

Generating optimal glyphs
Where a real minus character is required (e.g., for numbers such as -1, for man page cross
references such as utf-8(7), or when writing options that have a leading dash, such as in
ls -l), use the following form in the man page source:

Zalecenie to dotyczy też przykładów kodu.

The use of real minus signs serves the following purposes:

• To provide better renderings on various targets other than ASCII terminals, notably in
PDF and on Unicode/UTF-8-capable terminals.

• To generate glyphs that when copied from rendered pages will produce real minus signs
when pasted into a terminal.

To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, use "\[aq]"
("apostrophe quote"); for example

\[aq]C\[aq]

gdzie C jest cytowanym znakiem. Zalecenie do tyczy się również stałych znakowych używanych
w przykładach kodu.

Where a proper caret (^) that renders well in both a terminal and PDF is required, use
"\[ha]". This is especially necessary in code samples, to get a nicely rendered caret
when rendering to PDF.

Using a naked "~" character results in a poor rendering in PDF. Instead use "\[ti]".
This is especially necessary in code samples, to get a nicely rendered tilde when
rendering to PDF.

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.

• Example programs should ideally be short (e.g., a good example can often be provided in
less than 100 lines of code), though in some cases longer programs may be necessary to
properly illustrate the use of an API.

• Expressive code is appreciated.

• Comments should included where helpful. Complete sentences in free-standing comments
should be terminated by a period. Periods should generally be omitted in "tag"
comments (i.e., comments that are placed on the same line of code); such comments are
in any case typically brief phrases rather than complete sentences.

• 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!).
Można użyć poniższego polecenia do sformatowania swojego kodu źródłowego do stylu
bliskiego pożądanemu:

indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c

• 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;

• Jeśli przed kodem źródłowym znajduje się wyczerpujące wyjaśnienie, kod źródłowy
powinien być oznaczony podrozdziałem Kod źródłowy programu, 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.

Włączając sesję powłoki pokazującą użycie programu lub innej właściwości systemu:

• Należy umieścić log z sesji powyżej kodu źródłowego.

• Należy wciąć log z sesji czterema spacjami.

• Należy używać czcionki pogrubionej dla tekstu wprowadzanego przez użytkownika, tak aby
odróżnić go od tekstu produkowanego przez system.

Przykłady wyglądu przykładowych programów można znaleźć w wait(2) i pipe(2).

PRZYKŁADY

       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), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)

TŁUMACZENIE

       Autorami  polskiego  tłumaczenia  niniejszej  strony   podręcznika   są:   Przemek   Borys
       <pborys@dione.ids.pl>,    Robert    Luberda    <robert@debian.org>    i    Michał   Kułach
       <michal.kulach@gmail.com>

       Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe  informacje  o  warunkach  licencji
       można   uzyskać   zapoznając   się   z   GNU   General   Public   License   w   wersji   3
       ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩  lub  nowszej.  Nie   przyjmuje   się   ŻADNEJ
       ODPOWIEDZIALNOŚCI.

       Błędy  w  tłumaczeniu  strony  podręcznika  prosimy  zgłaszać  na  adres listy dyskusyjnej
       ⟨manpages-pl-list@lists.sourceforge.net⟩.