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, wielu podręczników z sekcji 3, 4 i 7 oraz niektórych podręczników z sekcji 1, 5
i 8. 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 użytkownika (programy)
Komendy mogą być wykonywane przez użytkownika z powłoki.

2 Wywołania systemowe
Funkcje opakowują operacje wykonywane przez jądro.

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 tytuł sekcja data źródło rozdział-podręcznika

Argumenty komendy są następujące:

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 Nazwa i wersja projektu udostępniającego stronę podręcznika (niekoniecznie będzie to pakiet, który
udostępnia samą funkcjonalność).

rozdział-podręcznika
Zwykle pole to powinno pozostać puste, jako że wartość domyślna jest wystarczająca.

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 [Zwykle tylko w sekcjach 2 i 3]
SKŁADNIA
KONFIGURACJA [Zwykle tylko w sekcji 4]
OPIS
OPCJE [Zwykle tylko w sekcjach 1 i 8]
STATUS ZAKOŃCZENIA [Zwykle tylko w sekcjach 1 i 8]
WARTOŚĆ ZWRACANA [Zwykle tylko w sekcjach 2 i 3]
BŁĘDY [Zwykle tylko w sekcjach 2 i 3]
ŚRODOWISKO
PLIKI
ATRYBUTY [Zwykle tylko w sekcjach 2 i 3]
WERSJE [Zwykle tylko w sekcjach 2 i 3]
STANDARDY
HISTORIA
UWAGI
ZASTRZEŻENIA
USTERKI
PRZYKŁADY
AUTORZY [Odradzane]
ZGŁASZANIE BŁĘDÓW [Nieużywane w projekcie man-pages]
PRAWA AUTORSKIE [Nieużywane w projekcie 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.

BIBLIOTEKA
Biblioteka udostępniająca symbol.

Pokazywana jest tu ogólna nazwa biblioteki, następnie, w nawiasie, nazwa pliku biblioteki oraz,
jeśli to potrzebne, flaga konsolidatora wymaganego do podlinkowania do niego programu (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.

Gdy wiele różnych warunków wywołuje ten sam błąd, preferowanym podejściem jest utworzenie
odrębnych wpisów listy (z powtórzonymi nazwami błędów) dla każdego z warunków. W ten sposób jasna
będzie rozdzielność warunków, w których wystąpił błąd, lista może być czytelniejsza oraz można
podać dodatkowe informacje specyficzne dla każdego z warunków (np. wersję jądra, w której po raz
pierwszy wystąpił dany warunek).

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 Podsumowanie systemów, na których API zachowuje się odmiennie lub gdzie występuje podobne API.

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

Ten rozdział powinien odnotowywać obecne standardy, z którymi zgodne jest API.

Jeśli API nie jest zamieszczone w żadnym standardzie, ale zwyczajowo istnieje w innych systemach,
prosimy wymienić te systemy. Jeśli wywołanie jest specyficzne dla Linuksa lub GNU, również należy
o tym poinformować. Należy zamieścić również wzmiankę, jeśli jest dostępne w BSD.

Jeśli rozdział zawiera tylko i wyłącznie listę standardów (a tak jest zazwyczaj), lista ta powinna
być zakończona kropką (".").

HISTORIA
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ł HISTORIA.
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 Linuksa 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.

Stare wersje standardów należy odnotować tutaj, zamiast w rozdziale STANDARDY, przykładami są standardy
implementacji SVr4 i 4.xBSD albo SUS, SUSv2 i XPG.

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.

ZASTRZEŻENIA
Ostrzeżenia o częstym sposobie błędnego stosowania API przez użytkowników, niebędące błędem API
ani błędem projektowym.

USTERKI
Opis ograniczeń, znanych usterek lub niedogodności oraz innych problematycznych aktywności.

PRZYKŁADY
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 USTERKI.

ZGŁASZANIE BŁĘDÓW
Projekt man-pages nie używa rozdziału ZGŁASZANIE BŁĘDÓW w stronach podręcznika systemowego.
Informacje na ten temat są dostarczane w sekcji KOLOFON generowanej skryptem. Wiele projektów
dodaje jednak rozdział ZGŁASZANIE BŁĘDÓW. Zaleca się umieszczenie go blisko końca strony.

PRAWA AUTORSKIE
Projekt man-pages nie używa rozdziału PRAW AUTORSKICH w stronach podręcznika, informacje na ten
temat znajdują się bowiem w źródle strony. W stronach, w których ten rozdział jest obecny, zaleca
się umieszczenie go blisko końca strony, tuż nad ZOBACZ TAKŻE.

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.

KONWENCJE REDAKCYJNE I DOTYCZĄCE FORMATOWANIA

       Poniższe  podrozdziały  opisują  wybór  szczegółowych   rozwiązań   dotyczących   preferowanego   sposobu
       formatowania oraz redagowania różnych rozdziałów w projekcie man-pages.

   SKŁADNIA
       Należy umieścić prototyp(y) funkcji w .nf/.fi, aby uniknąć wypełniania.

       Gdy  w  składni  wskazany  jest  więcej  niż  jeden  prototyp  funkcji,  prototypy nie powinny być zwykle
       rozdzielone pustym wierszem. Można je jednak zastosować (używając .PP) w następujących przypadkach:

       •  do rozdzielenia długiej listy prototypów funkcji w powiązane grupy (zob. np. list(3));

       •  w innych przypadkach poprawiających czytelność.

       W SKŁADNI, długi prototyp funkcji może wymagać kontynuacji w  nowym  wierszu.  Wiersz  ten  należy  wciąć
       zgodnie z następującymi zasadami:

       (1)  Jeśli  istnieje  pojedynczy prototyp wymagający kontynuacji, należy wyrównać wiersz kontynuacji tak,
            aby zaczynał się tuż pod początkiem listy argumentów z wiersza powyżej, biorąc pod  uwagę  przypadek
            renderowania  na  urządzeniu  ze  stałą  szerokością  fontu  (np.  na xterm) (wyjątek: wcięcie można
            dostosować, aby uniknąć bardzo długiego wiersza kontynuacji lub  aby  zapobiec  kolejnemu  wierszowi
            kontynuacji, gdy prototyp funkcji jest bardzo długi). Przykład:

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

       (2)  Jednak  gdy  wiele  funkcji  w  SKŁADNI  wymaga  wierszy kontynuacji i nazwy funkcji mogą mieć różną
            długość, należy wyrównać wszystkie wiersze kontynuacji, aby zaczynały się w tej samej kolumnie. Daje
            to lepsze renderowanie w wyjściu PDF (ponieważ SKŁADNIA używa fontu o zmiennej szerokości, w  którym
            spacje są renderowane jako znaki węższe niż większość pozostałych). Przykład:

                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
       Preferowanym  sposobem  zapisu  ustawienia  errno jest "ustawiane jest errno wskazując błąd" lub podobne.
       Jest to spójne z redakcją użytą w POSIX.1 oraz FreeBSD.

   ATRYBUTY
       Proszę zauważyć, co następuje:

       •  Proszę opakowywać tabelę w tym rozdziale w .ad l/.ad, aby uniknąć wypełniania tekstu  oraz  w  .nh/.hy
          aby wyłączyć dzielenie słów.

       •  Proszę  upewnić  się,  że  tabela  zajmuje  całą szerokość strony, korzystając z opisu lbx do jednej z
          kolumn (zwykle pierwszej, choć w niektórych przypadkach dobrym wyborem jest  ostatnia,  jeśli  zawiera
          dużo tekstu).

       •  Można  swobodnie  stosować  makro  T{/T}  pozwalając  na  przełamanie  komórek tabeli na wiele wierszy
          (pamiętając, że strony mogą być czasem renderowane na szerokość mniejszą niż 80 kolumn).

       Aby zobaczyć zastosowania powyższych uwag, należy sprawdzić źródła różnych stron podręcznika.

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 formatowania do stron podręcznika opisujących polecenia
W przypadku stron podręcznika opisujących polecenia (zwykle w sekcji 1 i 8), argumenty zawsze są podawane
kursywą, nawet w rozdziale SKŁADNIA.

Nazwa polecenia i jego opcji powinny być zawsze formatowe w pogrubieniu.

Konwencje formatowania do stron podręcznika opisujących funkcje
W przypadku stron podręcznika opisujących funkcje (zwykle w sekcji 2 i 3), argumenty zawsze są podawane
kursywą, nawet w rozdziale SKŁADNIA, w którym reszta funkcji jest podana w pogrubieniu:

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

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

Każde odwołanie do programu, funkcji itp. będących tematem bieżącej strony podręcznika, powinno być
zapisane czcionką pogrubioną, po której 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).

Używanie semantycznych przełamań wierszy
W źródłach strony podręcznika nowe zdania powinny rozpoczynać się od nowego wiersza, długie zdania należy
przełamać zgodnie z interpunkcją (na przecinkach, dwukropkach itp.), a długie zdania podrzędne należy
podzielić na wyrażenia. Ta konwencja zwana czasem "semantycznym przełamaniem wiersza" ułatwia
zwizualizowanie łatek, które często działają na poziomie poszczególnych zdań, zdań podrzędnych lub
wyrażeń.

Listy
Występują różne rodzaje list:

Oznaczone zdania
Używane do listy znaczników i ich opisów. Gdy znaczniki są stałymi (makrami lub liczbami) są
pogrubione. Proszę korzystać z makra .TP (ang. Tagged Paragraph).

Niniejszy podrozdział "Oznaczone zdania" jest dobrym przykładem tego typu listy.

Listy numerowane
Elementy są poprzedzone liczbą w nawiasie (1), (2). Oznaczają listę kroków posiadających określoną
kolejność.

Jeśli występują podkroki, są numerowane jako (4.2).

Listy pozycyjne
Elementy są poprzedzone liczbą (indeksem) w nawiasach kwadratowych [4], [5]. Oznaczają pola w
zestawie. Pierwszym indeksem będzie:

0 Jeśli reprezentuje pole w strukturze danych C, aby zachować spójność z tablicami.
1 Gdy reprezentuje pole pliku, aby zachować spójność z narzędziami takimi jak cut(1).

Listy alternatywne
Elementy są poprzedzone literami w nawiasie (a), (b). Reprezentują zestaw (zwykle) rozłącznych
alternatyw.

Listy punktowane
Elementy są poprzedzone symbolem punktora (\[bu] - ang. bullet). Zwykle oznaczane jest w ten
sposób wszystko, co nie pasuje do innych typów list.

Uwagi numerowane
Nie są to tak naprawdę listy, ale składnia jest identyczna do "list pozycyjnych".

Pomiędzy symbolem listy a jej elementami powinny być dokładnie 2 spacje. Nie dotyczy to "oznaczonych
zdań", korzystających z domyślnych reguł wcięć.

Konwencje formatowania (ogólne)
Akapity należy rozdzielać odpowiednimi markerami (zwykle .P albo .IP). Nie należy rozdzielać akapitów
pustymi wierszami, gdyż powoduje to nieprawidłowe renderowanie w niektórych formatach wyjściowych (takich
jak PostScript i 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.

Przy pokazywaniu przykładowej sesji powłoki, wejście użytkownika należy pogrubić, na przykład

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

• Są sprzeczne opinie na temat "acknowledgement" i "acknowledgment". To drugie dominuje, ale nie jest
uniwersalnie stosowane w amerykańskim agielskim. Pierwsze jest stosowane przez POSIX oraz w licencji
BSD. W projekcie Linux man-pages używa się "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.
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) i należy je formatować za
pomocą makr .EX i .EE oraz otoczyć odpowiednimi znacznikami akapitów (.P albo .IP). Przykład:

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

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 Do epoki Uniksa
(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 Chyba że odnosi się do
wyniku "uname -m" itp.
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, wskaźnik null i bajt 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.", "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.

Tworzenie optymalnych glifów
Gdy wymagany jest prawdziwy znak minus (np. w przypadku liczb takich jak -1, w przypadku strony
podręcznika zawierającej odniesienia do innych stron takie jak utf-8(7) 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.

Użycie prawdziwego znaku minusa ma na celu:

• Lepsze renderowanie w sytuacjach innych niż terminal ASCII, w szczególności w PDF i na terminalach
Unicode/UTF-8.

• Generowanie glifów, które po skopiowaniu z wyrenderowanych stron utworzą prawdziwy znak minusa przy
wklejeniu na terminal.

Aby utworzyć znak pojedynczego prostego cudzysłowu który wyświetla się poprawnie w stronach ASCII, UTF-8
i PDF proszę używać "\[aq]" ("cytowania apostrofu") np.

\[aq]C\[aq]

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

Tam, gdzie wymagany jest prawidłowy znak karety (^) renderujący się poprawnie w terminalu i w PDF-ie,
proszę użyć "\[ha]". Jest to szczególnie konieczne w przykładach kodu, aby uzyskać prawidłowe
renderowanie karety w formacie PDF.

Surowy znak "~" daje kiepskie renderowanie w PDF-ie. Zamiast tego należy użyć "\[ti]". Jest to
szczególnie konieczne w przykładach kodu, aby uzyskać prawidłowe renderowanie w formacie 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.

• Przykładowe programy powinny być krótkie (dobry przykład często można zademonstrować w mniej niż 100
wierszy kodu), choć w niektórych przypadkach do prawidłowego zilustrowania użycia API konieczne są
dłuższe programy.

• Zalecany jest kod ekspresywny.

• Tam gdzie to przydatne, należy stosować komentarze. Całe zdania w komentarzach zamieszczanych w
oddzielnych wierszach należy zakończyć kropką. Kropki należy zwykle unikać w komentarzach wtrąconych
(stosowanych w tym samym wierszu co kod); są one zresztą zwykle krótkimi równoważnikami, a nie pełnymi
zdaniami.

• 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ższych 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

       Tłumaczenie   niniejszej   strony   podręcznika:  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   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.

Linux man-pages 6.9.1                          15 czerwca 2024 r.                                   man-pages(7)