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.
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.
NAME
SYNOPSIS
CONFIGURATION [Normally only in Section 4]
DESCRIPTION
OPTIONS [Normally only in Sections 1, 8]
EXIT STATUS [Normally only in Sections 1, 8]
RETURN VALUE [Normally only in Sections 2, 3]
ERRORS [Typically only in Sections 2, 3]
ENVIRONMENT
FILES
VERSIONS [Normally only in Sections 2, 3]
ATTRIBUTES [Normally only in Sections 2, 3]
CONFORMING TO
NOTES
BUGS
EXAMPLES
AUTHORS [Discouraged]
REPORTING BUGS [Not used in man-pages]
COPYRIGHT [Not used in man-pages]
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. |
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. |
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 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. |
EXAMPLES
Jeden lub więcej przykładów opisujących, jak funkcja, plik lub polecenie są używane.
For details on writing example programs, see Example programs below.
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).
REPORTING BUGS
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.
COPYRIGHT
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.
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, and long sentences should split into
lines at clause breaks (commas, semicolons, colons, and so
on). 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 or sentence clauses.
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. |
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 Unicode under Linux
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.
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.
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
In general, the use of abbreviations such as
"e.g.", "i.e.", "etc.",
"cf.", and "a.k.a." should be avoided,
in favor of suitable full wordings ("for example",
"that is", "compare to", "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
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.
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!). 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:
* |
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)
O STRONIE
Angielska wersja tej strony pochodzi z wydania 5.07 projektu Linux man-pages. Opis projektu, informacje dotyczące zgłaszania błędów oraz najnowszą wersję oryginału można znaleźć pod adresem https://www.kernel.org/doc/man-pages/.
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Przemek Borys <pborys [AT] dione.pl>, Robert Luberda <robert [AT] debian.org> i Michał Kułach <michal.kulach [AT] 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 <manpages-pl-list [AT] lists.net>.