| man-pages(7) | Miscellaneous Information Manual | man-pages(7) |
man-pages - konwencje pisania linuksowych stron podręcznika ekranowego
man [sekcja] tytuł
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 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:
Argumenty komendy są następujące:
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.
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.
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.
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:
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:
int tcsetattr(int fd, int optional_actions,
const struct termios *termios_p);
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);
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.
Proszę zauważyć, co następuje:
Aby zobaczyć zastosowania powyższych uwag, należy sprawdzić źródła różnych stron podręcznika.
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").
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.
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).
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ń.
Występują różne rodzaje list:
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ęć.
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.
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 Unikod w Linuksie
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
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.
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
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.
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.
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.
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:
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.
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:
indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
exit(0); exit(1); return n;
.SS Kod źródłowy programu
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)
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.
| 15 czerwca 2024 r. | Linux man-pages 6.9.1 |