MAN-PAGES(7) | Podręcznik programisty Linuksa | MAN-PAGES(7) |
man-pages - konwencje pisania linuksowych stron podręcznika ekranowego
man [sekcja] tytuł
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 podręcznika man są tradycyjnie definiowane następująco:
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.
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.
Pierwszą komendą strony podręcznika powinno być polecenie TH:
The arguments of the command are as follows:
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 | |
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] |
ZGODNE Z | |
UWAGI | |
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.
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.
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").
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.
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).
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.
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).
Control characters should be written in bold face, with no quotes; for example, ^X.
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ć.
Klasyczny schemat zapisu wersji BSD to x.yBSD, gdzie x.y to wersja (np. 4.2BSD). Proszę unikać form takich jak BSD 4.3.
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
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
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 | |
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.
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 |
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
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 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
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", "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.
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.
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
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.
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.
To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, use "\(aq" ("apostrophe quote"); for example
\(aqC\(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.
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:
Włączając sesję powłoki pokazującą użycie programu lub innej właściwości systemu:
Przykłady wyglądu przykładowych programów można znaleźć w wait(2) i pipe(2).
Wzorcowymi przykładami tego, jak powinny wyglądać strony podręczników z pakietu man-pages, są strony pipe(2) i fcntl(2).
man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)
Angielska wersja tej strony pochodzi z wydania 5.10 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/.
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 lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres manpages-pl-list@lists.sourceforge.net.
13 sierpnia 2020 r. | Linux |