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

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

Wiersz tytułowy
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 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 Ź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)
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)
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 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 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.

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

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

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

PRZYKŁAD 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).

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

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

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

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

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.

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

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 w tłumaczeniach: i-węzeł
lowercase lower case, lower-case
pathname path name w tłumaczeniach: ścieżka
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
timestamp time stamp
timezone time zone
uppercase upper case, upper-case
usable useable
user space userspace
username user name
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
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, wskaźnik null i znak null
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.",
"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 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 "\m(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.

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 ls -l), proszę używać następującej
postaci w źródłach stron podręcznika:

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

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:

\(aqC\(aq

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

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

* 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Ł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.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)
       <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.71
       oryginału.